The LFForm Object

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.

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.

The LFForm Properties

The LFForm object contains the following properties that describe the current process information at runtime. They can be used to conditionally perform actions in JavaScript code.

step: {id: string, name: string} or null if it doesn't exist.

• The current step name of the process with any tokens processed. For example, “{/dataset/approver_name} Approval Task” would be “John Doe Approval Task”.

stage: {id: string, name: string} or null if it doesn't exist.

• The current stage name as defined in the process diagram.

language: string or null if it doesn't exist.

• The language selected in the user’s Laserfiche account.

locale: string or null if it doesn't exist.

• The locale selected in the user’s Laserfiche account.

isCloud: Boolean

• Whether or not the form is hosted in a Laserfiche Cloud environment.

isPreview: Boolean

• Whether or not the form was opened in preview mode.

isReadonly: Boolean

• Whether or not the form is set to read-only. For instance, the user task step was configured to display the form as read-only.

isDisabled: Boolean

• Whether or not the form was opened from an unassigned task or by a user not assigned to the task.

isPrint: Boolean

• Whether or not the form is being rendered as a PDF or raster image for a save to repository activity, an email task, or is being downloaded by a user.

isAnonymousUser: Boolean

• Whether or not the form is public and currently being accessed by an unknown user.

isDraft: Boolean

• If the form was saved as a draft and has been reopened this will be true, otherwise this will be false.

pageURL: string

• The current active URL of the loaded form.

The LFForm Interfaces

getFieldValues

Gets the value of the specified fields.

• Signature: LFForm.getFieldValues(id)
• Input:
  • id: An identification object or array of identification objects that have the desired fields.
• Output:
  • If there is only one field matching an identification object, returns the data of that field.
  • If there are multiple fields that match an identification object (fields in a collection or table, for instance), returns an array of data for all matching fields.

setFieldValues

Sets the value of the specified fields.

• Signature: LFForm.setFieldValues(id, value)
• Input:
  • id: An identification object or array of identification objects.
  • value: The value to set the field value to.

    Note: Different field types expect different values:

    • SingleLine, MultiLine, Dropdown, RichText, and Signature fields expect a string.
    • Number fields expect a number.
    • Checkbox fields expect an object with a "value" property. For example: {value: ["Choice_1", "Choice_3"]}, {value: ["Choice_1", "_other"], otherChoiceValue: "Hello"}
    • Radio button fields expect an object with a "value" property. For example: {value: "Choice 2"}, {value: "_other", otherChoiceValue: "Hi"}
    • Geolocation fields expect an object with "latitude" and/or "longitude" properties. For example: {latidude: 12, longitude: 34}
    • Address fields expect an object with "address1", "address2", "city", "country", "province" and/or "zipcode" properties. Example: {address1: "3545 Long Beach Blvd", city: "Long Beach", province: "California"}
    • DateTime fields expect an object with a "dateStr" property. A "timeStr" property is optional and only applied when Show Time is enabled for the field. For example: {dateStr: "2021-11-19", timeStr: "10:30:00 AM"}
    • Time fields expect an object with a "timeStr" property. For example: {timeStr: "11:30:25 PM"}
    • Collection, Table, FileUpload and Fileset fields are currently not supported.

    Note: If a field is set as read only, its value can not be changed.

• Output:
  • A promise that resolves when the values are set or errors are returned.

showFields

Shows the specified fields. This function can affect table/collection row/set templates.

• Signature: LFForm.showFields(id (, id2, id3...))
• Input:
  • id: An identification object or array of identification objects. You can specify multiple objects for this function.
• Output:
  • A promise that resolves after the fields are displayed or errors are returned.

hideFields

Hides the specified fields. This function can affect table/collection row/set templates.

• Signature: LFForm.hideFields(id (, id2, id3...))
• Input:
  • id: An identification object or array of identification objects. You can specify multiple objects for this function.
• Output:
  • A promise that resolves after fields are hidden or errors are returned.

disableFields

Disables the specified fields. This function can affect table/collection row/set templates.

• Signature: LFForm.disableFields(id (, id2, id3...))
• Input:
  • id: An identification object or array of identification objects. You can specify multiple objects for this function.
• Output:
  • A promise that resolves after fields are disabled or errors are returned.

enableFields

Enables the specified fields. This function can affect table/collection row/set templates.

• Signature: LFForm.enableFields(id (, id2, id3...))
• Input:
  • id: An identification object or array of identification objects. You can specify multiple objects for this function.
• Output:
  • A promise that resolves after fields are enabled or errors are returned.

changeFieldSettings

Changes settings on the specified fields. This function can affect table/collection row/set templates.

• Signature: LFForm.changeFieldSettings(id, settingChanges)
• Input:
  • id: An identification object or array of identification objects.
  • settingChanges: An object with the property to change as the key and the value to change to as the value.

    Currently supported properties (keys):

    • label: Change the field label. Accepts a string. Also supports table column labels and page names.
    • description (alias: textAbove): Change the field description. Accepts a string.
    • subtext (alias: textBelow): Change the field subtext. Accepts a string.
    • tooltip: Change the field tooltip. Accepts a string.
    • placeholder: Change the field placeholder. Accept a string.
    • autoCompleteValues: Only for Single Line fields. Change the auto complete dropdown options. Accepts an array of strings.
    • content (alias: default, HTMLContent): Only for Custom HTML fields. Change the content of custom HTML. Accepts a string.
    • CSSClasses (alias: cssClasses, classNames): Change the field CSS classes. Accepts a string or an array of strings. You can specify multiple CSS classes with a space-separated string.
    • buttonLabel (alias: signButtonLabel, uploadButtonLabel): Only for File Upload and Signature fields. Change the button label. Accepts a string
    • rowLabels (alias: addButtonLabel, addRowButtonLabel, addSetButtonLabel): Only for Table fields. Changes the row labels. If fixed row count, accepts an array of strings. If dynamic row count, Accepts a string.
    • addButtonLabel (alias: addRowButtonLabel, addSetButtonLabel): Only for Table and Collection fields. Changes the add row/set label. Accepts a string. Still supports {n} dynamic numbering
    • prevButton: Only for Page fields. Changes the previous button label. Accepts a string.
    • nextButton: Only for Page fields. Changes the next button label. Accepts a string.
    • addressOptions: Only for Address fields. Changes the address sub labels and its visibility. Accepts an array of object with this format: {subField: "address1", label: "New Label", show: true}

      Note: subField expects a string with "address1", "address2", "city", "country", "province" and/or "zipcode" properties.

