Smart Form Java Script API
With Single Script Smart Forms you have the ability to change features on said form which enhance the user experience. These can be showing or hiding elements when submitting a form, pre-populating of fields for users, and even setting events to store cookies independently of Gator.
_gf
_gf is an object that is added to the DOM by the Smart Form Single Script when it is loaded. All Smart Form Single Script API functions are added to it.
It's important that any API functions called on your site are not run until _gf is fully initialised. For this reason, we recommend copying and extending the below snippet, which periodically checks for the _gf object and forms to be ready before using them
<p>// define a simple polling function to wait for a callback to return true
function waitFor(checkingCallback, doneCallback) {
var interval = setInterval(function() {
if(checkingCallback()) {
doneCallback();
clearInterval(interval);
interval = null;
}
}, 300);
}
// we wait for the _gf object and the _gf.ready function to be defined
// before calling _gf.ready with a form id of 1
// make sure you change 1 to the id of your form
waitFor(
function() { return _gf && _gf.ready && _gf.ready(1) },
function() {
// example usage below
_gf.setFieldValue(1, 'foo', 'bar');
}
);</p>_gf.formOptionsOverride
Property for overriding certain form options.
In some cases you may want to override form options on a certain page on your website. Some options need to be set before a form is ready (such as allowing for hidden fields to be pre-populated) so we must "lay" our overrides out before the form is ready, and potentially before _gf is fully initialised too.
Use the below snippet as guide on how to do this. Please note that this should not be done within the waitFor function discussed earlier.
<p>var id = "1"; // get the form id that the overrides will be set for
// create an object that holds the override for each form
// this can hold multiple form override settings
var formOptionsOverride = {
[id]: { // use the form id as a key
prePopHiddenFields: true
}
};
// combine the existing value of _gf with the formOptionsOverride
// we do this to ensure all properties of _gf are saved, whether or not
// _gf is already initialised
var _gf = Object.assign({formOptionsOverride}, _gf || {});
// if required, define your waitFor function below here...</p>The below table shows the possible option overrides for a form.
| Name |
Description |
Example |
|---|---|---|
| prePopHiddenFields |
A boolean representing if hidden fields should be pre-populated on load. By default, hidden fields are not pre-populated so this must be set to true if that is required. |
true | false |
_gf.ready
Evaluate if a given form is ready to be used via other API functions. Returns true if the form is ready, otherwise false.
The Smart Form Single Script API is added to the DOM on page load, but it's possible code you write using the API is run before that happens. Call this function, passing in the id of a form on the page, to ensure the API and the form are ready to be used.
formId - the id of the form to check for
<p>_gf.ready(1);</p>_gf.on
Provide an event callback to be run at key points during a form’s submission process.
Use this to extend and customise the default form functionality. Use the event names below to tap into the form process at specific times.
validationerror - when the form has been submitted by the user, but a validation error occurred on at least one input in the form.
validate - when the form has been filled correctly, you can add custom validation here to decide whether to send the form or not. Stop the form from submitting by providing a callback that returns false.
submit - when the form has been filled correctly and is about to be posted to GatorMail.
success - when the form was successfully submitted to GatorMail.
failure - when the form was submitted to GatorMail but an error occurred.
complete - runs after either a successful or failed submission.
If a success or failure event callback is defined for a form, its success/failure messages will not show up.
formId - the id of the form this callback should be used with.
eventName - the name of the event that this callback should be triggered on e.g. validationerror, submit, success, failure, complete
callback - the function to be run when the event is triggered. This function can take the form object and an array of the inputs with their values and validation results as parameters (examples below)
<p>_gf.on(1, ‘validationerror’, function(form, values) {
// check through the values array for which inputs failed validation when form 1 fails validation
});
_gf.on(2, ‘success’, function(form, values) {
// replace the form HTML with a personalised thank you message when form 2 is successfully submitted
});
_gf.on(3, ‘complete’, function(form, values) {
// use this if other code is waiting for form 3 to complete, such as a custom loader icon
});</p>_gf.findForms
Rescan the DOM for newly added Smart Form shortcodes.
The Smart forms script will load forms for any shortcodes it finds on page load, but shortcodes added to the DOM after this will not be loaded. Use this function to get Smart Forms to recheck and load your forms. This is best used on Single Page Applications (SPAs) using React, Angular, Vue or similar.
No Parameters.
<p>_gf.findForms();</p>_gf.setField
Set options, including the value, for any field in a form.
Dynamically set options such as value, mandatory-ness and mandatory message for a given field.
formId the id of the form to set options for a field.
fieldName the name of the field to change. This should match the name of the field set in GatorMail.
options an object with options to change for the field (details below).
| Option |
Description |
Example |
|---|---|---|
| value |
A string representation of the new value to be set for the field. Set date values in the format “yyyy-MM-dd”. Alternatively, a callback function, with the current value provided as a parameter. Return the desired new value of the field from the function. |
"new value" function(currentValue) { return currentValue + " new value"; } |
| mandatory |
A boolean representing if this field should be mandatory (true if mandatory, false if not). |
true | false |
| mandatoryMessage |
A string representing the message to display to a form user if the field is mandatory but a value has not been provided. |
"please enter your details" |
<p>_gf.setField(1, 'my_text_field', { value: (currentValue) => currentValue + 'new value' });
_gf.setField(1, 'my_number_field', { value: '1' });
_gf.setField(1, 'my_date_field', { value: '2000-01-01'});
_gf.setField(1, 'my_text_field', { mandatory: true, mandatoryMessage: 'Please enter my text' });</p>_gf.getFieldValue
Get the value for any field in a form.
Get the value for any field in a form. This can be used to make form filling more interactive, such as changing icons when a field has a specific value.
formId the id of the form to get a field for.
fieldName the name of the field to get. This should match the name of the field set in GatorMail.
<p>let textFieldValue = _gf.getFieldValue(1, ‘my_text_field’);
// do something with that value.</p>_gf.setFieldValue [Deprecated]
Set the value for any field in a form. This function is deprecated, it will still work for existing forms but we would recommend using the _gf.setField() function instead.
Manually set the value of a field in a form, this can be used for all field types, including hidden fields.
formId the id of the form to set a field for.
fieldName the name of the field to change. This should match the name of the field set in GatorMail.
value the new value for the field represented as a string. Set date values in the format “yyyy-MM-dd”.
<p>_gf.setFieldValue(1, ‘my_text_field’, ‘new value’);
_gf.setFieldValue(2, ‘my_number_field’, ‘1’);
_gf.setFieldValue(3, ‘my_checkbox’, ‘true’);
_gf.setFieldValue(4, ‘my_date’, ‘2020-12-25’);</p>