Using Lookup-Related Events

Note: This page applies primarily to the classic form designer.

This topic describes custom events that indicate when lookups have started or finished loading. If you have custom processes that should begin only after lookups are complete, you can wait for the lookupcomplete or onloadlookupfinished event before starting those processes. This topic explains how these events work and provides examples of how you can use them in custom JavaScript.

The lookupcomplete event occurs when a lookup that was triggered by the user filling in certain rules or by the user clicking on an autofill button is complete. The onloadlookupfinished event occurs when lookups that started when the document was loaded have completed.

The lookupstarted event occurs when a lookup that was triggered by the user filling in certain fields or by the user clicking on an autofill button has started. You can use it to trigger a custom spinner or message to be displayed while the lookup is in progress. You can also use it to ensure that any custom JavaScript that changes the fields that trigger the lookup doesn't try to change those fields between lookupstarted and lookupcomplete. This avoids triggering unnecessary lookups.

Identifying Triggers and Rules for an Event

For lookupstarted and lookupcomplete, you can identify what triggered the lookup by using the properties triggerId and ruleId. If the lookup was triggered by one other input, then triggerId gives the id of that input. If the lookup was triggered by an autofill button, then triggerId gives the id of that button. ruleId identifies the rule that governs the lookup. To identify the ruleId for a specific lookup rule, access the browser console (developer tools) for your form. In the console, type jsonForm to present a JSON-formatted response. Expand the businessRules node to find the ruleIds for each lookup rule, together with other information about the lookup rule.

The following code sample illustrates the structure of one rule on a form

businessRules: Array(2)
  0:
    id: "533294f2-6cfa-4826-ad1e-2dd8ca00c012"
    inputMap: [{…}]
    isAutoFillHidden: true
    outputMap: (3) [{…}, {…}, {…}]
    pass: [2]
    populate: (3) [7, 16, 17]
    position: 1
    ruleId: "533294f2-6cfa-4826-ad1e-2dd8ca00c012" <-- example ruleId
    ruleMajorVersion: 2
    ruleName: "SampleRule"
    ruleType: 3
    serverName: "localhost"
    trigger: [2] <-- example triggerID
    type: 1
    __proto__: Object

Note: Prior to Forms 11 Update 4, ruleIds were not fixed; editing a lookup rule or adding a new lookup rule can change the ruleIds of all existing lookup rules. If you have custom scripts based on specific ruleIds, check their validity whenever you edit or add lookup rules. This no longer applies to Forms 11 Update 4 or later.

Hide a Waiting Message or Spinner when Lookup is Complete

While the form is doing a lookup, you may want to display a message or spinner, then hide it when the lookup is complete. Assuming that your waiting display has the class spinner, the following JavaScript will hide it when the lookup is complete:

$(document).ready(function () {
  $(document).on('lookupcomplete', function(event){
    if (event.triggerId == 'Field1') {
      $('.spinner').hide();
     //other actions
    }
  })
})

The code assumes that you are interested in the lookup that is triggered by the input with id Field1. If instead your lookup was triggered by an autofill button, then the triggerId you should look for is the id of the autofill button.

If your lookups are the kind that start when the page loads, use onloadlookupfinished rather than lookupcomplete. In this case, you would not need to look for a specific triggerId.

While we have only demonstrated how you can use lookup events for hiding a spinner, you can easily include other actions, as indicated by the comment in the JavaScript snippet. For example, you may want to perform certain calculations only when certain fields have been properly populated by a lookup, or you may want to pre-populate, show, or hide other fields based on the results of the lookup.

Populate Other Fields Based on Lookup Results

The following JavaScript sample shows you how you can populate a checkbox based on the results of a lookup. The lookup fills a numerical field. The JavaScript listens for the onloadlookupfinished event, then checks for the relevant ruleId (see Identifying Triggers and Rules for an Event for how to find ruleIds). If it finds that the correct rule has completed, it checks the value of the numerical field and fills the checkbox if that value is 1. The code assumes that the numerical field has been assigned the custom class NumberField, the ruleId of interest is 944, and the checkbox has been assigned the custom class Checkbox.

$(document).on("onloadlookupfinished", function(event) {
  if (event.ruleId==944) {
    if ($('.NumberField input').val() == 1) {
      $(this).find('.Checkbox input').attr('checked',true);
    }
  }
});

To implement the same feature with a lookup that depends on user input, use lookupcomplete instead of onloadlookupfinished.