Add Dynamic Behavior to a Form

Use events to introduce dynamic behaviors into your web forms, and combine them with actions, conditions, functions, and REST connector calls.

For example, you can introduce the following behaviors into your forms:

• Populate data in a control field based on another control field in the form. For example, a Country select field will impact the State select field and the State select field will impact the City select field.

• Enable control field validation based on another form control field. For example, if Start Date is given then End Date is mandatory or a Full Name gets its value from the First Name and Last Name.

• Make a REST call on demand, store the call’s response, and use response data in an event action or condition.

  Note:

  To use logged-in user's credentials when loading a form to execute a REST operation, define a REST connector without credentials. To use the same operation as a service call in the process, define another identical REST connector with credentials. This applies to internal REST API calls only.

Topics:

• Configure Events

• Specify Actions

• Specify Conditions

• Specify Functions

• Specify Filters in Events

• Reuse Event Snippets

• Specify Custom Outcomes for Forms

• Execute REST Connector Calls in Events

• Populate Controls Using REST Calls

• Link and Refresh List of Value Fields

• Examples of Loops in Forms

• Example of Current Logged in User Data Function

Configure Events

By configuring one or more events on a control or presentation, you change the control or presentation’s behavior. Configuring events in forms enables you to trigger connector calls, actions, conditions, and functions.

To configure events for a control or presentation:

1. In the web forms editor, select a control or presentation, and locate the Events options.
   1. For a control, select the control and scroll down the General tab of the Properties pane until you see Events.
   2. For a presentation, click a blank area of the form so that the Form and Presentation tabs display in the Properties pane. On the Form tab, select a presentation, then select the Presentation tab. Scroll down until you see Events.
   Notice placeholder text displayed in the Events field No events defined.
2. Click Add to define an event.

   The Events section now displays two fields; an Event Name field and a field with a drop-down menu listing event options available for the control or presentation.

   
   Description of the illustration event-options.png
3. Select an event option from the list and, optionally, enter a name for the event.

   Available event options are specific to the selected control or presentation.

   Event	Description	Control or Presentation
   On Load	Fires when a form or presentation loads.	Input Text, Text Area, Date, Time, Date Time, Email, URL, Money, Phone, Checklist, Checkbox, Radio Button, Button, Select, Section, Table, Repeatable Section, Message, Image, Video, Tab and Panel. Presentation
   On Change	Fires when an end user changes the control’s value.	Input Text, Text Area, Date, Time, Date Time, Email, URL, Money, Phone, Checklist, Checkbox, Radio Button and Select.
   On Focus	Fires when the cursor is in the control.	Input text, Text Area, Number, Date, Time, Date Time, Email, URL, Money and Phone.
   On Blur	Fires when the control loses focus.	Input text, Text Area, Number, Date, Time, Date Time, Email, URL, Money and Phone.
   On Submit	Fires before the form or presentation is submitted.	Input Text, Text Area, Date, Time, Date Time, Email, URL, Money, Phone, Checklist, Checkbox, Radio Button, Button and Select. Presentation
   On Click	Fires when an end user clicks the button.	Button and Link
   On Expand	Fires when a section is expanded.	Section
   On Collapse	Fires when a section is collapsed.	Section
   On Expand Toggle	Fires when an expanded section is toggled.	Section
   On Row Add	Fires when an end user adds a row to a table or repeatable section.	Table and Repeatable Section
   On Row Remove	Fires when an end user removes a row from a table or repeatable section.	Table and Repeatable Section
   On Selection Change	Fires when an end user changes the row selection in a table or repeatable section.	Table and Repeatable Section

4. After selecting an event option, click the editing icon next to the events drop-down menu to specify the actions, conditions, connectors, or functions for the event. Click OK to complete configuring the event.

   See Specify Actions, Specify Conditions, and Execute REST Connector Calls in Events.

   Note:

   To cancel an event, click its delete icon. Click Add to define an additional event. You can define multiple events for a control.

You can configure multiple events in a control. The configured events are executed sequentially in runtime. Note that, by default, the newest configured event is added last in the event sequence, and subsequently gets executed last in runtime. But you can re-order events to control their execution sequence. Use the event re-order handlerto re-order events and ensure that they get executed in the correct sequence in runtime. The event re-order handler gets displayed in front of each event name field only when there is more than one event configured on a control.

If you want to disable all events configured for a control, select the control, and specify the action Disable Events. See Specify Actions. This disables all events configured for the control and the events do not get executed in runtime. But note that On Load type of events are exceptions. On Load events get executed even if you specify the Disable Events action.

To enable events in controls where they have been disabled by the Disable Events action, configure the Enable Events action. This ensures that all those events get executed in runtime.

If the Disable Events action is configured for container controls such as tables, repeatable sections, sections, panels, and tabs, then all events in child controls that reside inside them are disabled. This also applies to any rows that you add to container controls after the Disable Events action has been configured in the container controls. To enable events in container controls, and also in all child controls inside the container controls, configure the Enable Events action in the container controls.

