Gadget Configuration Settings

After Creating a Form, you can choose from various Form Builder Gadgets to add to your form.

Once a gadget has been added to your form, the Configuration Panel opens automatically. Although all form builder gadgets perform different functions and have unique settings, many of their initial gadget settings are the same. 

• Gadget Label/Question
• Limit Visibility Based on Other Gadgets
• Required
• Description/Help Text
• Enable Autocomplete
• Show Placeholder Text
• Custom Column Name
• Edit Unique JSON Key
• Section Only Settings:
  • Office Use Only
  • Custom Page Name
  • Hide Gadget Label on Form
• Checkbox, Multiple Choice, or Dropdown Settings:
  • Options
  • Default Options
• File Upload:
  • Allowed File Types
• Number/Currency Gadgets:
  • Require Min/Max Numbers
  • Enable Calculations
• Link:
  • Link Text
• Short/Long Text Gadgets:
  • Require min/max characters
  • Regular Expression
• Read-Only Text:
  • Read-Only Text
• Read-Only Image:
  • Read-Only Image 
  • Description/Alt Text
  • Custom Image Size
  • Horizontal Alignment
• Read-Only Data:
  • Select a Gadget
• Date: 
  • Limit Selectable Dates
• Option Range:
  • From/To
  • Add Custom Labels
• Table/Repeater Gadgets:
  • Enable Calculation Footer
  • Start With This Many Rows (max 15)
  • Allow User to Add Additional Rows
  • Start with this many repeats (max 100)
  • Limit Number of Repeats
• Validation:
  • Error Text
  • Rules for making this visible
• Data Lookup Gadgets:
  • Data Source
  • Headless Integration
  • Add Linked Auto-filled Gadgets

Gadget Label/Question

The Gadget/Label Question The name of the field that will appear on the form. It also refers to the label the system references for the field in all reporting, workflows, and integrations unless a Custom Column Name has been identified. 

The Gadget Label/Question field is used on every type of gadget.

Limit Visibility Based on Other Gadgets

This setting allows you to show/hide either a single gadget or section within a form based on selections made. For example, if a checkbox for 'Include in Catalog' is checked, then the field 'Catalog Activation Date' would display. If not, then the field would be hidden. 

• To use the setting, start by selecting the field that will be used to determine the visibility. In the below example, it would be 'Include in Catalog'. 
• Next, choose the operator and value that will create a true statement to determine when the field will be visible. In the example, 'has checked' is selected as the operator, and 'Yes' is selected as the value. This creates a statement indicating that the field 'Catalog Activation Date' will display when the field 'Include in Catalog' has checked the value 'Yes'. If this is not true, the field will not display.

Multiple conditions may be used to determine visibility - but keep in mind that all statements must be true in order for the field to display on the form.

The Limit Visibility Based on Other Gadgets setting is available on all gadgets.

Office Use Only

The Office Use Only setting will allow you to hide a section of fields and information from the submitter of the form.

Once a section has been added to your form, the option to enable the Office Use Only setting will display in the configuration to the right.  With this setting enabled, you will be able to hide the section from the submitter while allowing all others to view the section and the information it contains at any step of the workflow process.

The office use only setting is only available for sections.

Custom Page Name

Using sections will allow you to break up the page by rendering them as pages within the form. By toggling the option on, you can enter a name that may differ from the title shown within the section in the form design. 

The custom page name setting is only available for sections.

Hide Gadget Label on Form

This setting will allow you to hide the section label on the form. This can be enabled by toggling the Hide Gadget Label on Form setting just below the Gadget Label/Question box. Once a section is hidden, the header will be removed from the section in the center panel and will be replaced with a section tag. The tag allows you as the app builder to identify section divisions more easily in the form builder, but it will not be visible to your users. 

The hide gadget label on form setting is only available for sections.

Required

The Required setting will ensure that data is not left blank on a field. Once it is toggled on, a red asterisk will appear next to the field label on the form, and a user will not be able to submit the form if the field is left empty.

If the user attempts to submit while the field is blank, a validation error will appear on the form forcing them to complete it.

The required setting is available on all gadgets except for:

• Sections
• Tables
• Repeaters
• Submitted By
• Read-Only Data

Description/Help Text

This adds additional text to the gadget that can be used as help text or additional explanation for the form submitter. It can be shown inline or behind a help icon.

