LFForm API Events

The LFForm object provides a global interface for accessing Laserfiche form elements and events using JavaScript. Through simple functions, you can find a specific field, retrieve the field values, and update field contents. You also have access to events both at the individual field level as well as the form submission event.

API References

Dive deeper into specific areas of the LFForm API:

• Read API

  Learn how to retrieve field values and find fields.

• Write API

  Discover how to modify fields and handle operations.

• Events API

  Subscribe to and handle form, field, and lookup events.

• Properties API

  Understand runtime form properties and state.

Additional Resources

• Recipes

  Learn more about common patterns and solutions.

• Custom HTML guide

  Check out our custom HTML and sandbox integrations.

Examples

const formFields = {
  approvalComments: { fieldId: 120 },
  firstName: { fieldId: 10 },
  triggerField: { fieldId: 130 },
  lookupTarget: { fieldId: 131 },
};

LFForm.subscribe('fieldChange', () => console.log('changed'), formFields.firstName);
LFForm.unsubscribe('fieldChange', formFields.firstName);

LFForm.onFormSubmission((event) => {
  const action = event?.data?.action?.value;
  const comments = LFForm.getFieldValues(formFields.approvalComments);
  if (action === 'Reject' && !comments) {
    return { error: 'Comments are required when rejecting.' };
  }
});

LFForm.onLookupTrigger(() => {
  if (LFForm.getFieldValues(formFields.triggerField) === 'NoCall') {
    return { cancelLookup: true };
  }
}, { lookupRuleId: 3 });

LFForm.onLookupDone(() => {
  if (LFForm.getFieldValues(formFields.lookupTarget) === 'Hello') {
    LFForm.setFieldValues(formFields.lookupTarget, 'World!');
  }
}, { lookupRuleId: 2 });

LFForm.onFieldChange(() => console.log('change'), { variableName: 'Single_Line' });
LFForm.onFieldBlur(() => console.log('blur'), { variableName: 'Single_Line' });

LFForm.onFormSubmission((event) => {
  if (event?.data?.action?.value === 'Reject') {
    return { error: 'Please add approval comments before rejecting.' };
  }
});

Identification Objects

Identification objects are objects containing information identifying which fields the interface should act on. Identification objects can have the following properties:

• trackId: A unique identifier for a field. Note that the trackId is generated on field creation, so it won't be the same between different submission events.
  

  Example: {trackId: "59783b47-db11-4709-ba5a-1fb4833a1f73"}

• fieldId: The field ID of a field.

  Example: {fieldId: 1}

• variableName: The name of the variable associated with the field.

  Example: {variableName: "First_Name"}

• variableId: The id of the variable associated with the field.

  Example: {variableId: "e7c9e10c-eeb0-4ce2-b3c6-26264c7fe655"}

• index: If the field is in a collection or table, you can specify the index to get the exact field.

  Note: The index starts from 0.

  Example: {fieldId: 2, index: 2}

Note: In all LFForm interfaces, you can specify an array of identification objects instead of just one object to target multiple fields.

Example: LFForm.getFieldValues([{fieldId: 2}, {fieldId: 3}]).

Table/Collection Row/Set Templates

For tables and collections, a form stores the definition for each row or set as a template. These templates are used to generate the row or set whenever they are added. Some of the interfaces in the LFForm object have the ability to affect the template of the field, with the ability to apply changes to future rows or sets.

For these interfaces, when your ID object specifies an index (for example {fieldId: 3, index: 1}), the change will only be applied to the field at the specified index. If your ID object does not specify an index (for example {fieldId: 3}), the change will be applied to the template, and will be applied to all existing and future rows or sets.

subscribe

Subscribe to an event for a specific field.

• Signature: LFForm.subscribe(eventName, handler, options)
• Input:
  • eventName: The name of the event. Currently supports "formSubmission", "fieldChange", "fieldBlur", "lookupTrigger", and "lookupDone" events.
  • handler: The function to call when events are triggered.
  • options: An identification object to identify the field to subscribe to. You could also add "handlerName" in the object to more easily identify the handler.
• Output: none

unsubscribe

Unsubscribe from events.

• Signature: LFForm.unsubscribe(eventName, options)
• Input:
  • eventName: The name of the event. Currently supports "formSubmission", "fieldChange", "fieldBlur", "lookupTrigger", and "lookupDone" events.
  • options: An identification object to identify the handler.
• Output: none

onFormSubmission

Subscribe to the formSubmission event.

• Signature: LFForm.onFormSubmission(handler, options)
• Input:
  • handler: The function to call when a submission is triggered. To block a submission, return an object with an error property describing the error message. This function can optionally return a promise that resolves with the error object. The promise will be awaited before submission automatically.
    • The handler takes in an event argument that contains the user’s intended submission action in the data.action property.
  • options: Optional. Can be used to specify the handler name. For example, {handlerName: "submissionHandler1"}
• Output: none

onFieldChange

Subscribe to the change event for the specified fields.

• Signature: LFForm.onFieldChange(handler, options)
• Input:
  • handler: The function to call when a specific field changes.
  • options: An object that identifies the field to subscribe to and to specify the handlerName if needed.
• Output: none

onFieldBlur

Subscribe to the blur event for the specified fields.

• Signature: LFForm.onFieldBlur(handler, options);
• Input:
  • handler: The function to call when a specific field blurs.
  • options: An object that identifies the field to subscribe to and to specify the handlerName if needed.
• Output: none

onLookupTrigger

Subscribe to a lookup trigger event.

• Signature: LFForm.onLookupTrigger(handler, options)
• Input:
  • handler: The function to call when a lookup is triggered.
  • options: An object that identifies which lookup rule this handler would be called for and to specify the handlerName if needed.
• Output: none

LFForm.onLookupTrigger(function () {
    if (LFForm.getFieldValues({variableName: "TriggerField"}) === "NoCall") {
        return {cancelLookup: true};
    }
}, {lookupRuleId: 3}); // When lookup rule 3 is triggered, 
                   // if field with variable name "TriggerField" has value of "NoCall", 
                   // cancel the lookup call.

onLookupDone

Subscribe to the lookup done event.

• Signature: LFForm.onLookupDone(handler, options)
• Input:
  • handler: The function to call when a lookup is triggered.
  • options: An object that identifies which rule this handler would be called for and to specify the handlerName if needed.
• Output: none

LFForm.onLookupDone(function () {
    if (LFForm.getFieldValues({variableName: "Lookup_Target"}) === "Hello") {
        LFForm.setFieldValues({variableName: "Lookup_Target_AutoComplete"}, "World!");
    }
}, {lookupRuleId: 2}); // after lookup rule 2 is done, check for Lookup_Target value. 
                   // If it is "Hello", set the Lookup_Target_AutoComplete to "World!"