Forms

Anne Rosebery
Form Developers

Inside the desired kapp inside the desired space, selecting Forms will take you to the forms console. This console displays all of the existing forms in that kapp (if any) and allows you three ways to create a new form:

  • Click the Create Form button and manually create a form from scratch
  • Click the Import Form button and import a form exported from another system, space, or kapp.
  • Click the arrow at the end of any form item to pull down it's menu and clone that form.

CreateForm

Each of these methods has pros and cons.

Creating from Scratch

Creating from scratch means you are starting fresh. There is no need to clean up any potentially unused or problematic fields, elements, bridges, or functions. However, many kapps require forms have certain elements on them to function properly. Starting fresh can mean having to recreate fields, elements, or sections already in place on other items.

Importing

Importing is essential when moving elements between environments, such as from development to test and from test to production, but it is unlikely to be an effective or effecient way to develop. While it is possible to develop by typing up all of the appropriate json, doing so forgoes the friendly form editor provided.

Cloning

Cloning allows for development using the form editor, but you inherit all elements from the existing item. You may not need all the elements, fields, bridges, etc on the form that was cloned. This leads to potential clean up.

Form Templates

A good combination of these methods is using the Create Form to create the initial form for the kapp with all of the required fields, elements, and such. This may also mean creating any forms that will be used as subforms in the main form for the kapp. Once that primary form is built with a main placeholder field, name it as a template and always create forms off of that. Make sure to always start from the template and keep the template up to date if changes are needed.

Building a Form

Every form has the same builder. This builder constructs the form as it will be seen by the platform users.

form builder basic

The builder has 4 functional areas: the header, the forms and elements menu, the body of the form, and the component details.

Header

The header provides, in order from left to right:

  • Access back to the form settings
  • The name of the form
  • When the form was last saved
  • An Action menu that allows you to

    • Preview the form in your browser. This (if your bundle is ready and set up) will allow you to see the form as your users would see it. Note that you still will have your access/permissions, which can occassionally change the experience.
    • Reset your form. This means remove the changes made since the last save.
    • Export the form.
    • View the submissions for the form.
  • Save the form
  • Access the Internal Application Help.

Fields and Elements

Elements

Below the header, the left hand side of the screen presents all of the options for elements and fields you can use on your form. You drag these into the desired place in the middle section of the screen to apply that item to the form.

Elements

  • Page: There must be at least one page on every form. This is the base element of sectioning the form. Pages have:

    • Name
    • Display Condition: If this evaluates to true, the page will display for the user. Default: true
    • Advance Condition: If this evaluates to true, the user will be allowed to advance from this page to the next/submit the page. Default: true.
    • Events: It is possible to run events/scripts on Load or Submit of the page.
    • Display Page: This allows you to specify a different display page for this service item from the standard applied by the kapp and form settings. The pages are used to contain all the other elements and fields for display to the users.
  • Confirmation: Confirmation is a specific type of page. It is meant to display as a confirmation after form submission. A form cenerally has one confirmation page, but it is possible to have more (with different display conditions). Confirmation pages are pages and so have all the same attributes as regular pages.
  • Section: Sections are meant to be collections of other elements, either for functional (eg. display/remove) or visual (eg. decorative) purposes. As such, sections are simple elements with:

    • Name
    • Optional (displayed) Title
    • Display rules
    • Render Attributes Details on the sections such as Visibility rules and Render Attributes will be covered when discussing the third form builder section.
  • HTML: HTML fields will allow you to enter HTML and will render that HTML when the form is displayed. These are also very simple, with:
  • Name
  • Content
  • Display rules
  • Render Attributes
  • Plain Text: Plain text are text fields that will always render plain text. These are, essentially, inside an html pre tag. They have the same components as HTML fields.
  • Button: There are multiple types of button. Once you put a button on your form, you can deside which type it is:
  • 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 Note that the custom page is the only type of button that allows you to define the event/script associated with it. 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

Fields have very similar sections in the field details (the third form builder section). These will all be reviewed in that section below. Only the field differences will notes here.

  • 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.

question date web example

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: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.

question date time web

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.

question time only web

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.

Form, Element, and Field Details

The right hand side of the builder contains the details of the form, element, or field selected in the center portion of the builder. The options displayed may be slightly different for each type of item, but the function of each component functions the same way when it is displayed.

Form Details

FormDetails

Form details contains the form name and description (as read only) and provided a place for additional form notes. This is a great place to put additional development notes for the form.

Bridged Resources

BridgedResources

It is here, in bridged resources within the form, that all bridge queries that will be used within the form, whether in script, events, or field options, will be defined. All Bridge Mappings/Queries defined in the space will be available for configuration.

Choices

Choices

You will see a Choices section 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 here.

  • 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

Display

Display will have one or two sections depending on whether it is an element for a field. If present it will always have Visibility. This controls whether or not the field is visible. 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 visible. You can also select if a field removes any value already present in the field and doesn't allow values to be set when it is removed.

The other option under display will only be present under fields because it is Editable: whether the field is read-write or read-only. This can also be conditional and when conditional, if the condition evaluates to true, the field/element is editable (read-write).

Validation

Validation2