Specify Actions

Actions let you trigger changes to a control. You can choose from a variety of control and style actions. For example, you might configure a Clear button to clear the values of other form controls.

To specify actions for a control:

1. Select a control on the form canvas and specify an event for it. For example, choose On Click for a button control. See Configure Events.
2. Click the Event editing icon adjacent to the Event field.

   The event window displays with the selected event option (for example, On Load) at the top, and color coded buttons for adding actions, conditions, or connectors to the event.

3. Click +Action to add an action.

   A solid red Action indicator appears. The Summary field below it displays a compact version of the action you'll define. Use the button at the end of this field to collapse or expand the actions editor.

4. In the Control Name field, select the control the action will affect.
5. In the Action field, select the action to take place. For example, select Clear Value to clear the selected control’s value.

   You can select from a variety of actions grouped in Control and Style categories. The options vary based on the control.

6. If configuring a control action, complete any additional fields that display. Control actions such as Value, Label, Help, Hint, Placeholder, Min Value, Max Value, and Pattern require further configuration for Type and Value fields.
   
   Description of the illustration event-window-type-value.png

   If a Type field displays, select from these options:

   • Constant lets you specify a value for the selected control. Be sure to specify the corresponding value in the Value field.

   • Data Definition lets you use the data from the payload. When you click the adjacent Value field that displays, available items are listed.

   • Control lets you use the data from a control. Be sure to select the control name and property to use.

     Properties are control specific. For example, some controls, such as the number control, have many properties as options. Other controls, such as the image control, only have one property: Hidden. Email and phone controls have a property Placeholder but don't have the Min Value and Max Value properties.

   • Function lets you perform common operations with strings, values and arrays, as described in Specify Functions.

   • Connector Data lets you assign a value from a connector call made from the same event.

   Note:

   You can modify multiple properties of controls such as their value or label. You can also use the data, such as connector data, to modify the control, but you cannot modify data.
7. If configuring a style action, complete additional fields that display for the selected action.

   For example, you might combine a condition with a style action so that if a certain value is exceeded, a control’s color, label, or class changes to alert users.

8. If needed, use the buttons at the bottom of the event window to configure additional actions or specify a condition or connector call. See Specify Conditions and Execute REST Connector Calls in Events.
   Connector calls cannot be executed based on a condition. Connectors are always executed when their event is executed. You can later use the connector response values in any condition or action.

   Note:

   In the event window, use the Undo or Redo buttons to remove or restore recent changes to actions. Use the delete icon to delete an action. Click Cancel to exit the event window without saving changes.
9. After completing the event, click OK, then Save.

Specify Conditions

Conditions let you configure an If/Then/Else condition to trigger an action or connector call for a control’s selected event or a control’s specified action.

To specify conditions for a control:

1. Select a control on the form canvas and specify an event for it. See Configure Events.
2. Click the event editing icon adjacent to the Event field.

   The event window displays with the selected event option (for example, On Load) at the top, and color coded buttons for adding actions, conditions, or connectors to the event.

3. Click +If to add a condition.

   Multiple items display to help you construct and complete the condition.

   • Solid blue If, Then, and Else indicators signal each portion of the condition to complete.

     The Summary field below the If indicator displays a compact version of the condition you'll define. Use the button at the end of this field to collapse or expand the conditions editor.

   • Use the +Condition, +Action, +Else If, and +Else Action buttons to add additional conditions or actions to the condition.

   • Use the fields displayed under the If or Else If indicators to define conditional behavior.

4. Complete the If portion of the condition.
   1. Select a type from the Type field and complete fields that display. Select from these options:

      • Constant lets you specify a value for the selected control. Be sure to specify the corresponding value in the Value field.

      • Data Definition lets you use the data from the payload. When you click the adjacent Value field that displays, available items are listed.

      • Control lets you use the data from a control. Be sure to select the control name and property to use.

        Properties are control specific. For example, some controls, such as the number control, have many properties as options. Other controls, such as the image control, only have one property: Hidden. Email and phone controls have a property Placeholder but don't have the Min Value and Max Value properties.

      • Function lets you perform common operations with strings, values and arrays, as described in Specify Functions.

      • Connector Data lets you assign a value from a connector call made from the same event.

   2. Select an operation. For example, choose is True from the drop-down field.

      Tip:

      To check for a null value, choose is False; if a control has no value, the condition result returns true. Conversely, choose is True to check that a property is present.

      Note:

      You can also check if a particular property, such as value, of a control is empty or not using the is empty operation. Controls of array type (repeatable sections or tables) are considered empty if the array is empty. A check box or a checklist is considered empty if no selection is made.
   3. Based on the selected operation, complete a second Type field and additional fields that display. You must specify a type and additional fields for all operations except when is True or is False are selected.
   4. To add another condition, click +Condition, specify if it's an And or an Or condition and configure it.

      For example, as shown in the figure, you can configure a condition for the Cost control field of a travel request form such that if cost is greater than 5000 and the duration of travel is less than 14 days then you can set further Then or Else conditions to be triggered.

      
      
      Description of the illustration add-another-if-condition.png
      