If set as descriptive text, content can be entered into the editor, and it will display on the form below the gadget label. 

If it help text is preferred, the checkbox 'Display as help bubble' can be checked, and the text will instead be displayed behind the tooltip icon (). 

The Description/help text setting is used by all gadgets except the following: 

• Read-Only Text
• Table 
• Repeater
• Submitted by
• Read-Only Data

Enable Autocomplete

The Autocomplete option in Short Text, Long Text, and Email gadgets allows you to configure an autocomplete suggestion for a form field.  By utilizing the user's browser autocomplete settings it will suggest a value on a form field for selection which can be used to improve the built-in accessibility of your forms. Autocomplete configuration will be omitted by default (even if autocomplete is not enabled, the browser still could offer hints).  If you don't want to include autocomplete at all you'll want to disable via the 'Off' option.  Below outlines the options when autocomplete is enabled on the field:

• On (Browser Default) - the default autocomplete logic set up in your browser settings will be used for possible suggestions.
• Off - the browser will not provide any autocomplete suggestions for the field.
• Name - will suggest the Name configured in your browser autocomplete settings.
• Phone Number - will suggest the Phone configured in your browser autocomplete settings.
• Street Address - will suggest the Street Address configured in your browser autocomplete settings.
• Postal Code - will suggest the Postal or Zip code configured in your browser autocomplete settings.
• Custom - allows you to configure a custom autocomplete option via a html attribute.  More information in the link on how to set that up (requires a bit more technical knowledge).

The Enable autocomplete option is only available for use in the following gadgets:

• Short Text
• Long Text
• Email

Options

When adding a checkbox, multiple choice, or drop down gadget to the form, a setting for Options will be available. This setting will allow you to define the selections available to the user. 

After adding the gadget to the form, the options can be entered manually by clicking the Add button and providing a label, or by selecting a preset from the drop down menu. The presets will contain common options such as true/false, yes/no, on/off, agree/disagree, etc to help speed up the form creation process.

The Options setting will only be available on the checkbox, multiple choice, or dropdown gadgets.

Default Options

The default option setting will only be available for a multiple choice gadget. This allows you to select one of the available options as default, rather than leaving it blank. 

Show Placeholder Text

This setting allows you to populate sample text within the field that will be replaced when the user adds their information.

Placeholder text is enabled by clicking the toggle to turn it on, and then entering the text as you would like it to appear on the form for the user.

The placeholder text setting is only available for use the following gadgets:

• Short Text
• Long Text
• Date
• Time
• Number
• Email
• Link
• Currency
• File Upload

Allowed File Types

When using the file upload gadget, you can determine the types of files that users are allowed to submit. There are three options available to select from:

