Custom JavaScript (boxes): form submission functions

Some custom JavaScript functions at the box-level run exclusively as part of a synchronous form processing pipeline.

The order of execution of these actions are indicated by the dropdown in the HQ, as well as outlined in order here. Some additional (non-modifiable) steps are included, and indicated by the word "Native":

1. Native – Get all form data from the HTML form fields and Editor settings, and compile this into a form data object to use for further processing. No validation is performed at this point. This is simply data acquisition.

2. Before form validation return types –

   • boolean / false – Halts execution of form submission, and does no further processing.
   • boolean / true – Continue with standard/native validation and further processing.
   • string – Run the "showError(message)" function, which will show a red error bubble with the string you returned. Halts execution of form submission, and does no further processing. This can be useful if you want to run your own validation on some fields before standard/native validation occurs.
   • object – All form data that reaches the processing pipeline for a submission is represented as a single object. The entire form data object will be overwritten with the object you return here.

This skips data validation, so it would be up to you to run your own validation. If this is not acceptable, consider doing object modification in "After Form Validation" instead.

• return – Returning undefined (or null, or a number, or anything else, or nothing at all) will not take any action on the form data. Processing will continue with regular validation.

3. Native – Standard/native form validation runs if anything other than the following is returned from step 2 above false, string, object. Standard/Native validation simply checks for any fields marked “required” in the Editor, validates the Email field.

4. After Form Validation – return types –

   • boolean / false – Halts execution of form submission, and does no further processing.
   • boolean / true – Continue with further processing.
   • string – Run the "showError(message)" function, which will show a red error bubble with the string you returned. Halts execution of form submission, and does no further processing. This can be useful if you want to run your own validation on some fields after standard/native validation occurs.
   • object – All form data that reaches the processing pipeline for a submission is represented as a single object. The entire form data object will be overwritten with the object you return here.
   • return – Returning undefined (or null, or a number, or anything else, or nothing at all) will not take any action on the form data. Processing will continue with regular validation.

If your goal is to modify the form data object, then you must return an object from either “Before Form Validation” or “After Form Validation”. If you simply modify the object within your function, that is not enough. You must then return that object after you modify it. It is highly recommended that you do this in either “Before Form Validation” or “After Form Validation”. If you wait to do it in “Before Form Submit” that can alter the query string that is built and sent to our backend for post-processing. This would be a highly advanced procedure, mostly intended for internal staff to accomplish unanticipated use cases. Furthermore, it is most likely redundant to return an object from both “Before Form Validation” and “After Form Validation”. It is recommended to return an object from one or the other, if your goal is to modify the form data object.

If your goal is to modify the form data object, the common practice is to use the current form data object, then modify it, then return it. The current form data object can be referenced through the variable “x” which is passed to you as a reserved variable in all Custom JS (Boxes) functions.

5. Native – showLoading() – This shows the loading animation which indicates to the user that their form is in the process of submitting. If you really need to override this with an alternate loading animation, you can target “#modal_loading_spinner” in “After DOM Ready”. We will consider adding more loading animation options in the future.

6. Native – Build internal query string for backend post-processing. This is a combination of field metadata set in the Editor, and how that maps to specific data entered in the form (ie. the form object).

7. Before form submit return types:

   • boolean / false – Halts execution of form submission, and does no further processing.
   • boolean / true – Continue with submission of the form data to our backend for post-processing.
   • string – Run the “showError(message)” function, which will show a red error bubble with the string you returned. Halts execution of form submission, and does no further processing. This can be useful if you want to run your own validation on some fields after standard/native validation occurs.
   • object – All form data that reaches the processing pipeline for a submission is represented as a single object. The entire form data object will be overwritten with the object you return here.

It is not recommended to return an object here. Instead, use “Before Form Validation” or “After Form Validation”.

• return; – Returning undefined (or null, or a number, or anything else, or nothing at all) will not take any action on the form data. Processing will continue with submission of the form data to our backend for post-processing.

8. Native – Submission of the form data to our backend for post-processing.

9. After Form Submit – return types:

   • boolean / false – Halts execution of form submission, and does no further processing.
   • anything else, or nothing returned – No action taken, continue with “after submit” action, as defined in the Editor.

10. Native – Continue with “after form submit” action – As defined in the Editor (ie. change pages, redirect to url, etc).

11. Native – hideLoading() – Hides the loading animation

Custom JavaScript (boxes): inputs => (api, s, x)

Every custom JavaScript function receives the same three parameters as inputs (case sensitive):

1. api – This allows you to exchange data easily between Custom JS (Parent) and Custom JS (Boxes). For example, if you define “api.myCustomVar = true;” in Custom JS (Parent), then you will be able to detect the value of that variable simply by referencing it the same way in Custom JS (Boxes) “if (api.myCustomVar) return false;”. Just note that this “api” variable exchange between Parent and Child is time/sequence dependent, just as you would expect. So in this example, you may want to define “api.myCustomVar = true;” in Custom JS (Parent) – After Document Ready. That will ensure that your custom var is defined and accessible by the time any box-level functions run in the child.

