Note: Nintex Apps data centers are located in West US and Australia (AUS). In-region processing of Nintex Apps data is only available in these regions.

Form

Nintex Apps's Form is a data component that allows you to view and edit a single record. In contrast to Tables, which show multiple records and allow for mass updates, the Form shows details for a specific record, which can be updated inline. If multiple records are present in the model, a Form will appear for each separate record.

Using the Form component

At its most basic level, the Form is used to edit fields on a single record. Using different properties and elements of the Form, however, it is possible to guide end users through the process of updating a record on a single page

After you add a Form to the page, adding columns, sections, and fields to the Form allows for a more specific user experience, directing users through the exact steps necessary to input or update required information. Columns, sections, and rows provide great control of where editable fields appear, but also affect the order in which items are read on a Nintex Apps page. When a Field is added within columns or sections, a row is generated containing that field. Fields add specific instruction or guidance through labels and additional prompts.

Columns

  • Add as many columns as you need by clicking the Add columns button in the Form header.

    • Columns are adjustable in the properties pane where you can change order, alignment, and responsive behavior.

  • Remove columns by clicking the column, then the delete Remove columns.

Sections

  • Add Sections by highlighting the Form component and clicking Add section.

    • Sections are adjustable in the properties pane where you can turn section titles on/off and edit section titles.

  • Remove Sections by clicking the section, then clicking delete Remove section.

Fields and rows

Add fields to sections by highlighting the section, clicking Add, and selecting Model fields from the dropdown menu.

  • Add a field you want end users to read, edit, or both from the model associated with the Form component, Javascript templates, images, or column sets.

  • Adding a field will generate a row.

    • Once a row is created, you can add additional fields to that row by clicking the row border, then clicking Add.

  • Rows have no configurable properties. When a row is selected, the Properties pane will be blank.

Buttons and images

Add a button group to a section by highlighting the section, clicking Add fields and selecting Button Group from the dropdown menu.

  • This inserts a button group directly into the Form at the selected location.
  • When you add buttons to the Form component, these buttons have their own properties. All Form button properties are the same as those for Ink Button Set buttons.

Add an image to a section by highlighting the section, clicking Add fields and selecting Image from the dropdown menu.

  • This inserts an image directly into the Form at the selected location.
  • When you add an image to the Form component, the image has its own properties. All Form image properties are the same as those for Ink Image components.

Column sets

Add column sets to a section by highlighting the section, clicking Add fields and selecting Add column set from the dropdown menu.

  • Add as many columns within the column set as you need by clicking the Add columns button in the column set header.

    • Columns are adjustable in the properties pane where you can change order, alignment, and responsive behavior.

  • Remove columns by clicking the column, then the delete Remove columns.

Form modes

Form modes determine how records display at runtime and how users can interact with those records. To set a mode, click the Form on the canvas and adjust the Default mode property.

Mode options include:

  • Read with inline-edit (default): Users can view records, but they can't edit until they click edit Edit. This is useful when users need to view previously created records and update their information, such as on record detail pages.
  • Edit: Records display in an editable state if the user has the appropriate permissions. Edit mode is best for new record experiences, which only require data entry instead of data viewing.
  • Read-only: Records display in an uneditable state regardless of the user's permissions. Read-only mode is best for pages that require information organized in a Form view, but only as a reference.

Example

This is an example page. Its data resets each time the page is loaded.

Best practices

  • While having Save/Cancel buttons directly above the Form may be useful in most cases, consider using one save button per page to remove visual clutter and reinforce how to save page data to the end user.
  • If your model contains many records or is a related list, consider using a Table component instead.
  • While Forms allow for focused form-filling, they are not very interactive. If the records on your page require extensive use of action flows, consider using a Button Set component for those actions, or using the Deck component instead.
  • There is no limit on how many fields you can add to a row, but it's best to only use two to three. Adding more than three fields makes the form content difficult to read and navigate.

Component actions

Component actions are available using Run component action.

Change Form mode

Changes the mode of the selected component.

  • Form mode: The mode to switch the selected component to. Available options include:
    • Edit
    • Read with in-line editing
    • Read-only
  • Toggle between this and the default mode: When enabled, this option does not set the component to a specific mode, but switches between the selected mode and the mode set in the component's Default mode property.

Other features

A character counter helps end users know when they are approaching the content limit for text entry fields and encourages them to make input more succinct. Nintex Apps property Show length counter adds a counter for string fields and the larger textarea fields:

  1. Click the string or textarea field within the component.
  2. In the Field Properties pane, check Show length counter.