Validation checks the value and existence of a value and stops processing if that requirement is not met. There are three non-exclusive options: Required, Pattern, and Custom Constraint.

Required checked 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 that 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.

Events

Event

The event section is where events associated with that element or field are and where you can create new events. The events available may differ by item. For example, load and submit events are available for a page, but change events are available for a field.

Event2

Events provide you with the ability to do something based on an event (load, submit, change) on the form. This could be a set fields action (generally leveraging a bridge) or a custom script. Events are flexible and so extremely powerful and have further documentation all to themselves. However, basic usage is also extremely simple. Add the event and then fill in a name, an event (load, submit, change, etc), and a type (set field or custom), then either chose the fields to set or enter your script and save.

Render Attributes

RenderAttributes

Render attributes are attributes added to the field or element in the HTML when it renders. This is often, as pictured, classes. However, it can be anything that is necessary for desired fuctionality. Some libraries request or require certain render attributes, or sometimes having certain render attributes simply makes some custom scripting easier. This is just another tool provided to assist in building the best possible solutions with the platform.

Advanced

AdvCustHead

Advanced always contains advanced, lesser used features for an element. For the form, it is the custom header content. This is a way to define additional scripts and styles that will be used in only this form. This isn't as commonly used because the majority of scripts and styles are shared across various forms and are more appropriately up in the theme/bundle.

AdvPage

As previously described, Advanced 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.

AdvField

For the field, this shows the field key used at the DB level. Since this is assigned by the system and should not be changed without a very important and specific reason, this is also tucked away under Advanced.

Configuring a Form

Every form has the same options, under the same tabs: General, Categories, Attributes, Security, Submission, an actions menu, and a link to the builder.

General

Form1

This is where the form name and slug are set. The form slug is meant to be a unique value for this form within the kapp and needs to be able to render in the URL. This is why the characters available in the slug are limited. Because this is the form's unique identifier, it is also recommended that this not be updated once the form has production submissions. The form name, however, can be updated as desired.

This tab also contains the form status. This status does not do anything within the console or within the application. However, this status is meant to be used by the themes to determine which items render and are submittable.

This also contains the form type, which is also a classification for use in the theme or by users, but is not functional in the system beyond providing an additional form search parameters.

The submission label is a customizable way of identifying individual requests. These can include text and any value from the submission. For example, you may choose for an on boarding submission label to be: On-boarding for ${values('New Hire Name')} Requested by ${values('Requested By Display Name')} This could then be used when identifying the request instead of (or in conjuction with) an Id sort of identifier.

The form's Description is the last thing on this tab. While this is optional it is highly recommended even when it will not be shown to the user that a description of the functionality provided by that form be included here. This can provide some measure of basic documentation for the functionality of the form.

Categories

Form2

This is where you can add categories defined for the kapp. Note that you cannot create new categories here, only apply existing categories to this form. To create new categories, go to Category Defitions within the Kapp the form is in. Note that Categories are Kapp specific. Defining Categories in one kapp does not make them available in other Kapps in the same Space.

To add a category, you need to select it from the drop-down, click Add Category, and click Save Categories. If you leave the tab without clicking Save Categories, your additions will not be applied.

Attributes

Form3

This is where attributes are applied to this form. As with Categories, attributes cannot be created here, only applied. If you need to create new attributes, go to Attribute Definitions within the Kapp the form is in. Note that Form Attributes are Kapp specific. Defining Form Attributes in one kapp does not make them available in other Kapps in the same Space.

To add an attribute, you need to select it from the drop-down, add the desired value for that attribute, click Add Attrbute, and click Save Attributes. If you leave the tab without clicking Save Attributes once you are done adding attributes, your additions will not be applied.

You may note that you can add some attributes only once and some more than once. This is set at the attribute definition level and would need to be changed there.

What attributes are used for is limited only by imagination. These can be used by the workflow engine to determine the correct assignee group(s) to controlling the display on the Front-end. They are there to be used as needed.

Security

Form4

The security tab is where the security definitions defined within the Kapp are applied to the form. Note that it is only necessary to specify security rules for the form if it is desired to override what is defined at the Kapp level for the form.

KappSettings

Form Display controls who can see (and therefore submit) the form. It is not possible at this level to allow someone access to see but not submit the form. That would need to be controlled with rules on the front-end, such as an advance condition, or within the workflow engine after submit (to not process or delete the submission).

Form Modification controls who can change/update the form. This is often set to a security definition that includes form developers and platform admins.

Submission Display controls who can see submissions. This is often set to the submitter of the submission and platform admins. Submission Display access also becomes important when retrieving search results. Searches will error if they contain too many (>25) submissions the user cannot access. This is something to keep in mind when determining access for various forms and when constructing search queries.

Submission Modification controls who can modify a particular submission. This is often set to the submitter of the submission and platform admins.

Also on this tab is a setting to allow for anonymous submission:

anon

This setting controls whether a submission is submitted with the user's login information or with "anonymous". Note that this does not actually control access. That is done with the Form Display setting.

Submissions

Form5

Once submissions have been entered for you form, this will provide a listing of the submissions for the form, most recent first. When clicked on, they will show the details of that selected submission.

Submission