• Output:
  • A promise that resolves after settings changes have been applied or errors are returned

changeFormSettings

Change the settings on the form.

• Signature: LFForm.changeFormSettings(changes)
• Input:
  • changes: An object with the property to change as the key and the value to change to as value.

    Currently supported properties (keys):

    • title: Change the form title. Accepts a string.
    • description: Change the form description. Accepts a string.
    • pagination: Change the page label and previous/next button labels. Accepts an array of objects in the following format { pageId: 1, label: "First Page", prevButton: "Back", nextButton: "Forward" }

• Output:
  • A promise that resolves after the form settings changes have been applied or errors are returned.

changeActionButton

Change the label of a single action button. Buttons include the Submit, Approve, and Reject submission actions, the Save as Draft button, and user defined custom submission action buttons on forms used by message start events and user tasks.

• Signature: LFForm.changeActionButton(button, changes)
• Input:
  • button: A string that identifies the button by the Button CSS Class defined in the user task settings Form tab.

    Currently supported class names:

    • Submit
    • Approve
    • Reject
    • SaveAsDraft
    • User defined submission action button class names

  • changes: An object with attributes to change.

    Currently supported properties (keys):

    • label: Option label. Accepts a string.

• Output:
  • A promise that resolves after the change to the action button has been applied or errors are returned.

changeActionButtons

Change the label of a list of action buttons. Buttons include the Submit, Approve, and Reject submission actions, the Save as Draft button, and user defined custom submission action buttons on forms used by message start events and user tasks.

• Signature: LFForm.changeActionButtons(changes)
• Input:
  • changes: An array of objects with attributes to change.

    Currently supported keys:

    • action: A string that identifies the button by the Button CSS Class defined in the user task settings Form tab.

      Currently supported class names:

      • Submit
      • Approve
      • Reject
      • SaveAsDraft
      • User defined submission action button class names

    • label: Option label. Accepts a string.

• Output:
  • A promise that resolves after the changes to action buttons have been applied or errors are returned.

addRow, addSet

Adds new rows or sets to a table or collection.

• Signature: LFForm.addRow(id, count); LFForm.addSet(id, count);
• Input:
  • id: An identification object or array of identification objects. Only tables or collections can be targetted for these APIs.
  • count: The number of rows or sets to add.
• Output:
  • A promise that resolves after the rows or sets have been added.

deleteRow, deleteSet

Deletes the specified rows or sets from a table or collection.

• Signature: LFForm.deleteRow(id, index (, index2, index3...)); LFForm.deleteSet(id, index (, index2, index3...));
• Input:
  • id: An identification object or array of identification objects. Only tables or collections can be targetted for these APIs.
  • index: The index of the row or set to remove. The index starts at 0. You can specify multiple indices.
• Output:
  • A promise that resolves after the rows or sets have been deleted.

addCSSClasses

Adds CSS classes to the specified fields. This function can affect table/collection row/set templates.

• Signature: LFForm.addCSSClasses(id, CSSClasses)
• Input:
  • id: An identification object or array of identification objects.
  • CSSClasses: The CSS classes to add. Can be a string or an array of strings. You can specify multiple CSS Classes with a space-separated string.
• Output:
  • A promise that resolves after the CSSClasses have been added.

removeCSSClasses

Removes the specified CSS classes from the specified fields. This function can affect table/collection row/set templates.

• Signature: LFForm.removeCSSClasses(id, CSSClasses)
• Input:
  • id: An identification object or array of identification objects.
  • CSSClasses: The CSS classes to remove. Can be a string or an array of strings. You can specify multiple CSS Classes with a space-separated string.
• Output:
  • A promise that resolves after CSSClasses have been removed.

findFields

Finds any fields that satisfy the specified arbitrary conditions.

• Signature: LFForm.findFields(predicate)
• Input:
  • predicate: A function that takes in the field State and should return true for fields you want to find, and false for fields you don't want to find.
• Output:
  • An array of fields that satisfy the predicate.

findFieldsByClassName

Finds fields with the specified CSS class.

• Signature: LFForm.findFieldsByClassName(className)
• Input:
  • className: The CSS class that is assigned to the fields you want to find.
• Output:
  • An array of fields with the specified CSS class.

findFieldsByFieldId

Finds the fields with the specified field ID.

• Signature: LFForm.findFieldsByFieldId(fieldId)
• Input:
  • fieldId: The field ID of the fields you want to find.
• Output:
  • An array of fields with specified field ID.

findFieldsByVariableName

Finds the fields with the specified variable name.

• Signature: LFForm.findFieldsByVariableName(variableName)
• Input:
  • variableName: The variable name of the fields you want to find.
• Output:
  • An array of fields with the specified variable name.

findFieldsByVariableId

Finds the fields with the specified variable ID.

• Signature: LFForm.findFieldsByVariableId(variableId)
• Input:
  • variableId: The variable ID of the fields you want to find.
• Output:
  • An array of fields with the specified variable ID.

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!"