• Accept all file types
• Only accept the selected file types
• Custom "accept" value (I know what I'm doing)

The Accept all file types option will allow users to upload and submit any type of file. 

The Only accept the selected file types will limit the files allowed to be uploaded to only those with the type specified from a small list of options. Selecting this will provide a secondary list of options, allowing you to limit the files to documents (pdf, docx, txt, ppts, xlsx), images (png, jpg, gif), or videos (mov, mp4, avi). 

The Custom "accept" value (I know what I'm doing) option limits the files to those specified, and requires that you identify the file extension. For example, entering '.psd' to allow a Photoshop document. If you are unsure about the file extension to enter, try using either the accept all or the selected file types option instead.

Require Min/Max Numbers

This setting will only be available on the Number gadget. This allows you to set number of characters required by minimum, or the maximum allowed. For example, entering a '1' into the minimum setting requires the user enter at least a single numeric character. If you were to enter a '1' into the maximum setting, the user would not be able to enter more than a single numeric character.

To enable the setting, click on the toggle icon to turn it on, and then enter the respective minimum or maximum number of characters. 

Require min/max characters

This setting will only be available on the Short and Long text gadgets. This allows you to set number of characters required by minimum, or the maximum allowed. For example, entering a '1' into the minimum setting requires the user enter at least a single numeric character. If you were to enter a '1' into the maximum setting, the user would not be able to enter more than a single numeric character.

To enable the setting, click on the toggle icon to turn it on, and then enter the respective minimum or maximum number of characters. 

Regular Expression

The Short text gadget provide an advanced option that allows you to enforce custom formatting. For example, if you wanted to capture a phone number that was formatted like this: 555-555-5555, you could use regular expression such as ^\d{3}-\d{3}-\d{4}$ to enforce the 10 digits and dashes. 

The syntax for regular expressions is more advanced, but simple patterns like the one mentioned above are pretty approachable. There are several resources available on the internet to help you understand regular expressions, and while we don't endorse a particular site, we have found that this resource is often helpful for our customers: https://regexone.com/.

A custom error message can also be provided to help users understand the required formatting. For example, a user did not correctly format a phone number as 555-555-555, a customized error message would appear upon the submission of the form to alert them. 

Enable Calculations

At times, it may be necessary to run simple math calculations within a forms, such as addition or multiplication. To use calculations with a Number, Currency, or Option Range gadget, they will need to be enabled by selecting the toggle within the settings.

• Begin by adding either the Number, Currency, or Option Range gadgets to the form to house the total for the calculation.

• Next, enable calculations by toggling on the Enable calculations option within the settings for the total field.

• Select the type of calculation (sum, subtract, multiply, product, average, median, min, max or count).

• After you have selected the type of calculation to use, you can select the Number, Currency, or Option Rage field you wish to calculate (ie: Field 1, Field 2, etc).

Note: You do not need to turn on calculations for the input fields, only for the total output field.

• When the user enters a value into the two fields selected, the calculation will be shown in the enabled field.

Calculations for Currency

When using calculations for currency, it’s important to make sure you’re setting the current output for the total.

For example, I want to calculate the dollar amount of sandwiches multiplied by the number of sandwiches purchased (currency x amount = $ total).

• For this example, you would need to add a currency gadget for Cost of Sandwiches, a number gadget for Number of Sandwiches, and a currency widget to house Total Sandwiches.
• Once the fields are established, toggle the Enable calculations setting to turn it on.
• For determining the total, select product under Type of Calculation, and then select Cost of Sandwiches for Field 1, and Number of Sandwiches for Field 2.

• Change the toggle at the top of the form to Preview.
• Enter the appropriate values into the fields, and the Total Sandwiches Cost will automatically calculate!

The enable calculations setting is only available on the Number, Currency, and Option Range gadgets.

Enable Calculation Footer

At times, it may be necessary to run simple math calculations within a forms, such as addition or multiplication. To use calculations for number or currency gadgets within a table or repeater, the calculation footer will need to be enabled by selecting the toggle within the settings.

Once the table or repeater gadget has been add to the form:

• Toggle the Enable Calculation Footer option within the table settings.
• For each item in the table, select the type of calculation. For example, selecting sum will add the values of the column together.
• When the user enters a value into the fields selected,  and the sum for each column will be calculated automatically in the footer.

Note: Calculations do not work if users submit documents through the API directly.

The calculation footer setting will only be available for the table and repeater gadgets.

Link Text

This setting allows you to configure the link text that will display when viewing a document. When the user submits the form with a link, the URL will be shown to them, but when reviewing the document it will reflect the link text instead. 

The default will display as 'click to visit', but you can configure this to reflect your preferred language. 

The Link Text setting is only available for the Link gadget.

Read-Only Text

The read-only text setting will only be available for the read-only text gadget. This field will house the information as it will appear on the form, providing additional context or instructions to the user that can not be edited.

This text can be entered using a WYSIWYG editor to provide any formatting needed.

 

Read-Only Image

The read-only image setting will only be available for the read-only image gadget. This field will house a static image to display on the form for logos, instructions, example images, QR codes, etc.  Below are the settings to set-up the read-only image.

Description/Alt Text

You can assign the image Alt Text that will display when a user mouses over the image to better facilitate accessibility.

Custom Image Size

You can select from a predetermined number of image sizes (Tiny, Small, Medium, Large, Huge) how large the uploaded image will appear on the form.  The None default selection will display the actual file size.

Horizontal Alignment

You can align the image in the gadget (left, right, center) to display as you desire - it will default as center aligned.

Select a Gadget

The Select a Gadget setting is only available within the the Read-Only Data advanced gadget. The setting is used to indicate the source of the read-only data that will be displayed on the form. This data may come from two different sources:

• Data on the form: Previously entered data on the form. This option is typically used when information from Kuali needs to be sent through an integration to an external system, and the app administrator wants to ensure that the field is not edited by any reviewers. 

  Note: The following gadgets cannot be used with the Read-Only Data gadget:

  • Check Boxes
  • Repeater
  • Signature
  • Tables
  • Image Upload
  • File Upload

  The Data Lookup (Multi-select) can be used, but only with Groups.

• System metadata: Data that is automatically captured on the form (e.g. document number, submission date, submitter’s email address, etc.)

When using the read-only data gadget and selecting system metadata, the following options are available:

Submitter:

The name of the person that submitted the form.

Submitter - ID:

A unique ID for the submitter that is automatically assigned by Kuali.

Submitter - Display Name:

The display name of the person that submitted the form as entered on the submitter's user record.

Submitter - School ID:

Includes the data found in the School ID field on the submitter’s user record. This is typically populated with the institution student or faculty id.

Submitter - Email:

The email of the person that submitted the form.

Submitter - Username:

The username of the person that submitted the form. If an institution has Single-Sign On configured, the username will be populated with the information sent from the SSO. If SSO is not configured the username may be edited by the institution’s Kuali system administrator or the user themselves. This field is not required.

Submitted At:

The date when the form was submitted.

Created By:

The name of the person that created the form.

Created By - ID:

A unique ID for the creator of the form that is automatically assigned by Kuali.

Created By - Display Name:

The display name of the person that created the form.

Created By - School ID:

Includes the data found in the School ID field on the form creator’s user record. This is typically populated with the institution student or faculty id.

Created By - Email:

The email of the person that created the form.

Created By - Username:

The username of the person that created the form. If an institution has Single-Sign On configured, the username will be populated with the information sent from the SSO. If SSO is not configured the username may be edited by the institution’s Kuali system administrator or the user themselves. This field is not required.

Created At:

The date when the form was started.

Number:

The document number of the form that is stored in Kuali. Each submitted form for an app has a unique number to distinguish it from other submitted forms.

Workflow Total Run Time:

The total amount of time a form was going through the workflow process.

Workflow Status:

The current status of the document in the workflow process. This updates on the form as it progresses through the workflow. The status could include:

• In Progress: The document is still going through the workflow process
• Complete: The document has completed the workflow process and has been approved.
• Denied: The document has completed the workflow process and has been denied.
• Error: The progress of the document through the workflow process has been paused due to an error in the workflow. Reach out to your Kuali administrator for additional assistance.
• Withdrawn: You previously withdrew this document, and it is no longer being run through the form’s workflow.

Time on Current Step:

The amount of time a form has been on its current workflow step.

Link to Document:

When this option is used on your form, it will provide a link to that document. This variable can also be used in notification steps in workflow to link users to the document in Kuali.

Limit Selectable Dates

When using the date gadget, a minimum and maximum date can be specified to control what dates users are able to select. 

For example, if you had a form where users are allowed to request a preferred date for an upcoming training, and they may only select dates within a two week period, you can select the first available date and the last available date.

When the user clicks into the field to select a date, only dates within the range specified will be available for selection.

Custom Column Name

The Custom Column Name setting allows you to change the text that appears within the column header for the gadget when you are viewing the document list. For example, if you have a field called 'Title' on the form, but you would prefer it read as 'Course Name' on the document list. 

The default for the document list will be to use the same name as the field. 

• To add the custom name, you will need to toggle the option on.
• Next, enter a new title into the Custom Column Name field and then publish the app. 
• Once the changes have been published, you can return to the document list and click on 'Columns'. 
• Click on the eye symbol next to the column you want to display, and the new column title will display. 

Note: If you do not immediately see the Custom Column Name reflecting in the column list, refresh the document list. 

The Custom Column Name setting is not available for Sections, Read-Only Text, Submitted By, or Read-Only Data gadgets.

Edit Unique JSON Key

An advanced option that allows you to edit the system ID for this gadget, which can make it easier to identify the content within the API. Changing this can have serious consequences for your app and should be changed only with careful consideration. 

The default field Id for a gadget will be shown just below the label:

Enabling the option will provide a field for you to enter a custom JSON key that better suits your application:

Unique JSON keys are not available for Sections, Read-Only Text, Submitted by, or Read-only Data gadgets.

From/To

The From/To setting is only available when using an Option Range gadget. This setting allows you to determine the range that users can select from, and defaults to a range of 1 to 5.  This value can also be used within calculations.

The From setting can be adjusted to a value of one or zero, and the To setting can be adjusted to a value ranging from 2 to 10. Once selected, the form will reflect the available range for users to select from.

Add Custom Labels

The Add Custom Labels setting is only available when using an Option Range gadget. This setting allows you to provide additional labels for context to the left and right of an option range.

For example, if you wanted the option range to reflect that a value of 1 indicates a user disagrees, and the value of 5 indicates a strong agreement,  you would add in the labels accordingly. 

Start With This Many Rows (max 15)

When using a table gadget, you can define the number of rows a table should start with. The default value will be 2, but you can adjust this up to a max of 15 rows.

Allow User to Add Additional Rows

Allowing the user to add additional rows will only apply to the table gadget. This setting allows the form submitter to add additional rows to the table when they’re filling out the form. From within the setting, you can also set a maximum number of rows a form submitter can add, up to 15.

Start with this many repeats (max 100)

When using the repeater gadget, you can specify the number of repeated groups of fields on the forms up to a maximum of 100 that display when the user first views the form. 

Limit Number of Repeats

When using the repeater gadget, you can limit the total  number or repeated groups of fields a user can enter. For example, if a user is entering information regarding awards and your institution has a maximum of six awards - you can limit the repeats to six.

Error Text

The option to enter Error Text is only available on the Validation gadget and is the error message that will appear to the user in the form and upon submission (or workflow action) when the defined 'Rules for making this visible' are met.  

You can also additional Description/help text if desired to better clarify the validation.

Rules for making this visible

The Rules for making this visible option is only available on the Validation gadget and are the defined rule(s) to trigger the Error Text validation for the user in the form and will prevent submission (or workflow action).  You can add as many rules as desired to trigger the validation error - at least one rule is required make the validation text appear.  For example, the below rule is set to trigger if the Sponsor selected in the form is 'To Be Determined':

Once triggered it will display in the form and also upon submission or attempting to take a workflow action (i.e. Approve, Complete Task):

Data Source

The option to select a Data Source will be available on the Data Look up gadgets. This is used to indicate what data should be referenced within the gadget. The options available for selection will vary based on the gadget you are working with.

Single Item

When using the Single Item data lookup, the only option available will be External Data. This refers to external data that is accessed through an API integration. The data will be presented on the form as read-only data that can not be adjusted by the user.

List

The List data lookup can be used to refer to Kuali Data (People, Groups, or Apps) or External Data available through created API integrations.  The list lookup will allow the form submitter to select a single item from a dropdown menu or typeahead gadget based on information provided earlier in the form or associated with a user's profile. 

Multiselect

The Multiselect data lookup can be used to refer to Kuali Data (People, Groups, or Apps) or External Data available through created API integrations.  Functions like the Data Lookup (List) gadget but allows the form submitter to select multiple items from a dropdown menu or typeahead gadget. 

Note: Within Kuali data sets you'll have the options of Edit Available Data and Advanced Settings. The Edit Available Data allows you select the desired fields from the internal source to be available in the Add linked auto-filled gadgets options (and to filter upon). 

The Advanced Settings allows you additional configuration options on the data being pulled in the lookup.  First, you can specify when the data should update in the document if the linked data changes.  You can select 'Never' to not update regardless if it's changed in the primary document or 'When the linked document is saved' so it will reflect the updated data in the primary document once it's saved.  You can also put additional lookup filtering to limit lookup values based on certain criteria from the available data (i.e. Workflow status, Multiple choice, Date picker, etc.). Also, if versioning is enabled in the app you're linking to in the gadget then you'll have additional document updating and filtering options - more information can be found in the Document Versions article.

Headless Integration

Headless Integration will only be available on the Single Item Data Lookup. This setting will hide the integration gadget on your form, but will still run in the background.  This allows you to use the gadget for integration purposes without exposing data on the form.  

Add Linked Auto-filled Gadgets

Adding linked auto-filled gadgets will allow the display of multiple pieces of data related to the same selection. The fields available to display will vary based on the chosen data source. 

For example, if you have added a List lookup to the form, and you have selected Kuali People as the data source - you could also choose to include fields such as Display Name, School ID, Email, or Username to display as part of the selection.

The linked auto-filled gadgets are added by dragging them into the form, and they will noted as linked through the chain icon that appears next to them.