5. Complete the Then portion of the condition by clicking +Action and completing the action. See Specify Actions.

   For example, for the Cost control of a travel request form if the cost is greater than 5000 and the number of days of travel is less than 14 then the Justification field is required in the form.

   
   Description of the illustration then-condition.png

6. Complete the Else portion of the condition by clicking +Else Action and completing the action.

   For example, for the Cost control of a travel request form if the cost is greater than 5000 and the number of days of travel is less than 14 then the Justification field is required in the form else it's optional.

   
   
   Description of the illustration else-condition.png
   

7. If needed, add and configure additional If/Then/Else conditions.

   Note:

   In the event window, use the Undo or Redo buttons to remove or restore recent changes to conditions. Use the delete icon to delete a condition. Use up and down arrows to reorder conditions within the window. Click Cancel to exit the event window without saving changes.
8. After completing the event, click OK, then Save.

Specify Functions

Use functions in event actions and conditions to perform common operations with strings, values, and arrays. For example, use a function to add two values, concatenate two strings, or sum items in table rows.

Important points about functions:

• You can specify parameters for selected functions. The parameter value can be a constant, data definition value, control value, other function, or connector data value.

• Some functions support selecting arrays of data or repeatable controls.

• You can nest functions, such as concatenate multiple strings or the results of multiple rows. You might select a concatenate function and concatenate a data value, connector data value, or control value with another value such as a constant.

Choose from the following mathematical, aggregation, and text functions.