When editing the field, end users will now see a character countdown ("25/ 128") that indicates the number of characters used (the first number) and how many total characters are allowed (the second number).

Note: 
  • The counter is enabled by default for standard textarea fields.
  • The counter is not available for Salesforce rich text area type fields.

Change the field character limits

When using the counter, the character limits are preset by the connection. (For example, Salesforce sets a limit of 128 characters for string fields, and 3200 characters for textarea fields). These limits are set by the field's metadata.

To change the limit:

  1. Click the model with the field whose limit you want to override, then click Fields.

  2. Click the specific textarea or string field.

  3. In the Field's Description pane, check Override field metadata.

    • Under Length, set the length to the desired number of characters.

  4. Click Save.

For more information on field metadata overrides, see Field Metadata Overrides topic.

Client-side validation

Client-side validation lets you validate a user's input against the field's expected format (e.g., email address, Social Security number, and more). Validation is client-side, which means the user doesn't have to save the form–and query the server–to be alerted that their input doesn't match the field's required format. If validation fails, error messages appear that advise users on how to fix the error. To learn more, see the Client-side validation doc.

Properties

Component properties

  • Model: The model that contains the fields the Form displays. Revisions made in the Form affect the model selected here.

  • Default mode: Select the default record interaction for end users. Options are:

    • Read with inline-edit (default): All fields will appear in read mode but can be edited on click if a user has permission to do so.
    • Edit: All available fields appear in edit mode on page load.

    Note:  Forms are most easily read in Edit mode.

    • Read-only: All fields appear in read-only mode regardless of user permissions.

  • ARIA label: Determines what description will be read by assistive technology, such as screen readers, by setting the aria-label HTML attribute, which is part of the Web Accessibility Initiative—Accessible Rich Internet Applications (WAI-ARIA) spec.

    Used to describe elements where text may not be visible, this property can be a specific string of text, the merge variables of one or more fields, or a combination of the two.

  • Show save and cancel buttons: If true, Save/Cancel options will appear allowing end users to save changes made within the Form. If false, the Save/Cancel buttons will not appear above the component.

  • Label position:

    • Top: The field's label displays above the field.

    • Left: The field's label displays to the left of the field.

      • Label minimum width and Label maximum width: Sets the lower and upper size limits for the label.
      • Label flex ratio: Sets the size of this label relative to the input field's width.
      • Input field/text minimum width and Input field/text maximum width: Sets the lower and upper size limits for the input field.
      • Input field/text flex ratio: Sets the size of this input field relative to the label's width.

      Note:  Setting a Form's Label position property to Left will override any Checkbox/Switch fields with a Label position specified.

  • Allow HTML in field labels and section headers: When the Allow HTML property is checked, any HTML markup within the column header label value will be parsed and rendered per the markup.

    It's also possible to use this feature for other, more advanced HTML elements.

Important:  While using custom HTML can allow for powerful customizations, it can come with risks. Custom HTML can result in unexpected behaviors. If you do use custom HTML, test your pages thoroughly in a sandbox environment after each Nintex Apps update.

  • Show errors inline: Display messages next to the field
  • Show inline error only on hover: Only displays the message inline if the end user hovers over the field.
  • Unique ID (optional): Nintex Apps automatically generates an alphanumeric ID for the component; if preferred, give it a practical name.

  • Style variant: Style variants are created and set in the Design System Studio. Some components have pre-defined variants for a specific aspect of a component's style. Also, Nintex Apps builders can style and customize elements to create their own themes within the DSS. These themes will dynamically populate as selectable values in the Style Variant dropdown menu.

    Note: 

    To refresh available style variant options, click refresh Refresh style variants.

    This is useful for when changes to the design system (like style variants or variable options) have been made in another browser window or by another user.

  • Margin: Sets a component's margin (the space around it) relative to other components on the page.

    • To set margins for all sides, click All.
    • To set margins for each side individually, click Separate.

    Margin values can be set to any configured spacing variable for the page's design system. Margin cannot be set an arbitrary value; it must use a design system variable.

Standard display logic options are available to display or hide the component or feature.

Nested elements

