Form Builder is used to construct forms as Platform users will see them. All Forms use the same Form Builder.

Header Content and Fields Component Details Best Practices

Header

The following information and options are included in the header:

A button to return to the Form Settings window
The Form name
When the Form was last saved
The Action menu, which includes the following options:

Preview: Lets you view the Form in your browser. If your bundle is ready and set up, you can see the Form as your users would see it.
Note: Your access/permissions remain the same when previewing, which can occasionally change the experience.
Reset: Removes any changes made to the Form since the last save.
Export Form: Displays a JSON version of the form. You can click Download or copy the text for saving as desired.
Save as New: Allows you to save a copy of the form with a new name and a new slug.
View Submissions: Opens the Submissions tab in Form Settings, which displays a list of form submissions.

The Save option.
Access to the internal application Help.

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 of other elements that can be used either functionally (for example, for display or removal) or visually (that is, for 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, effectively 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.

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: Displays the options configured in the Choices section in a checkbox format.
Date: Inserts a box with an interactive calendar. Click the box to open the calendar, then click a date to select it. 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. Alternatively, you can enter a date directly into the text field. The expected format in the field is mm/dd/yyyy.
Date/Time: Like the Date element, Date/Time inserts an interactive calendar but includes the option to specify a time as well. If you enter a date only, the field defaults to the 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 to 00. The value after the plus sign is the time zone offset. All values are stored in GMT (+00:00).
Dropdown: Displays the options configured in the Choices section in a dropdown list.
Radio: Displays the options configured in the Choices section in a radio button format.
Text: Displays a text field with the configured number of rows. This field can range from short values, such as asking someone their name (1 line), to asking someone for comments (3-5 lines). Validation can also range from simple to complex. See the Validation section for more information.
Time: Inserts a box with an interactive calendar. Click the box to open the calendar, then select a time from the list. Alternatively, you can enter a time directly into the box. The expected format is hh:mm. You can add AM/PM to the value, 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 of this topic 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.

Example: If a user saved a record while on the first page of a three-page form and came back to it later, the current display condition on that page would not be evaluated because the user was already on that page. If the display condition had been updated to make the first page no longer visible, users who were currently on that page would still see it. If the intent were to make a page inaccessible, it would require an event to forward people off the page.

The evaluation occurring 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 items on previous pages, form attributes, identity values, and so on.

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 used to configure the available choices for checkboxes, dropdowns, and radio button fields.

Choices can be hard-coded or pulled from a bridge. It is often helpful to pull any choices that could change, such as available conference rooms using a bridge rather than hard-coding them. That way, when the data changes, the data in the source of record can be changed without affecting the "code" in the form.

Choices have a value and a label that is visible to the user. The value is what's saved. This allows you to present the user with one name (for example, the name of a conference room) while letting you store information with a 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.

Elements are visible by default. When you mark an element as Hidden, it's removed from the page view and the elements that appear lower on the page are shifted up to cover the blank space.

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

When you put code into the head of an embedded form, 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. 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

Form-specific code is commonly reused accross multiple forms. For example, you might implement options like selecting the "Requested For" value or the desired location across multiple forms. If you do, we recommend you move that code to your bundle and call it as a function from the form. Moving the code to the bundle helps with maintenance issues, because you can make changes to the code in one location instead of any number of forms.