2. x; – This is the “form data object” and only contains data for “Before Form Validation”, “After Form Validation”, “Before Form Submit”, and “After Form Submit”. For all other Custom JS (Boxes) functions, x will equal an object with no keys “{}”.

If your goal is to modify the form data object, common practice is to use the current form data object, then modify it, then return it. The current form data object can be referenced through the variable “x” which is passed to you as a reserved variable in all Custom JS (Boxes) functions, but only relevant for the “form processing functions” – Before/After Validation, and Before/After Submit. For example, let’s say that in “Before Form Validation” you wanted to grab the domain from the email address, and pass that in the form data as “custom_7”. You could use the following code for that: if (x.email && x.email.indexOf(“@”) > 0) {x.custom_7 = x.email.split(“@”)[1]; return x;}

Since you are doing this in “Before Form Validation” it will skip standard/native validation of the email address (but only if you end up finding an email address with an @ symbol in it, and returning the modified object “x”). On the other hand, if you don’t find a valid email with an @ symbol in it, then it will skip your custom object return, and will therefore run standard/native validation as though you never had any custom code written. So in the above case, if you want standard/native email validation to always run first, simply move the above code snippet to “After Form Validation”. Or use a combination of Before/After Form Validation as you see fit.

Notice how the variable “x” already contains “x.email” in the example above? That is because “x” is an object that contains all the form data at this point. We make all the form data available to you through the “x” object. If you want to see what data is included in “x”, simply do a “console.log(x)” and trigger the lightbox to run and submit the form. Then view the console to see what object properties are output (and therefore available to you).

Finally, note in the example above, that “custom_7” may not have originally been turned on in the Editor. But you can add additional properties to the “x” object as you see fit, even if they were never turned on in the Editor.

3. s – This is the object that contains most of the metadata about the lightbox being displayed, and will be provided for use in every Custom JS (Boxes) function.
   • s.protocol = PROTOCOL;
   • s.protocol_user_override = PROTOCOL_USER_OVERRIDE;
   • s.widget_type = WIDGET_TYPE;
   • s.primer_cache_version = PRIMER_CACHE_VERSION;
   • s.parent_url = PARENT_URL;
   • s.full_url = FULL_URL || "";
   • s.use_bugsnag = PRIMER_USE_BUGSNAG;
   • s.use_console = SHOW_ERRORS;
   • s.is_preview = IS_PREVIEW;
   • s.is_responsive = PRIMER_USE_RESPONSIVE;
   • s.is_variation = IS_VARIATION;
   • s.user_id = VENDOR_GUID;
   • s.user_guid = VENDOR_GUID;
   • s.vendor_id = VENDOR_GUID;
   • s.vendor_guid = VENDOR_GUID;
   • s.lightbox_id = LIGHTBOX_GUID;
   • s.lightbox_guid = LIGHTBOX_GUID;
   • s.lightbox_short_id = LIGHTBOX_SHORT_ID;
   • s.lightbox_name = LIGHTBOX_NAME;
   • s.variation_id = VARIATION_GUID;
   • s.variation_guid = VARIATION_GUID;
   • s.variation_short_id = VARIATION_SHORT_ID;
   • s.variation_name = VARIATION_NAME;
   • s.lightbox_or_variation_id = LIGHTBOX_OR_VARIATION_GUID;
   • s.lightbox_or_variation_guid = LIGHTBOX_OR_VARIATION_GUID;
   • s.lightbox_or_variation_short_id = (IS_VARIATION ? VARIATION_SHORT_ID : LIGHTBOX_SHORT_ID);
   • s.lightbox_or_variation_name = (IS_VARIATION ? VARIATION_NAME : LIGHTBOX_NAME);
   • s.is_desktop = IS_DESKTOP;
   • s.is_phone = IS_PHONE;
   • s.is_tablet = IS_TABLET;
   • s.is_mobile = IS_MOBILE;

Custom JavaScript (parent)

Common input parameters: (window, document, jQuery, api)

1. window – This is the outermost parent window context, under which the main website is functioning.

2. document – This is the outermost parent window’s document context, under which the main website is functioning.

3. jQuery – This is Primer's private jQuery context, which is completely separate from the parent window’s jQuery context. We use our own private jQuery context to ensure cross-site consistency of jQuery versioning in our platform. It also prevents jQuery conflicts with the parent website. You can also reference it these three ways: “jQuery”, “$”, or “JQUERY_PRIMER”

4. api – Use this to pass data back and forth between Custom JS (Parent) and Custom JS (Boxes). You can use this object to define custom functions and/or variables to use platform-wide, as you see fit. This “api” object also contains reference to our native functions which you can find under the following namespace: api.LIGHTBOX

Advanced use cases

Use these with caution. We cannot provide support if the below functions are misused.

The following native functions are available as advanced use cases.