Column properties

  • Division behavior: Determines how the column will size itself in relation to other columns within the Form component.

    • Flexible width: Flexible width columns take up as much room as is available; when the screen size shrinks they also size down to their minimum width before wrapping within the Form component.

      • Flex ratio: This sets the size of this column relative to other columns. For example, if there are two columns in a Form component, and the flex ratio for each is 1, they will each take up ½ of the Form. If one has a flex ratio of 2, and the other has a flex ratio of 1, the first one occupies ⅔ of the Form, and the second one occupies ⅓ of it.
      • Minimum width: Sets the lower limit for the column's width. This can be specified using px, em, rem, %, vh, or vw measurements.

      Note:  Make sure the column's minimum width is at least as wide as its contents!

    • Fit to content: This sizes the column to fit the width of the content within the Form component.

    • Specified width: Sets a fixed width for the column.

      • Width: Sets the width of the column. This can be specified using px, em, rem, %, vh, or vw measurements.

  • Vertical align: Adjusts vertical alignment to top, center, or bottom of the column.

  • Change order: Adjusts the order in which columns appear from left to right.

  • ARIA label: Determines what description will be read by assistive technology, such as screen readers, by setting the aria-label HTML attribute, which is part of the Web Accessibility Initiative—Accessible Rich Internet Applications (WAI-ARIA) spec.

    Used to describe elements where text may not be visible, this property can be a specific string of text, the merge variables of one or more fields, or a combination of the two.

  • ARIA role: Determines which type of user interface element the component represents for assistive technology. The available options all refer to standard landmark ARIA roles. For more technical information on each role type, refer to MDN web docs.

    • Banner: Used for defining global site details, such as company name, global search, logos, and similar information.
    • Complementary: Used for content that, while related to the main content area, is not necessary for that main area to stand alone. Typically used for sidebars and other supplementary information.
    • Content Info: Used for footers that appear on each page, which typically contain copyright information, navigation items, or similar content.
    • Form: Used to identify sections that comprise a singular form--even though it may be comprised of multiple components.
    • Main: Used to identify primary focus of the page.
    • Navigation: Used to indicate a section containing links for navigating a site.
    • Region: Used as a more generic landmark in order to indicate an area is relevant, but not categorized under the other available roles.
    • Search: Used to indicate a section contains elements for searching the page or site.

Standard display logic options are available to display or hide the component or feature.

Section properties

  • Show section heading: Toggle section title text at the top of a section.
  • Section heading: Update text that appears in section header.

Standard display logic options are available to display or hide the component or feature.

Field properties

Once fields are added to the Form component, each field has a specific set of properties. These properties vary, depending upon the field type. Click on the field within the Form to reveal and edit its properties.

In addition to adding Fields from the Add Fields drop down on the component, it's possible to add a Template. This creates a field on the table which can be configured from the Field Properties tab.

Template fields provide a way to display arbitrary text or HTML alongside field data. Other fields may be included within a template field through the use of merge syntax.

A basic template field for a full name may look like this:

{{FirstName}} {{LastName}}

It is also possible to update any fields included within a template field at runtime by double-clicking the Template field within the component.

For additional information, see Using Fields.

  • Show error message when: This determines when error messages appear. It applies to all validation rules for the given field.

    • User leaves the field: This is the standard blur HTML event, so errors appear as soon as the user navigates away from the input.

    • User changes the field's value: This is the standard change HTML event. Errors appear when the user pauses briefly after adjusting the input and disappear when the user fulfills the input requirements.

    • User leaves the field and then on subsequent value changes: Errors appear when the user first navigates away from the field and then navigates back —the validation then behaves like "User changes the field's value."

      This is useful when you don't want to immediately show an error message, but you'd like to validate when they return to the input—thus minimizing the errors the user may encounter before they've finished changing the input.

    • Save model changes action runs: Errors appear when the user initiates the Save model changes action.

The following properties are available on individual validations:

  • Only validate on save: ( Only available on Required validation ): When enabled, ignores the value of Show error message when and only validates whether the field has a value when the user saves.

  • Required: ( Only available on Required validation ) Validates based on whether or not the field value is empty when validations are set to run.

    Note:  If the field's metadata states that a field is required, this field is set to True and cannot be updated.

  • Enable: When selected, the specific validation rule is applied to the input and error messages display when requirements aren't met.

    Note:  Enable is set per-rule, so you can enable/disable individual validation rules for one field.

  • Validate based on: The type of requirements that the input must meet to pass validation

    • Field length: Validates whether or not the user has typed more characters than allowed by the field's metadata.
    • Format: Validates based on one of four standard input formats:
      • Date: MM/DD/YYYY
      • Email: example@example.com
      • Social Security number: ###-##-####
      • URL: example.com
    • Formula: Validates based on a custom formula. If the formula runs and returns FALSE, error messages appear.
    • Snippet: Validates based on a JavaScript snippet. If the snippet runs and returns FALSE, error messages appear.
      • Snippet: The name of the snippet to validate with

  • Override default error message with: Replaces the system's default inline message with a custom message.