Integrations LibraryGet in Touch!

Form Builder

Suggest Edits

Form Builder is used to construct forms as they will be seen by Platform users. All Forms use the same Form Builder.

Content and Fields

The Content and Fields sections list the elements that you can use in a Form. To add an element to the form, click and drag it into the desired area in the middle pane of the Form Builder.

Content

The following Content elements are available:

  • Page: A Page is the base sectioning element for Forms. Every Form must include at least one Page.
  • Confirmation: A Confirmation is a specific type of page that acts as a confirmation after form submission. Forms typically have a single confirmation page, but you can set up multiple configure pages with different display conditions. Otherwise, a Confirmation has all the same attributes as any other Page.
  • Section: A section is a collection other elements, which can be used either functionally (for example, display or removal), or visual (that is, decorative) purposes.
  • HTML: This element allows you to enter HTML, which is rendered when the Form is displayed.
  • Plain Text: This element always renders plain text, effctively using an HTML pre tag.

  • Button: An element users can select. You can choose between one of four button types:

    • Submit Page: Submits the page and advances as validations, submit events, advance conditions, and display conditions specify.
    • Previous Page: Returns to the previous page (does not save content changed since the last save in this page.
    • Save for Later: saves the content on this page and reloads the page.
    • Custom: Lets you define the event/script associated with the button.
      • Note:The others are all preconfigured actions. So, for example, if you wanted to go to the previous page, but wanted to save the current page first, you would need to use a custom button and use the javascripts provided for the save for later and previous page functionalities to achieve the desired button event.

Fields

The following Fields elements are available:

  • Attachment: This field is for allowing users to upload attachment(s). One field can hold one or many attachments. Unlike all other field types, attachment fields do not accept defaults. Attachments can be limited in number, size, or file type by using custom constaints (described below).

  • Checkbox: This will display the options configured in the choices section (described below) in a checkbox format for your users.

  • Date: This will provide a date field for your users. This will appear like a text field, but will pop-up a calendar when clicked on. Web interfaces shown are from the Base bundle. Different bundles have the option to present different interfaces.

    Select a date by clicking on the day. Arrows along the top take you back and forth one month. The Home icon brings you back to the current month. Dropdowns for month and year allow you to navigate larger changes easily.

    Typing directly in the field is allowed with an expected format of mm/dd/yyyy. The answer is stored in ISO 8601 format - yyyy-mm-dd.

  • Date/Time: Date/Time:This will provide a date and time field for your users. This will appear like a text field, but will pop-up a calendar when clicked on. Web interfaces shown are from the Base bundle. Different bundles have the option to present different interfaces.

    The Date operates the same and the time dialog slider is set to the right. If you just select the date, the time defaults to your current time. The expected format in the field is mm/dd/yyyy hh:mm. You can use either AM/PM or 24 hour time.

    The answer is stored in ISO 8601 format - yyyy-mm-ddThh:mm:ss+00:00.

    Seconds are not set via the web console and are always set 00. The value after the + sign is the time zone offset. All values are store GMT (+00:00).

  • Dropdown: This will display the options configured in the choices section (described below) in a dropdown box for your users.
  • Radio: This will display the options configured in the choices section (described below) in a radio button format for your users.
  • Text: This will display a text field with the configured number of rows, from asking someone their name (1 line) to asking someone for comments (3-5 lines). Validations can be as strict and complex or as simple and basic as needed (see Validation section below).

  • Time: This will provide a time field for your users. This will appear like a text field, but will pop-up a calendar when clicked on. Web interfaces shown are from the Base bundle. Different bundles have the option to present different interfaces.

    Clicking in our standard Time Only question presents a dialog to select a time by the hour. You can also directly enter the time. Expected format is hh:mm. The customer can add AM/PM but the answer is always stored in 24 hour format.

Component Details

The rightmost pane of Form Builder lists the options for the currently selected Content or Field element. Options are separated into the sections below.

Form Settings

Click the Form Settings option in the center pane to view and define form-specific information. The following sections are available:

  • Form Details: Displays the form name and description in read-only format. Additionally, provides the Form Notes field, which you can use to enter additional development notes for the form.

  • Bridged Resources: This section is used to define all bridge queries that will be used within the Form, whether in script, events, or field options. All bridge mappings and queries defined at the Space level can be used for configuration.

  • Advanced: This section allows you to enter custom header content. See the Advanced section for more information.

Details

The Details section allows you to specify the element name, the element label (which is displayed to users), and the default value, if any, to assign to the element.

Display and Advance Conditions

Display and Advance Conditions are Page-specific elements used to control page visibility and behavior.

Display Condition: A Display Condition determines whether a page is visible to users. This condition is evaluated at the time the user advances to the page. This means that if a user is on a particular page of a form and saves their record, then comes back to it later, the current display condition on that page is not evaluated. The user is already on that page. If the display condition has been updated to make it no longer visible, users that are currently on that page will still see it. Note that this may require an event to forward people off the page if the desire is to make a page no longer accessible. Evaluating this before the page displays also means that values load events on the page cannot be part of the criteria for determining the display condition. Instead, display conditions must use It must be items on previous pages, form attributes, identity values, etc.

Advance Condition: An Advance Condition determines whether a user can advance from a page to the next/submit the page.

Default Field Values

The Default Value option allows you to specify a text string, variable, or bridged resource as the default response for the element.

There are multiple ways to leverage the Default Value option, including:

  • Entering a static value (for example, entering a value of "Yes" for a Yes/No Radio button)

  • Entering or selecting a variable to use in the expression. A common example of this usage is setting a Requested By field to the User ID of the person who is currently logged in using the Identity variable.

  • Using a bridged resource to populate a default value. For example, you can enter a query of people information that uses the login ID of the individual for a parameter.

    You can then select the result of that bridge from the variables and used in the default.


Choices

The Choices section is available for checkboxes, dropdowns, and radio fields. This is where you configure what choices, or options, are available to the user for that field.

There are two key things to note for this section:

  • Choices can be hard-coded or pulled from a bridge. It is often helpful to pull any choices that may ever change (available conference rooms, for example) using a bridge rather than hard-coding them. That way, when the data changes, the data in the source of record (AD, Datastore, etc) can change but you don't need to go through your change process to change the "code" in the form.
  • Choices have both a label (visible to the user) and a value. It is the value that is saved. This allows you to present the user with the name of a conference room, for example, but for you to store and use the unique id.

Display

The Display section allows you to configure an element's visibility. Elements can be visible, hidden, or dependent on a conditional (similar to the "if" of a JavaScript if statement). If the condition evaluates to true, the element is visible.

For field elements, you can also specify whether the field can be edited, if editing is disabled, or if editing is enabled only under certain conditions.

Conditional Expressions

Conditional Expressions let you inject logic and guide users down the right path. Conditional expressions are written in JavaScript and can include variables like element values or attributes defined within the Platform.

The following variables are available by default for use with conditional expressions in the Form Builder:

  • space
  • kapp
  • form
  • values
  • identity

Examples

The example below shows how conditional formatting can control when a section is displayed. In this case, the section would only display when the "Employee Department" field is equal to "Accounting".

This example uses a conditional expression that includes a check box question field. In this case, since checkbox fields can have multiple values, we use the indexOf JavaScript function to test if the value "Blue" was selected.

Using JavaScript to hide and show Fields programmatically

There may be times when you want to leverage available JavaScript functionalities to control a field's display and validation. This can be achieved by creating a specific field for shared forms and setting that field to a value that, per the built in conditional expression, controls the display in the desired way. However, in situations where the conditional expression is likely to be updated frequently, you can use the following JavaScript to control a field's display directly:

K('field[Field Name]').hide()
K('field[Field Name]').show()
K('field[Field Name]').disable()
K('field[Field Name]').enable()

This method this may cause conflicts. For example, if you define a “Visible” condition in the builder of “Hidden” and then call the show method, eventually the form will self-correct and hide the field again. Leaving these conditions to their default state should allow you to use the functions in JavaScript event code.

Validation

The validation section checks whether a value should exist. If the requirements outlined in this section are not met, processing is stopped. There are three non-exclusive options available in this section: Required, Pattern, and Custom Constraint.

Required checks for the existence of a value. This can be conditional, basically what you would put in the if part of a javascript if statement. When conditional, if the condition evaluates to true, the field/element is required. Note that if a field is always required, but conditionally visible, it is still required even when not visible. It is likely, if applying a display condition, that a similar or the same condition may be appropriate for the field.

Note: You can specify a message to be displayed if the required value is not provided. A default message is available, but may not be the desired text for communicating the issue to the user, especially if the required field is a hidden field.

Pattern provides preset regex patterns for validation along with a custom option. Custom requires valid regex and a message if the pattern is not met. There is a related How To for information on creating regex patterns.

Custom constraint includes validation based on other options with the form or answers. Form information, attributes and answers are available to use. Like a custom pattern, a message must be provided if the constraint is met. Examples of this are limiting an attachment field to only allow upload of XLS files:

value.filter(function(item) { return !item.name.match(/\.xls$/i) }).length === 0

The corresponding message might be:

Please upload only .xls spreadsheets into this field.

Validating fields with patterns

Using regular expressions helps ensure that data is entered properly. Some examples of desired validation patterns are checking for currency (two digit decimal values), email addresses, and IP addresses.

Validation patterns can be applied to fields in the validation section.

There are currently no preconfigured patterns, but you can enter custom pattern validation in the RegEx box, along with a message that will displayed if the field fails the validation in the Message box.

Events

Events make Forms more dynamic. They allow you to run custom code, search other systems using bridges, and set fields with data when something happens on a Form.

Events are available on all elements except Sections, HTML/text elements, and the preconfigured buttons (Save for Later, Submit, and Previous Page).

Event Types

Not all event options are available for every element. For example, you shouldn't have a Submit event on an Attachment question. The Type of Event determines when the event is fired.

Form Element Available Element Types
Page / Confirmation Page Load, Submit
Section No Events Available
HTML / Plain Text No Events Available
Custom Button Click

All Questions have a Change event type. While this is easy to see how it works with drop-down lists and radio buttons, questions like Attachments and Date/Time fields are a little trickier. The event is triggered on every change, so you need to use the Run If condition (see below) to monitor exactly when to fire the events. For example, you may not want to fire an event if the field value is null; or you may only want to fire the event if another question contains a specific value.

Event Actions

There are two options available to select when an Event fires: Custom and Set Fields.

  • Custom: Provides the opportunity to fire javascript. A field is provided with some basic formatting help. Optionally, you can call other available functions from your bundle.
  • Set Fields: Allows you to set a value to any existing question on the form. You have the option to use a bridge to collect the values, or you can use the standard set of variables provided. The variables provided include the values of the questions on the form, the form information, the identity information (for the logged in user when the even fires), the kapp and space information, etc.

Advanced Features

A couple of other features enhance Events usefulness. The first is the Run If condition. This feature lets you stop the event from firing if the condition evaluates to false.

The other feature is Bridge Resource. This option is often used with Set Fields events and can pull fields from an external source. The option can also provide data for tables or other custom javascript events.

Along with these options, you can specify builder-defined events. See Builder-Defined Events for more information.

Render Attributes

Render attributes are attributes that are added to a field or element when it is rendered. Common render attributes are class or id, but there are any number of attributes that could be set for use with various JavaScript libraries.

To apply a render attribute, provide the attribute and its desired value in the render attribute section of the field/element, then save your item. The render attribute is then displayed with the element.

Which render attributes to use varies greatly depending on what libraries are loaded in your particular theme/bundle. Render attributes are all about display and leveraging available options. Attribute validity depends on what is available to your forms when they render.

Advanced

The Advanced section contains lesser-used, more advanced features for an element. The options available differ depending on what element is selected, as described below:

  • Forms:At the Form level, the section is used to enter custom header content, which lets you define additional scripts and styles for use only in this Form.

    Note: This option is rarely used because the majority of scripts and styles are shared across various forms and are more appropriately assigned at the theme/bundle level.

  • Pages: At the Page level, the section provides the Display Page for the Page. This allows you to specify a different display page for this service item from the standard applied by the kapp and form settings. Since it is rare to have one form display differently from the others in its kapp so completely, this is under Advanced..

  • Fields: At the Field level, the Advanced section contains the field key used at the database level. This is assigned by the system and shouldn't be changed without a very important and specific reason.

Best Practices

Consider these best practices when building forms.

Using Code in Forms

For including code into forms, you almost always use JavaScript.

Where to Put Code

For form specific code, there are three places that we recommend to put your code, Custom Events, the Custom Head Content field, and theme files.

Code in custom events is only executed when the event is fired, but it is a standard location, and "makes sense" to look there for maintenance or upgrades to the form. This is the ideal place to put code that is not re-used across forms.

Custom Head Content is available under the Advanced section of the Form Settings. Any text placed here is added to the Head of the web page when it is displayed.

Embedded Forms

Be aware that when putting code into the head of an Embedded form, that it may not load the same as a "parent" form. Specifically, it may load after you are expecting it to be available.

Also note that when you are using a REACT theme, all forms are embedded into the theme page. Thus, all advanced header code may load after the rest of the form is loaded and may not be available when you intend.

Where Not to Put Code

One of the reasons we recommend putting code into either the Custom Head Content or a Custom Event is maintainability. Those are logical places to put your form specific code. The one place we do not reccomend putting code is an HTML element.

HTML elements can have code (script tags), but it makes it hard for the next form developer to find code that is mixed in with other text features on a form. Also, code loaded in HTML elements may not be available or fire when intended based on the way the form loads.

Reusable Code

It's a common occurence for form specific code to be reused across multiple forms. Options like selecting the requested for or the desired location could be implemented across multiple forms. When this happens, it's recommended to move that code to your bundle and call it as a function from the form. Moving the code to the bundle helps with any maintenance issues. When changes need to be made to this code, it only needs to be done in one location instead of several (to dozens or hundreds) of forms.

Updated 2 months ago