Function Category	Function Name	Parameters	Description
Other	Create UUID	None	Generates a universally unique identifier.
Other	Current browser language	None	Returns the locale that the user has specified in the browser settings. For example: en, en-US, de, fr
Other	Get application name	None	Returns the current application name.
Other	Get Geolocation	(Number)	Returns a String with the JSON representation of an object that contains the current position of the device. You must specify a timeout value in milliseconds to wait for the browser's response. A timeout of 10000 milliseconds works well in most situations. The returned String with the JSON representation is similar to: {“latitude”:37.556685099999996,“longitude”:-122.2777825,“altitude”:null,“accuracy”:45,“altitudeAccuracy”:null,“heading”:null,“speed”:null} You can use the function Parse from JSON to convert the returned String to an object, and then the function Get Property to access the attributes in the object. For example, to access the latitude use: Get Property(Parse from JSON(Get Geolocation(10000)), "latitude")
Date	Current Date	None	Generates the date in yyyy-mm-dd format.
Date	Current Time	None	Generates the time in 24 hour T00:00:00 format (for example, T23:59:59).
Date	Current Date Time	None	Generates the date/time in yyyy-mm-dd T00:00:00 format.
Date	Add Seconds	(Date, Number)	Adds the number of seconds to the given date, time, or date/time.
Date	Add Minutes	(Date, Number)	Adds the number of minutes to the given date, time, or date/time.
Date	Add Hours	(Date, Number)	Adds the number of hours to the given date, time, or date/time.
Date	Add Days	(Date, Number)	Adds the number of days to the date.
Date	Add Months	(Date, Number)	Adds the number of months to the date.
Date	Add Years	(Date, Number)	Adds the number of years to the date.
Logic	And	(Input1, Input2, Input3...)	Checks if Input1 && Input2 && Input3... is true or false.
Logic	Or	(Input1, Input2, Input3...)	Checks if Input1 || Input2 || Input3... is true or false.
Logic	Not	(Condition)	Negates the value of the specified condition.
Logic	Inline If	(Condition, ValueIfTrue, ValueIfFalse)	Implements an If…Else statement. If the condition specified is true, the first value is returned as the result, else the second value is returned. Example: Inline If (N=5, 60, 70) returns 60 if N=5 else returns 70.
Relational	Equal (=)	(Input1, Input2)	Checks if Input1 equals Input2 and returns a Boolean value.
Relational	Greater than (>)	(Input1, Input2)	Checks if Input1 is greater than Input2 and returns a Boolean value.
Relational	Less than (<)	(Input1, Input2)	Checks if Input1 is less than Input2 and returns a Boolean value.
Relational	Greater than or equal to (>=)	(Input1, Input2)	Checks if Input1 is greater than or equal to Input2 and returns a Boolean value.
Relational	Less than or equal to (<=)	(Input1, Input2)	Checks if Input1 is less than or equal to Input2 and returns a Boolean value.
Math	Sum ( + )	(Number, Number)	Adds two numbers.
Math	Summation	([Number])	Adds arrays of numbers.
Math	Subtract ( - )	(Number, Number)	Subtracts numbers (for example, 10–5).
Math	Multiply ( * )	([Number])	Multiplies numbers. For example, multiply all values in a column.
Math	Divide ( / )	(Number, Number)	Divides numbers and includes the decimal portion, up to 10 decimal places (for example, 4/3=1.3333333333).
Math	Integer Division	(Number, Number)	Divides numbers and truncates the result (for example, 5/2=2, -5/2=-2).
Math	Modulo ( % )	(Number, Number)	Finds the remainder after division of one number by another.
Array	Min	([Number])	Finds the minimum value in an array.
Array	Max	([Number])	Finds the maximum value in an array.
Array	At Index	([Any], Index)	Finds the value at a particular index of an array or string.
Array	Count	([Any])	Finds the count value in an array.
Array	Avg	([Number])	Finds the average value in an array.
Array	Concat	([Any])	Joins array values.
Array	IndexOf	([Array], Element)	Returns the index of an element in an array. For example, IndexOf ([1,2,3], 1) returns 0. Returns -1 if the element specified is not found in the array.
Text	Concat	([String])	Joins a text string.
Text	Split	(String, String)	Splits a string into an array using the second parameter as a separator. For example, you can split a series of numbers in a text field into a checklist.
Text	Join	([String], String)	Joins an array into a string using the second parameter as a separator. For example, you can fetch values of all rows within a table column and create a series.
Text	Trim	(String)	Removes leading or trailing spaces.
Text	Contains	(String or Array, Element)	Checks if a string or array (within a control) contains a specific element and returns a Boolean value.
Text	Replace	(String, String, String)	Replaces a text string. Uses three parameters, where: The first string is the original text The second string is the value or regular expression that will be replaced by the new value The third text is the replacement For example, REPLACE("Hello World!", "Hello", "World") returns "World World!" Note: In regular expressions there are 12 characters with special meanings: backslash \, caret ^, dollar sign $, period or dot ., vertical bar or pipe symbol |, question mark ?, asterisk or star *, plus sign +, opening parenthesis (, the closing parenthesis ), opening square bracket [, and opening curly brace {. If you want to use any of them as regular characters, you will need to escape them with backslash \.
Text	Matches	(String, String)	Checks if two strings or expressions match and returns a Boolean value.
Text	Substring	(String, StartingIndex, Length)	Returns a substring of a string, beginning at the specified starting index up to the length indicated. For example, Substring ('apple', 0, 3) returns app.
Interval	Duration in days	(Date, Date)	Calculates the difference between two dates and returns the result in number of days. To calculate the interval, you can manually enter start and end dates in the event window or supply them through date controls present within the form. If you choose to manually provide dates for calculation, use the following valid formats: mm-dd-yyyy yyyy-mm-dd 7 October 2017 7 Oct 2017 December 25, 2017 You can use the following separators interchangeably: - / , space
Interval	Duration in months	(Date, Date)	Calculates the difference between two dates and returns the result in number of months.
Interval	Duration in years	(Date, Date)	Calculates the difference between two dates and returns the result in number of years.
Current Logged in User Data	Current user's ID	None	Returns the current logged in user's ID.
Current Logged in User Data	Current user's first name	None	Returns the current logged in user's first name.
Current Logged in User Data	Current user's middle name	None	Returns the current logged in user's middle name.
Current Logged in User Data	Current user's last name	None	Returns the current logged in user's last name.
Current Logged in User Data	Current user's email	None	Returns the current logged in user's email.
Current Logged in User Data	Current user's manager's ID	None	Returns the current logged in user's manager's ID.
Current Logged in User Data	Current user's manager's first name	None	Returns the current logged in user's manager's first name.
Current Logged in User Data	Current user's manager's middle name	None	Returns the current logged in user's manager's middle name.
Current Logged in User Data	Current user's manager's last name	None	Returns the current logged in user's manager's last name.
Current Logged in User Data	Current user's manager's email	None	Returns the current logged in user's manager's email.

To use a function:

1. In the web forms editor, select a control on the canvas. Note that you can also apply events and functions to presentations, as described in Configure Events.
2. On the Properties pane, scroll down to the Events field. Click Add to add an event and select its type in the drop-down field (for example, On Change).
3. Click Edit next to the event you just added.
4. In the event window, add an action or condition by clicking the +Action or +If button.
5. Configure the action or condition to use a function.
   • For an action, select a control on which to apply the function in the Control Name field. In the Action field that displays, select Value in the Action field. In the Type field that displays, select Function, then choose a function from the functions listed by category in the Function field. Optionally, provide a name for the function in the Function Name field to easily identify it (this name displays in the Action Summary field).
   • For an if condition, select Function in the Type field that displays, and choose a function from the functions listed by category in the Function field. Optionally, provide a name for the function in the Function Name field to easily identify it (this name displays in the Condition Summary field). Complete the condition in the remaining condition fields.
6. Specify parameters within parentheses for functions that allow them.
   Additional fields display within parentheses for functions that include parameters, such as math functions.
   The Compact Function field displays a summary of the function you define. Use the button at the end of this field to collapse or expand the functions editor.
7. Click OK to close the event window. Click Preview to test the function. For example, a simple application uses a function set on the Value field to sum values each time a user enters or changes a value in the table, and displays the calculated value in the Total field. If the total exceeds a set amount (constant), a style action displays the total in red letters.
   
   Description of the illustration specifying-functions.png
   

Specify Filters in Events

Filters let you selectively use a subset of data from a larger set. For a form control, you can define a filter within an event and use the filter data in other controls through event actions and conditions.

To specify filters within an event:

1. Select a control on the form canvas and specify an event for it. See Configuring Events.

2. Click the event editing icon adjacent to the Event field.

   The event window displays with the selected event option (for example, On Change) at the top and color coded buttons for adding actions, conditions, connectors, or filters to the event.

3. Click +Filter to add a filter, and specify the data source from which you want to filter specific information. You can choose data attributes, another control, or a REST connector.

4. If the data source selected is valid (of the type: array), additional +Criteria and +If buttons appear as shown in the following figure:
   Description of the illustration filter.png

5. Click +Criteria to specify how data is filtered from the data source. You can also use an If condition to do the same.

   Note:

   You can specify more than one way to filter data from the source. If you specify an Or condition, the results are combined or unioned. If you specify an And condition, the result is the intersection of that filter condition with the other filter conditions.

   You can also specify another Filter (specified before) as the source type for your filter. This gives you the ability to filter data from another filter.

6. Provide a suitable name for the filter; the information extracted from the data source is stored within this filter.

7. In the same event window, you can use the data in the filter to populate other controls dynamically through actions or conditions.

8. After completing the event, click OK, then Save.

Filtering Using Events – An Example

This section demonstrates filtering through events using a web form with a drop-down select control and a table.

Based on the option you choose in the select control, you will be able to filter data from a data source and selectively use the extracted data to populate the table.

In this example, we use a previously created REST connector to fetch data from a web server, which contains a list of items. Each item, in this case, is a complex data object that contains personal details of individuals, such as first name, last name, unique ID, company name, email, phone number, city, and so on. To create a REST connector from scratch, see Creating a REST Connector.

We use this REST connector to define a global connector call, globalResponse, under Presentation properties of the form. Want to know more about global connectors? See Working with Presentations. In addition, this connector also serves as the input to the select control.

Now, let’s configure controls and events in the web form to suit this example.

1. Add and configure a drop-down select field on the form’s canvas.

   1. From the Basic Palette, drag and drop a Select control onto the canvas.

   2. Select the control, and on the General tab, change the Label field to First Name.

   3. Under Options Source, select the Connector option and populate the Resource and Operation fields with respect to the REST connector defined within the application. See Populating Controls Using REST Calls.

   4. Under Response, specify the items list to display as options of the control.

      1. For this particular example, we map the first name attribute to the Label Binding field, so that only first names of all individuals appear as options in the select control. Also, the unique ID attribute is mapped to the Value Binding field as follows:
         
         Description of the illustration filter-response.png
         

2. Add and configure a table control on the form’s canvas.

   1. From the Advanced Palette, drag and drop a Table control onto the canvas.

   2. Add two additional columns, and edit column labels as Last Name, Organization, and Email.

   3. Drag and drop an input text control into each column.

3. Click on the select control, and define an On Change event for it in the General tab.

4. Click the event editing icon to open the event window. In this window, click +Filter to add a filter.

5. The following figure shows the event configuration for this example:

   1. Connector data is set as the data source and its value comes from the global connector call, globalResponse, defined previously.

   2. The subsequent Filter section shows how the data is filtered from the source, that is, when the ID of an item in the source list matches with the ID of the option selected by the user, all data associated with that item is stored in the filter, filter.

   3. An event action selectively uses the data contained in this filter to populate the table. Although each item may have several attributes associated with it, here we use only last name, company, and email attributes. We map each of these attributes a corresponding input text control or table column.
      
      Description of the illustration filter-actions.png
      

      Note:

      While defining event actions, if you choose to map the filter data to a control of simple data type (for example, input text), you have to specify an index value in addition to the attribute that you would like to map to the control.

6. When the form loads, the select control displays first names of all individuals as follows:
   
   Description of the illustration filter-names.png
   

7. After you make a selection, all data associated with the selected option is stored within the filter, and this data is selectively used to populate the table as shown in the following figure:
   
   Description of the illustration filter-output.png
   

Reuse Event Snippets

You can extract event snippets from an event editing window and reuse them across the form’s presentation.

Define a complex event snippet once and reuse it across different events, thereby saving time and minimizing errors. You can manage all the extracted snippets from the web form’s Presentation tab. Additionally, updating a global snippet definition updates all instances of the snippet within other events.

Topics:

• Extract a Snippet

• Use a Snippet

Extract a Snippet

Extract any event block, such as action, condition, loop, connector, or filter, as a global snippet and reuse it in other event definitions.

To extract an event snippet:

1. In an event definition window, click Extract Snippet.

   A name field appears at the top of the window and all the available blocks are selected for extraction.

   
   Description of the illustration event-snippet.png

2. Turn a block’s toggle button off to exclude it from extraction.
3. Enter a suitable name for the snippet and click OK.

   The snippet is now available for reuse in any event within the same presentation. You can access and edit the extracted snippet from the form’s Presentation tab. See Work with Presentations.

Use a Snippet

Use previously extracted event snippets in any event definition.

1. In the event definition window, select + Reusable Snippet at any point in your definition.
2. Select an extracted snippet from the drop-down list to add it to the window.
3. Additionally, you can click Detach to independently retain the blocks within a global snippet, but not the snippet as a whole.

   Note that changes made to the global snippet won’t reflect in the blocks you’ve retained.

4. Click Delete to remove the snippet and all its constituents.

Specify Custom Outcomes for Forms

In addition to Submit, you can specify custom outcomes (such as Approve, Reject, On Hold, and so on) for a form according to your requirements and test the same in the Composer. Also, you can specify conditions to prevent users from submitting a form.

You can trigger submit of a form with a custom outcome using any event on a control or presentation. Want to know how to define events? See Configuring Events.

For example, let us specify a form’s outcome value through an On Click event on a button control. In the event window:

1. Click +Action and select the Trigger Outcome action available for the Presentation control.

2. Specify a custom value in the Outcome field, for example, REJECT.

   When a user clicks this button in runtime, the form is submitted with the outcome value as REJECT.

   
   Description of the illustration outcome-trigger.png

You can also use the outcome value of a form in any control using an On Submit event. As an illustration, let us define an On Submit event for an input text control to display the form’s outcome value. In the event window:

1. Click +Action and select parameters for all fields as shown in the following figure.
   Description of the illustration outcome-submit.png

2. When a user submits the form in runtime, the input text control is populated with the form’s outcome value.
   
   Description of the illustration outcome-reject.png
   

   You can input and test different custom outcomes using the Preview feature, see Previewing Forms and Their Payload.

Preventing Form Submit

By default, the form submission is prevented when the form is incomplete or invalid. You can also define custom conditions within an On Submit event to prevent users from submitting a form. For example, you can prevent submit based on a data attribute’s or control’s value.

The following example shows an On Submit event defined for a Presentation. Here, the form submission is prevented if the outcome variable of the form contains a specific value, that is, PREVENT.

Description of the illustration outcome-prevent.png

Execute REST Connector Calls in Events

Executing a REST call in an event enables you to store the call’s response and use it in an event action or condition.

Examples

• Configure a web form that prompts users to enter a zip code. Add an event that calls a weather site to query weather values. Store the response data, then add actions to the event that display temperature-related values.

• Configure a web form that prompts users to enter a company name and click a Get Quote button. Add an event to the button that calls a stock service site to query stock values for the specified company. Store the response data, then add event actions that display read only stock value fields.

  
  Description of the illustration connector-call-example.png

Before configuring a REST connector call, create the REST connector you want the event to call.

To add and configure the connector call:

1. In the web form editor, select a control, add an event, and select its type.
   For example, include an On Change event for a text input control or an On Click event for a button control. See Configure Events.
2. Click the event’s Edit icon to display the Events window.
3. Click +Connector to add the connector call.
4. Configure the connector call.
   1. In the Connector field, select a REST connector from those defined for the application.
   2. In the Resource and Operation fields, select the resource to access and operation to perform as configured in the REST connection.

      Note:

      You can also perform a POST operation from the event window. Currently, for POST operations, arrays aren’t supported for requests but can be successfully received and handled in responses.
   3. Complete the connector call parameters (query, header, or body) that display based on the operation you choose. For example, the illustration below shows a connector call with a GET operation and a template parameter called message.

      You can configure query parameters either from static texts or from form expressions (as shown in the example). Use Form Expressions to specify complex values in query parameters based on functions, payload data, and control values. Get values from payload data directly without dependency on controls by using Data Definition type. Configure functions by using the Function type, for example, specify a concat function to combine two or more values.

   4. Enter a variable name in which to store the response data (for example, quoteResult or weatherInfo).
      
      Description of the illustration add-connector-call.png
5. Optionally, configure error handling. You can set actions to address all errors or a selected error detected in the call.
   1. Click +Error Handler to add an error handler.
   2. In the Run on Error field, select an error (or all errors) to detect.
   3. In the Control Name field, select the control on which to identify the error. In the Action field, select the control or style action to take.
6. Collapse the connector call.
7. Below the connector call, configure actions, conditions, or additional connectors, and click OK.
   A common use case is to add an action to display response data from the connector call. Click +Action, select a control, specify Value as its action, Connector Data as its type, and the response variable data to display in the Value field.
   
   Description of the illustration add-connector-action.png

   Note:

   • If the connector data is an array of elements, you can specify a particular array item in the response Value field by entering the corresponding array index, for example, quoteResult[0].lastPrice[1].price.

   • If the REST response consists of a complex data object, you cannot map the data object directly into a control (such as Input Text or Text Area) through an event. Instead, you must specify which details of the complex data object should be mapped to the control, along with an appropriate function such as Concat (if required), in the event window. For example in a REST response, if a complex data object called name contains two elements, firstname and lastname, you must specify which one of these elements should be populated into the control. If you require both of these elements to be populated, use a function such as Concat with a suitable separator in the event window.

Populate Controls Using REST Calls

Dynamically populate controls such as drop-down select, check list, radio button, table, and repeatable section controls with data using REST connectors.

1. Drag and drop a drop-down select, a check list, a radio button, a table, or a repeatable section control onto the canvas to populate it with data using a REST call.
2. Select the control and optionally, on the General tab in the Properties pane, edit the name, binding, label, and other fields.
3. For a drop-down select, check list, or radio button control, in the Options Source field, select Connector and then configure the fields under the Options Source field to define the values based on a REST call. For a repeatable section or table control, select the Use Data From Connector field and configure the fields under this field.
   1. Connector: Select a REST connector from the defined list of connectors for the application.
      A REST connector lets you fetch data and perform tasks based on that data. See Create REST and Web Service Connectors.
   2. Resource: Select a resource from which data should be fetched.
   3. Operation: Specify an operation to call.
      An operation indicates the task you want to perform. For example, a user may use an operation to fetch all the countries or to fetch a list of states based on a country code.
   
   Description of the illustration connector-options.png
4. Based on the call, the system will display a list of required parameters (payload values) and a response below the Options Source field or the Use Data From Connector field.
   1. Payload values: Specify the information to pass to the REST connector (parameters). You can specify query, header, or template parameters.
      If you selected Text, enter the parameter information. Or, if you selected Control value, select a control value from the available options.

      Note:

      Text parameters are secure and remain on the server.
      
      Description of the illustration payload-values.png
   2. Response: Define how the response will be mapped to the control properties:

      • Options List: Define the mapping by specifying an attribute list from the response that contains the items to display as the options in the control.

      • If the list is a simple type of list such as a list of strings or numbers, then no label and value mappings are needed. The value of the item in the list will be used as both the label and the value of the option.

        If the list consists of complex elements, then you need to specify a mapping using the Label Binding and Value Binding fields to identify the label and value.

      Note:

      • For a table control, define how the response will be mapped to each column in the table. For a repeatable section, define which property from the response will be mapped to which control inside the repeatable section.

      • If the connector data is an array of elements, you can map a particular array item to a Response field by entering the corresponding array index, for example, response[0].RestResponse[1].result.

      
      Description of the illustration response.png
5. You may also use the Skip Upon Load property to determine when the connector data loads into the control.
   • Deselect the checkbox (default state) to allow connector data to be populated into the control when the form loads.
   • Select the checkbox to prevent connector data being populated into the control when the form loads. When you use this option, you must explicitly execute a connector refresh for the data to load into the control.
6. Optionally, in the Events field, configure the events for the control. See Add Dynamic Behavior to a Form.

Test the dynamic fetching of data by testing the application. And, verify if the mappings you defined work correctly as expected.

Link and Refresh List of Value Fields

Use the Refresh Connector control action in an event so that each time an end user makes a selection in a LOV field, REST call data is refreshed and reflected in another LOV field. For example, in an order application form, after a user selects from a Category drop-down field, the list of products for that category only displays in a Product drop-down field.

To refresh an LOV field:

1. In a web form, configure two LOV controls (select, checklist, or checkbox) to use the same REST connector to populate and return values such as categories and products. See Populate Controls Using REST Calls.
   In this LOV use case, the Product control has query parameters set to search for the Category control’s value.
2. Select the first control (for example, Category field). On the Properties pane, scroll down to the Events field and add or edit an event. For example, add an On Change event and click Edit to edit the event.
3. In the event window, add an action by clicking the +Action button.
4. In the Action field that displays, select Refresh Connector. This setting means that each time users make a selection in the Category field, the Product field’s REST call is refreshed to return product values for the selected category.
   
   Description of the illustration linking-refreshing-list-values.png
5. Click OK to close the event window. Click Preview to test the function.

Examples of Loops in Forms

You can use loops in form controls to execute actions that need to iterate. The iterator can be a number or an array. Loops are a way to execute the same action multiple times in a form.

Let us explore with some examples how loops work in forms.

• Configure a Simple Loop
• Configure a Loop With an Array

Configure a Simple Loop

In this example, let us add multiple rows to a table by configuring a simple loop with a number iterator.

1. Drag and drop a table control onto your form’s canvas. Then drag and drop an InputText control in the table’s column.
2. Select the table control, and in the properties pane that displays scroll down till you find Events. Click to configure an event for the control.
3. Select On Load from the drop-down list, and then click the editing icon.
4. In the event On Load window, click Loop. Select Constant in the Type drop-down list, and enter a number in the Value field, for example: 5. This value determines the number of times looping occurs when the form loads.
5. Click +Actions. In the Control drop-down list select Table, and in the Action drop-down list select Add Row.

   
   Description of the illustration loop-example1.png

   When the loop executes (on form load), the Add Row action gets executed 5 times.

6. Click OK.
7. Preview the form and see how it works.

Note that 5 rows get added to the table as the form loads.

To see how the loop executed, click Log in the Preview window.

.

Configure a Loop With an Array

In this example, let us configure a loop with an array of strings.

1. Drag and drop a table control onto your form’s canvas. Then drag and drop an InputText control into the table’s column.
2. Select the table control, and in the properties pane scroll down till you find Events. Click to configure an event.
3. Select On Load from the drop-down list, and then click the editing icon.
4. In the event On Load window, click Loop. Select the type as Data Definition in the Type drop-down list, and enter the value as list in the Value field.

   Note that list is already defined as an array of strings.

5. Click +Actions. From the Control drop-down list, select Table. From the Action drop-down list, select Add Row.
6. Configure another action. Click +Actions.
   1. Select Table in the Control Name drop-down list, and specify Last in the Which? field.
   2. In the Control Name that displays, select InputText, and then select Value in the Action drop-down list.
   3. In the Type field that displays, select Loop, and then select Value from the Value drop-down list.

      
      Description of the illustration loop-example2.png

      Note that the Loop type can have three options as value.

      • Index: 0-based index of the iteration (0, 1, 2, 3...)
      • Position: 1-based index of the iteration (1, 2, 3, 4...)
      • Value: The value of the current iteration. If the iterator is a number, this value will be same as Index.
7. Click OK.
8. Preview the form and see how the loop works.
   1. In the Preview window, click Reload with Payload.
   2. In the Custom Payload window, specify an array, and click OK.

      
      Description of the illustration loop-example2-payload.png

   3. You can see that the loop executes with the specified array.

      On form load, the table displays two rows with the values (red, blue) specified in the array.

Example of Current Logged in User Data Function

Use the Current Logged in User Data function within actions in form controls to get information about users in forms.

The Current Logged in User Data function allows you to dynamically populate information about the current user’s id, email, and the first, middle, and last name in forms. Additionally, you can also get the current user’s manager’s id, email, and the first, middle, and last name.

Let us explore how to use the Current Logged in User Data function with an example. In this example, let us configure a form with three fields (user’s id, first, and last name) such that they automatically populate when the form loads. Then configure another field (manager's email) such that it gets populated when the user clicks a button GetManagerEmail.

1. Drag and drop an Input Text control onto the form’s canvas. Then drag and drop two more Input Text controls and place them side by side.
   1. Change the name of the first control to UserID and its label to User ID.
   2. Change the names of the controls that you placed side-by-side to FirstName and LastName. Change their labels to First Name and Last Name.
2. Configure the User ID control.
   1. Select the control, and in the properties pane scroll down till you find Events.
   2. Click to configure an event. Select On Load from the drop-down list and then click the editing icon.
   3. In the event On Load window, click + Action. In the Control Name field select UserID and then select Value from the Action drop-down list. In the Type field that displays, select Function.
   4. In the Function drop-down list that displays, scroll down till you find Current Logged in User Data, and then select Current user’s ID.

      
      Description of the illustration current-loggedin-user1.png

   5. Click OK.
3. Configure the First Name and Last Name controls.
   1. For each control, select the control and repeat steps 2b to 2d. Ensure to select the correct control (First Name or Last Name) in the Control Name field.
   2. For the First Name control, in the Function drop-down list, select Current user’s first name under Current Logged in User Data.
   3. For the Last Name control, in the Function drop-down list, select Current user’s last name under Current Logged in User Data.
4. Drag and drop another Input Text control, and change its name to ManagerEmail and its label to Manager Email. Then drag and drop a Button control under it. Change the name and label of the button control to GetManagerEmail.
5. Configure the GetManagerEmail button.
   1. Select the button, and in the properties pane scroll down till you find Events.
   2. Click to configure an event. Select On Click from the drop-down list and then click the editing icon.
   3. In the event On Click window, select ManagerEmail from the Control Name drop-down list, and then select Value from the Action drop-down list. In the Type drop-down list that displays, select Function.
   4. In the Function drop-down list that displays, scroll down till you find Current Logged in User Data, and then select Current user's manager's email.
   5. Click OK.
6. Click Preview.

   When the form loads, the user's id, first, and last name gets auto populated into the User ID, First Name and Last Name fields. The Get Manager Email field is empty.

   Click the GetManagerEmail button. Note that the manager’s email gets loaded into the Manager Email field.

   
   Description of the illustration current-loggedin-user2.png