LFForm Write API

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.

Remarks

All mutating methods return Promise<LFFormPromiseResponse> unless noted otherwise. Await these calls to ensure changes are applied before continuing.

Examples

await LFForm.setFieldValues({ fieldId: 10 }, 'hello');
await LFForm.showFields({ fieldId: 10 });
await LFForm.changeFieldSettings({ fieldId: 10 }, {
  label: 'First Name',
  placeholder: 'Enter your first name',
});
await LFForm.changeFormSettings({
  title: 'Expense Report',
  description: 'Complete all required fields.',
});

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.

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: {latitude: 12, longitude: 34}
    • Address fields expect an object with "address1", "address2", "city", "country", "province" and/or "zipcode" properties. Example: {address1: "123 Sample Street", city: "Sample City", province: "Samplestate"}
    • 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.
    • browserTitle: Change the browser's window or tab title. Accepts a string. Note: The page/tab title will be updated to the value provided appended with " | Laserfiche"
    • 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.

validateFields

Sets or removes the specified validation settings from the fields with the specified field ID.

• Signature: LFForms.validateFields(id, vallidationRule)
• Input:
  • id: An identification object or array of identification objects. You can specify multiple objects for this function.
  • validationRule: An object with the property to change as the key and the value to change to as the value.

    Currently supported properties (keys):

    • Required (Boolean): Change the required state of the field.

• Output: A promise that resolves after changes are applied or errors are returned.