Versions Compared

Old Version 41

changes.mady.by.user Megan Ellis

Saved on

compared with

New Version Current

changes.mady.by.user Megan Ellis

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Each control setting property is explained below. Keep in mind that all controls do not have the same setting properties.

...

A control’s label is displayed on your form beside or above the control. When you first drag in a control it is assigned an arbitrary and unique label—checkbox 43 for example. Obviously for your users’ sake you will want more meaningful labels. Change a control’s label either on the form itself (by clicking the control and selecting the label) or by overlaying the arbitrary name in the Properties Label field.  Message controls are the only controls without labels—they are used for static text so you don’t need a label, too.

...

The whitelist allows a full range of text and structural body HTML: a, b, blockquote, br, caption, cite, code, col, colgroup, dd, dl, dt, em, h1, h2, h3, h4, h5, h6, i, img, li, ol, p, pre, q, small, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, u, ul. This means that you can only use these tags in a label's markup. You can find information about XHTML tags at this w3schools.com website. These restrictions also apply to help, hint, label, validation message, rule name and description. the Help property.

Let's say you want to underline (6 characters) in the label of a password field.

...

Tip

The < sign is not allowed in a label for Input controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Control Type

This applies to selection controls (dropdowns, radios and checkboxes) and most input controls (text, text area, email, phone, quantity, number, table, and repeat) and is populated automatically when you first drag in a control.  You can change this property if you want to switch a control in your form to a different type of control. This saves you from having to remove the original control and drag in a new one. The Control Type property is also used to change a date control to a time or date/time control. See Date, Time, Date/Time for more information.

...

This property lets you create a tooltip that will display in your form when the user mouses over the control. Simply type the text for your tooltip in the Hint field.   The Hint property does not support html markup.

Help

This property lets you provide for your users more detailed help about a specific control. If you enter text here, a  icon will appear next to the control on your form.  When the user clicks , the help text you supplied in the Help property will be displayed in a floating box.

...

This lets you display a specific error message if the user does not supply a valid value in the control.  If you leave this property blank users will get generic feedback (an “invalid value” message, for example) if they supply a bad value—but if you use this property, you can make the error message more helpful. The Error Message property does not support html markup.

For example, if you are using a pattern that requires the user to enter an area code of 203 in a phone control, you can use the Error Message property to let users know this explicitly if they try to enter a different area code.

...

 adjusts the date to be within 80 years before or 20 years after if the date is expressed with a two digit year. For example, using a pattern of "MM/dd/yy" and the current date/time of Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only year strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits, is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC. Live forms frevvo will always format as 4 digit years.  

Note

The date will be converted to the standard xsd:date format of yyyy-mm-dd  in the submissions XML document. Here is an example: <Order Date>2012-03-06</Order Date>. Refer to Viewing XML Documents for more details.

Rules can be applied to the Date control in all variations.

...

By using this property, time entries entered into the form are reformatted to match the selected format. For example, if you choose a military time format of hh:mm:ss and enter 2:00 PM the time value will display in the form as 14:00:00. It will be saved in the submissions XML document as <Order Time>14:00:00</Order Time>. Refer to Viewing XML Documents for more details.  

If you choose a format other than automatic,  parses and formats the time and dateTime control values with a locale specific date formatter. Read this documentation for more information about date/time controls and internationalization.

...

Note

The local time will be converted to and saved in UTC format and the date will be converted to the standard xsd:date format of yyyy-mm-dd in the submission XML document. Here is an example: <OrderDate>2013-08-12T19:13:00Z</OrderDate>. Refer to Viewing XML Documents for more details. 

Date and Time Format on Mobile Devices

...

You can change the color displayed by Required fields by modifying a Style and then applying it to your form/flow. If you prefer an asterisk to designate required fields, enable the Accessibility feature by checking the Accessible property on the form/flow Properties pane. This feature was built to allow visually impaired users to access forms. Enabling this property adds an asterisk (*) for all required fields. If users move ahead from that field without filling it, they will see the error, "You can't leave this empty <control name>".

...

What if you want a '=' character to appear in your options? Since the 1st equal sign is the delimiter between the value and the label, you can put an equal in the label as follows. For example, suppose you want your label to be "good = gold." If you enter this as the option, what you'll see in your dropdown is the label "gold." To solve this, use this options string: "a=good = gold". Now the label will be as you wish. Currently, if there is an equal sign in the label, it is not possible to also have an equal in the value. This will be supported in a future release.

Options label may include HTML formatting. If you find that the HTML used does not display on the PDF Snapshot, change the Print Font to a font that supports the character/markup you are using. For example, if you use a checkmark as an options label (&check;), use the DejaVu Sans print font which supports this character.

The choices cannot be changed if they have been generated from an uploaded schema, since the schema specifies the choices. On controls generated from schema, you won’t see the Options property in the Properties area. However, you can change the option labels. See 1063682390 this documentation.

Checkbox option values cannot contain spaces. For example if you set your checkbox option to "Black Cat=Black Cat", it will automatically be converted to "Black_Cat=Black Cat" as soon as you tab out of the options property. This is because checkboxes are multi-select. When the form is submitted, space is used as the separator character for the checkbox control's value. Thus a space character cannot be in the value itself as it would be interpreted as a separator.

The < sign is not allowed in an option label for Selection controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Tip

Design mode allows options with same value and different label. If you set the options of a Selection control as shown below then click the save and test icon, you will only be able to select one option of the Selection Control in Test mode.

  • a=b

  • a=c

This can be a an issue when working with dynamic selection controls. Designers must be careful that the web services they are using do not return data with duplicates values.

...

  1. Click on the selection control (Checkbox, Dropdown, Radio)
  2. Select Web Service from the Option Src dropdown


     
  3. Enter the URL of the RESTful web service that you are going to to retrieve the option data from. Data is retrieved using HTTP GET. The URL can contain templates and the options will be automatically updated whenever the value changes of any control referenced by a template in the URL.

    Ex: /http(s)://10.0.0.27/:8081/database/BIRT/allCustomers?_mediaType=json - This URL returns a list of all customers from a database The _mediaType parameter specifies that JSON results are returned. In this example, the Database Connector integrates with the database to execute the query. The Database Connector is a Restful service that returns results in XML or JSON.
     
  4. After entering the Options URL for your web service, click the save and test icon. Examine the results in the debug console to determine the Value and Label Bindings.
  5. The syntax for selection control options is <value>=<label>. The <label> is what will be displayed on your form/flow and the <value> is what is saved as the selected value when the user submits the form or completes the workflow.

    1. Enter the Value Binding - this is bind path of the option VALUES within the XML or JSON returned by the RESTful web service. Binding paths are specified with the '/' character used as a delimiter i.e. /resultSet/CountryID. The path locates the values to be extracted and set into the selection control options. If the data pointed to by the path is repeating, then the data extracted will be a collection of items. This is the value that will be stored in the XML submissions document when the form/flow is submitted/completed.
      The Value Binding can be determined by examining the resultSet in the frevvo debug console.

    2. Enter the Label Binding - this is the bind path of the option display LABELS within the XML or JSON returned by the RESTful web service. This label is displayed in the selection control options in Use mode. The Label Binding can be determined from the debug console by examining the resultSet in the debug console.

      1. Type the URL to your WebService in the Options Source property then click the save and test icon. Examine the resultSet in the debug console to determine the Value binding.

        Code Block
        titleExample 1: Results returned in JSON format
        If this is the JSON Data returned:  "totalResultsAvailable":2,
"resultSet":[{"CountryName":"Argentina","CountryID":"1"},{"CountryName":"Aruba","CountryID":"12"},{"CountryName":"Bahamas","CountryID":"13"}]}

If the Value Binding property is set to /resultSet/CountryID - the country id of the selected country will be stored in the Livefrevvo Forms submission

If the Label Binding is set to /resultSet/CountryName - the country names are what the user sees as the selection control options - Argentina, Aruba, Bahamas
        Code Block
        titleExample 2: Results returned in XML format
        If the results are returned in XML:   Notice that the XML uses namespaces and that they must be part of the bind path.

<?xml version="1.0" encoding="UTF-8"?>
<p0:allCountries xmlns:p0="http://www.frevvo.com/database/allCountries">
   <row>
      <CountryID>1</CountryID>
      <CountryName>Argentina</CountryName>
   </row>
   <row>
      <CountryID>12</CountryID>
      <CountryName>Aruba</CountryName>
   </row>
   <row>
      <CountryID>13</CountryID>
      <CountryName>Bahamas</CountryName>
   </row>
</p0:allCountries

If the Value Binding and Label Binding properties are be set to the same path: /p0:allCountries/row/CountryName - the Country Name will be included in the submission and Users will see the Country Names as the options of the selection control: Argentina, Aruba, Bahamas


  6. Click the save and test icon to test your form/flow.
  7. The Example below uses the Database Connector to retrieve a Customer List from a database. It also shows to construct the Value and Label Bindings from the XML results returned in the Debug Console.
Info

When using an _data parameter template in your options URL in a workflow, it may cause issues in steps that don't load the _data parameter and may even invalidate signed sections. One workaround is to store your _data parameter in a hidden control, and then use the template for that control in your Options Source URL instead.

Excerpt
hiddentrue

The Edmunds API web service returns a “vehicle makes” options list in JSON format and lets you narrow the options to a specific year. Design a form with a field for the user to enter a year and a checkbox, radio or dropdown control.

Image Modified

Follow these steps to populate the options of your selection control with the results returned from the Edmunds web service

  1. Edit the form in the Forms Designer 
  2. Click on the Selection control (checkbox, radio or dropdown) 
  3. Set the Options Src to Web Service 
  4. Set the Options URL to: https://api.edmunds.com/api/vehicle/v2/makes?state=new&year={year}&view=basic&fmt=json&api_key=p9v6s4uv6998k464u33m8jx3

  5. Set the Value Binding to:   /makes/niceName

  6. Set the Label Binding to:   /makes/name

    Image Modified

  7. Save the form 

 When the user types something in the Year field, the web service is automatically called, the results are refreshed and the choices in the Car Makes checkbox will change based on whatever the web service returned. To test this, type in the year 2015 then the year 2017.


Dynamic Options Example

Let's say you have a form/flow with a Dropdown control named Customer. You want to populate the options of this control with a list of Customers Names. You also would like to store the Customer Number associated with the Selected customer in the form/flow submission. We will use the Database Connector as our Web Service. For this example, the Database Connector is configured in Standalone mode to work with a MySQL database named classicmodels.

The Customer dropdown options can be populated with a business rule but you can also use the Dynamic Options feature. The frevvo Database Connector executes a query against a database named classicmodels that will return a list of Customers in JSON format. We will determine the Value and Label bindings by examining the results returned in the debug console.

Follow these steps:

  1. Click on the Customer control.
  2. Select Web Service from the Option Src dropdown
  3. The Options URL is: http://localhost:8081/database/BIRT/allCustomers?_mediaType=json  This URL points to an instance of the Database Connector running on the save server/port as . The results of this query will show the Customer Number and Customer Name for each customer in the Customers database table in JSON format.
  4. After entering the Options URL ,click the save and test icon. 
  5. To determine the Value Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by the value from the results that you want to be stored in the submission XML - in this case - customerNumber
    3. The Value BInding should be set to: /resultSet/customerNumber
  6. To determine the Label Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by value from the results that you want to see as the option labels - in this case - customerName
    3. The Label Binding should be set to: /resultSet/customerName



  7.  Click the save and test icon to test the form. Note the options display the Customer Name.



  8. Click Submit.
  9. Navigate to the Forms Home Page and click the Submissions icon. Open the submissions and view the Document tab. Note the Customer Number is the value stored there.

...

The ComboBox control supports three types of data retrieval: frevvo Users, frevvo Roles and Web Service. Select the data source using the dropdown in the Options Src property. Selecting Web Service makes it possible to use the ComboBox to retrieve values from a database and enable a list of possible partial matches. There is also a blank option. Pick this one if you are going to populate your ComboBox options using a business rule.

Note
  • frevvo Users and frevvo Roles require security/authentication. When selecting frevvo Users and frevvo Roles as the Option Src, your form or flow must be set to Authenticated Users (login required).
  • The Dynamic Options feature using the ComboBox will NOT work with SOAP web services.

...

  1. Drag the ComboBox control into your form/flow
  2. Set the Options Src to one of two choices: frevvo Users or frevvo Roles.
    1. Selecting frevvo Users - returns a list of ALL users in the current tenant.  constructs a URL:/frevvo/web/tn/{form.tenant.id}/users?match= then replaces the form.tenant.id template with the name of the current tenant. 

    2. Selecting frevvo Roles returns the list of ALL roles in the current tenant. constructs a URL:/frevvo/web/tn/{form.tenant.id}/roles?match= then replaces the form.tenant.id template with the name of the current tenant.

Image Modified

3. The ComboBox supports the ability to specify single or multiple values. Check the Single Value checkbox if you want to limit the choice to one value.

Image Modified

Users can typeahead to narrow the choices based on the letters entered. User ids and roles are case sensitive so remember to use the correct case when typing. 

Image Modified

4. Check the Options Value Only checkbox to restrict the ComboBox value to available options. Options Value Only is only available when Options Src is set to frevvo Users or frevvo Roles.

Info

You cannot test the ComboBox Options in the form/flow designers. Click the  save and test icon for the quickest way to verify that the ComboBox is working as expected.

Populate Dynamic Pick Lists from a Database with the ComboBox

The ComboBox control can be used to retrieve values from a web service and enable a list of possible partial matches. This is helpful when you have database queries that return a large number of options. You can filter the number of options returned from a query based on the text typed into the ComboBox. Users typeahead and are only presented with the matching options as choices.

  • Your web service must be able to filter results and accept parameters that drive filtering
  • A dynamic Options URL that contains the {<combobox control name>.matchText} parameter. As the user types text into the CombBox, the text will be substituted into the URL. The web service returns only the options matching the typed in text as choices.  
  • The ComboBox control shows up to 100 matching options. If the web service finds more that 100 possible matching options, only the first 100 are to be shown. Informing users that there are additional matches that are not shown is not supported.

Set the Options Source property of the ComboBox to Web Service then provide the Options URL and Bind Path properties:

  • Options URL - The URL of the RESTful web service that will retrieve matching options. Be sure that the URL contains the  {<combobox control name>.matchText} template parameter. 
  • Bind Path - The bind path of the matching options within the XML or JSON returned by the RESTful web service. The Bind Path property determines the selected value that is included in the submission and what the user sees.

Example

It is very common to pull options for a typeahead control such as the ComboBox from a database. If you are using the frevvo Database Connector to integrate with your SQL database you already have a Restful service that returns data as resultSets.

Let's say you have a classicmodels MySQL database with a Products table that contains 121 records. You have a form with a ComboBox control named NameofProduct and you want to populate the options from the query results. However, you do not expect your users to scroll through 121 choices until they find the one that they are looking for. Ideally, you would like to filter the results coming back from the query based on the characters inserted into ComboBox. Users can then typeahead and select a value from the filtered choices.

For this example, the frevvo Database Connector is installed on the same machine as and configured in Standalone mode running on port 8081.

  1. You will need a query to run against the database. This query, which is included in the BIRT queryset in the configuration.xml file, uses the MySQL Like and % wild cards, to return all the products that match the value in the template (pname}.

    Code Block
    <query name="productsByName">
<retrieve>
                <!--maps to HTTP GET -->
                <statement> SELECT * FROM Products where productName LIKE '%{pName}%' order by productName </statement>
</retrieve>
</query>

     

  2. Click on the ComboBox control to display the Properties panel. Select Web Service as the Options Src.

  3. Provide the URL to the datasource - in this case the URL to the database query in the BIRT queryset- productsByName. Add the {<combobox control name>.matchText} parameter to specify the value of the variable - pname - in the query as the matching text typed into the Name of Product control.

    Code Block
    http://<server>:<port>/database/BIRT/productsByName?pName={NameofProduct.matchText}
  4. Click the Image Modifiedsave and test icon. Enter a value into the ComboBox. Determine the Binding Path from the resultSet. In the image, the number 1 was entered into the ComboBox.

    Image Modified

  5. The ComboBox Properties panel should look like this. If you want to limit the user selection to one value, check the SIngle Value checkbox.

    Image Modified
     
  6.  Users will see all the returned options that match the number 1 when it is entered in the ComboBox. Adding 8t into the ComboBox will further filter the options and display the choices that match 18t . Each time a character is entered it is added to the URL and the Web Service is invoked. Only the matching results is displayed to the user.

...

You are not permitted to disable grouping controls such as panels or repeats. However, there is an Enabled property for Sections, each of the columns in a Table and each tab in a Tab control. If "enabled" is set on Tab or Section, controls inside of these group controls would be enabled. Conversely, if the property is unchecked, controls inside of a section or tab would be disabled. This property will make it easier to write Business Rules. 

You can enable/disable the selection controls via rules thereby enabling/disabling all the selection control options. It is not possible to enable/disable individual options.

Disabled tabs are still selectable and disabled sections can still be expanded and collapsed. This is as designed. If you are trying to show/hide the contents of a tab/section, use the 1063682390 property. 

...

The Save Value property applies to Message, Link, Image and Form Viewer controls. This property controls whether the control's value appears in the  form/flow submission document  . The  and the translation file used for multi language support. The property will be unchecked (default) for new Message, Link, Image or Form Viewer controls added to your form/flow. An example of the Properties pane for the Message control is shown in the image.

...

This property determines whether the value saved in the submissions repository is hidden when viewed in the  web submissions UI. Check the checkbox if the data users will enter into this field contains sensitive data that should not be visible when viewed in the web UI. Sensitive field values will be encrypted in the submissions database using an SHA algorithm. The control must be designated as a Saved Field in the form. This property does not enable hashing of the value stored in the XML document.

...

Another is the showhelp css class that is built into the Tight layout. For example, you can reduce white space even further with the Tight layout so that you have virtually no space between controls by selecting the hide label property on each control. This can be a way to implement a grid type layout as shown in this sample form below. 

When controls are this tight together there is no room to display the help icon for controls with help text. Notice that the first row of controls does displays the help icon. This is done by putting the string showhelp into the css class property for each control in the first row. This is a useful way to have help at the top of each column.

CSS Class to Set Font Size for the Table and Message Controls

...

The f-action- error css class displays text defined in a Message control if an Activity Document Action post returns an HTTP 422 status for a workflow step. Refer to Activity Document Action Behavior for Failed Post for the details.

Tip

If you are using Live Formsfrevvo in-house, Cascading Style Sheet code that was used in themes applied to forms/flows in previous Live Formsfrevvo releases, can be added to a newly created style.css file in the frevvo.war file . The context parameter, frevvo.css.url, in the web.xml file must be changed to point to it.

...

This property applies only to Submit controls. By default  disables the form's submit button until all required fields are filled and contain valid data. See Valid Forms for details of this feature. However, sometimes you may wish to override ' default behavior and allow the user to submit a form even if it is invalid. To do this, uncheck this property.

When "Enable if Valid" is checked and you click on the Submit button in a form that contains invalid data or required fields that are empty,  the form will not submit and the invalid fields will be highlighted with an orange background color. The designer can also display a message instructing the user what to do.

 This approach is very helpful to users when trying to determine why a form does not submit. Refer to this Invalid Form Notification for the details.

 

If "Enable if Valid" property is unchecked,  you can control the Submit button behavior in a business rule using the Submit.enabled = [true,false] property.

Prefix Property

Custom groups with rules included when dropped back onto the same or another form, will contain a special "Prefix" property. The property will automatically be given a unique value if you drop the group onto the same form 2 or more times. This ensures that the group controls have unique element name. You can view the impact the prefix has on the element names by viewing the form's schema or the control's property panel. Using the prefix property, you can write a separate rule to manipulate the 2nd or greater instance of the custom control. Refer to this documentation for the details.

...

A control’s label is displayed on your form beside or above the control. When you first drag in a control it is assigned an arbitrary and unique label—checkbox 43 for example. Obviously for your users’ sake you will want more meaningful labels. Change a control’s label either on the form itself (by clicking the control and selecting the label) or by overlaying the arbitrary name in the Properties Label field.  Message controls are the only controls without labels—they are used for static text so you don’t need a label, too.

...

Tip

The < sign is not allowed in a label for Input controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Control Type

This applies to selection controls (dropdowns, radios and checkboxes) and most input controls (text, text area, email, phone, quantity, number, table, and repeat) and is populated automatically when you first drag in a control.  You can change this property if you want to switch a control in your form to a different type of control. This saves you from having to remove the original control and drag in a new one. The Control Type property is also used to change a date control to a time or date/time control. See Date, Time, Date/Time for more information.

...

 adjusts the date to be within 80 years before or 20 years after if the date is expressed with a two digit year. For example, using a pattern of "MM/dd/yy" and the current date/time of Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only year strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits, is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC. Live forms frevvo will always format as 4 digit years.  

Note

The date will be converted to the standard xsd:date format of yyyy-mm-dd  in the submissions XML document. Here is an example: <Order Date>2012-03-06</Order Date>. Refer to Viewing XML Documents for more details.

Rules can be applied to the Date control in all variations.

...

By using this property, time entries entered into the form are reformatted to match the selected format. For example, if you choose a military time format of hh:mm:ss and enter 2:00 PM the time value will display in the form as 14:00:00. It will be saved in the submissions XML document as <Order Time>14:00:00</Order Time>. Refer to Viewing XML Documents for more details.  

If you choose a format other than automatic,  parses and formats the time and dateTime control values with a locale specific date formatter. Read this documentation for more information about date/time controls and internationalization.

...

Note

The local time will be converted to and saved in UTC format and the date will be converted to the standard xsd:date format of yyyy-mm-dd in the submission XML document. Here is an example: <OrderDate>2013-08-12T19:13:00Z</OrderDate>. Refer to Viewing XML Documents for more details. 

Max Length

...

You can change the color displayed by Required fields by modifying a Style and then applying it to your form/flow. If you prefer an asterisk to designate required fields, enable the Accessibility feature by checking the Accessible property on the form/flow Properties pane. This feature was built to allow visually impaired users to access forms. Enabling this property adds an asterisk (*) for all required fields. If users move ahead from that field without filling it, they will see the error, "You can't leave this empty <control name>".

...

The < sign is not allowed in an option label for Selection controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Tip

Design mode allows options with same value and different label. If you set the options of a Selection control as shown below then click the save and test icon, you will only be able to select one option of the Selection Control in Test mode.

  • a=b

  • a=c

This can be a issue when working with dynamic selection controls. Designers must be careful that the web services they are using do not return data with duplicates values.

...

  1. Click on the selection control (Checkbox, Dropdown, Radio)
  2. Select Web Service from the Option Src dropdown


     
  3. Enter the URL of the RESTful web service that you are going to to retrieve the option data from. Data is retrieved using HTTP GET. The URL can contain templates and the options will be automatically updated whenever the value changes of any control referenced by a template in the URL.

    Ex: /http(s)://10.0.0.27/:8081/database/BIRT/allCustomers?_mediaType=json - This URL returns a list of all customers from a database The _mediaType parameter specifies that JSON results are returned. In this example, the Database Connector integrates with the database to execute the query. The Database Connector is a Restful service that returns results in XML or JSON.
     
  4. After entering the Options URL for your web service, click the save and test icon. Examine the results in the debug console to determine the Value and Label Bindings.
  5. The syntax for selection control options is <value>=<label>. The <label> is what will be displayed on your form/flow and the <value> is what is saved as the selected value when the user submits the form or completes the workflow.

    1. Enter the Value Binding - this is bind path of the option VALUES within the XML or JSON returned by the RESTful web service. Binding paths are specified with the '/' character used as a delimiter i.e. /resultsSet/CountryID. The path locates the values to be extracted and set into the selection control options. If the data pointed to by the path is repeating, then the data extracted will be a collection of items. This is the value that will be stored in the XML submissions document when the form/flow is submitted/completed.
      The Value Binding can be determined by examining the resultSet in the frevvo debug console.

    2. Enter the Label Binding - this is the bind path of the option display LABELS within the XML or JSON returned by the RESTful web service. This label is displayed in the selection control options in Use mode. The Label Binding can be determined from the debug console by examining the resultSet in the debug console.

      1. Type the URL to your WebService in the Options Source property then click the save and test icon. Examine the resultSet in the debug console to determine the Value binding.

        Code Block
        titleExample 1: Results returned in JSON format
        If this is the JSON Data returned:  "totalResultsAvailable":2,
"resultSet":[{"CountryName":"Argentina","CountryID":"1"},{"CountryName":"Aruba","CountryID":"12"},{"CountryName":"Bahamas","CountryID":"13"}]}

If the Value Binding property is set to /resultSet/CountryID - the country id of the selected country will be stored in the Live Formsfrevvo submission

If the Label Binding is set to /resultSet/CountryName - the country names are what the user sees as the selection control options - Argentina, Aruba, Bahamas
        Code Block
        titleExample 2: Results returned in XML format
        If the results are returned in XML:   Notice that the XML uses namespaces and that they must be part of the bind path.

<?xml version="1.0" encoding="UTF-8"?>
<p0:allCountries xmlns:p0="http://www.frevvo.com/database/allCountries">
   <row>
      <CountryID>1</CountryID>
      <CountryName>Argentina</CountryName>
   </row>
   <row>
      <CountryID>12</CountryID>
      <CountryName>Aruba</CountryName>
   </row>
   <row>
      <CountryID>13</CountryID>
      <CountryName>Bahamas</CountryName>
   </row>
</p0:allCountries

If the Value Binding and Label Binding properties are be set to the same path: /p0:allCountries/row/CountryName - the Country Name will be included in the submission and Users will see the Country Names as the options of the selection control: Argentina, Aruba, Bahamas


  6. Click the save and test icon to test your form/flow.
  7. The Example below uses the Database Connector to retrieve a Customer List from a database. It also shows to construct the Value and Label Bindings from the XML results returned in the Debug Console.


Excerpt
hiddentrue

The Edmunds API web service returns a “vehicle makes” options list in JSON format and lets you narrow the options to a specific year. Design a form with a field for the user to enter a year and a checkbox, radio or dropdown control.

Image Modified

Follow these steps to populate the options of your selection control with the results returned from the Edmunds web service

  1. Edit the form in the Forms Designer 
  2. Click on the Selection control (checkbox, radio or dropdown) 
  3. Set the Options Src to Web Service 
  4. Set the Options URL to: https://api.edmunds.com/api/vehicle/v2/makes?state=new&year={year}&view=basic&fmt=json&api_key=p9v6s4uv6998k464u33m8jx3

  5. Set the Value Binding to:   /makes/niceName

  6. Set the Label Binding to:   /makes/name

    Image Modified

  7. Save the form 

 When the user types something in the Year field, the web service is automatically called, the results are refreshed and the choices in the Car Makes checkbox will change based on whatever the web service returned. To test this, type in the year 2015 then the year 2017.


Dynamic Options Example

Let's say you have a form/flow with a Dropdown control named Customer. You want to populate the options of this control with a list of Customers Names. You also would like to store the Customer Number associated with the Selected customer in the form/flow submission. We will use the Database Connector as our Web Service. For this example, the Database Connector is configured in Standalone mode to work with a MySQL database named classicmodels.

The Customer dropdown options can be populated with a business rule but you can also use the Dynamic Options feature. The frevvo Database Connector executes a query against a database named classicmodels that will return a list of Customers in JSON format. We will determine the Value and Label bindings by examining the results returned in the debug console.

Follow these steps:

  1. Click on the Customer control.
  2. Select Web Service from the Option Src dropdown
  3. The Options URL is: http://localhost:8081/database/BIRT/allCustomers?_mediaType=json  This URL points to an instance of the Database Connector running on the save server/port as . The results of this query will show the Customer Number and Customer Name for each customer in the Customers database table in JSON format.
  4. After entering the Options URL ,click the save and test icon. 
  5. To determine the Value Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by the value from the results that you want to be stored in the submission XML - in this case - customerNumber
    3. The Value BInding should be set to: /resultSet/customerNumber
  6. To determine the Label Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by value from the results that you want to see as the option labels - in this case - customerName
    3. The Label Binding should be set to: /resultSet/customerName



  7.  Click the save and test icon to test the form. Note the options display the Customer Name.



  8. Click Submit.
  9. Navigate to the Forms Home Page and click the Submissions icon. Open the submissions and view the Document tab. Note the Customer Number is the value stored there.

...

The ComboBox control supports three types of data retrieval: frevvo Users, frevvo Roles and Web Service. Select the data source using the dropdown in the Options Src property. Selecting Web Service makes it possible to use the ComboBox to retrieve values from a database and enable a list of possible partial matches. There is also a blank option. Pick this one if you are going to populate your ComboBox options using a business rule.

Note
  • frevvo Users and frevvo Roles require security/authentication. When selecting frevvo Users and frevvo Roles as the Option Src, your form or flow must be set to Authenticated Users (login required).
  • The Dynamic Options feature using the ComboBox will NOT work with SOAP web services.

...

  1. Drag the ComboBox control into your form/flow
  2. Set the Options Src to one of two choices: frevvo Users or frevvo Roles.
    1. Selecting frevvo Users - returns a list of ALL users in the current tenant.  constructs a URL:/frevvo/web/tn/{form.tenant.id}/users?match= then replaces the form.tenant.id template with the name of the current tenant. 

    2. Selecting frevvo Roles returns the list of ALL roles in the current tenant. constructs a URL:/frevvo/web/tn/{form.tenant.id}/roles?match= then replaces the form.tenant.id template with the name of the current tenant.

Image Modified

3. The ComboBox supports the ability to specify single or multiple values. Check the Single Value checkbox if you want to limit the choice to one value.

Image Modified

Users can typeahead to narrow the choices based on the letters entered. User ids and roles are case sensitive so remember to use the correct case when typing. 

Image Modified

4. Check the Options Value Only checkbox to restrict the ComboBox value to available options. Options Value Only is only available when Options Src is set to frevvo Users or frevvo Roles.

Info

You cannot test the ComboBox Options in the form/flow designers. Click the  save and test icon for the quickest way to verify that the ComboBox is working as expected.

Populate Dynamic Pick Lists from a Database with the ComboBox

The ComboBox control can be used to retrieve values from a web service and enable a list of possible partial matches. This is helpful when you have database queries that return a large number of options. You can filter the number of options returned from a query based on the text typed into the ComboBox. Users typeahead and are only presented with the matching options as choices.

  • Your web service must be able to filter results and accept parameters that drive filtering
  • A dynamic Options URL that contains the {<combobox control name>.matchText} parameter. As the user types text into the CombBox, the text will be substituted into the URL. The web service returns only the options matching the typed in text as choices.  
  • The ComboBox control shows up to 100 matching options. If the web service finds more that 100 possible matching options, only the first 100 are to be shown. Informing users that there are additional matches that are not shown is not supported.

Set the Options Source property of the ComboBox to Web Service then provide the Options URL and Bind Path properties:

  • Options URL - The URL of the RESTful web service that will retrieve matching options. Be sure that the URL contains the  {<combobox control name>.matchText} template parameter. 
  • Bind Path - The bind path of the matching options within the XML or JSON returned by the RESTful web service. The Bind Path property determines the selected value that is included in the submission and what the user sees.

Example

It is very common to pull options for a typeahead control such as the ComboBox from a database. If you are using the frevvo Database Connector to integrate with your SQL database you already have a Restful service that returns data as resultSets.

Let's say you have a classicmodels MySQL database with a Products table that contains 121 records. You have a form with a ComboBox control named NameofProduct and you want to populate the options from the query results. However, you do not expect your users to scroll through 121 choices until they find the one that they are looking for. Ideally, you would like to filter the results coming back from the query based on the characters inserted into ComboBox. Users can then typeahead and select a value from the filtered choices.

For this example, the frevvo Database Connector is installed on the same machine as and configured in Standalone mode running on port 8081.

  1. You will need a query to run against the database. This query, which is included in the BIRT queryset in the configuration.xml file, uses the MySQL Like and % wild cards, to return all the products that match the value in the template (pname}.

    Code Block
    <query name="productsByName">
<retrieve>
                <!--maps to HTTP GET -->
                <statement> SELECT * FROM Products where productName LIKE '%{pName}%' order by productName </statement>
</retrieve>
</query>

     

  2. Click on the ComboBox control to display the Properties panel. Select Web Service as the Options Src.

  3. Provide the URL to the datasource - in this case the URL to the database query in the BIRT queryset- productsByName. Add the {<combobox control name>.matchText} parameter to specify the value of the variable - pname - in the query as the matching text typed into the Name of Product control.

    Code Block
    http://<server>:<port>/database/BIRT/productsByName?pName={NameofProduct.matchText}
  4. Click the Image Modifiedsave and test icon. Enter a value into the ComboBox. Determine the Binding Path from the resultSet. In the image, the number 1 was entered into the ComboBox.

    Image Modified

  5. The ComboBox Properties panel should look like this. If you want to limit the user selection to one value, check the SIngle Value checkbox.

    Image Modified
     
  6.  Users will see all the returned options that match the number 1 when it is entered in the ComboBox. Adding 8t into the ComboBox will further filter the options and display the choices that match 18t . Each time a character is entered it is added to the URL and the Web Service is invoked. Only the matching results is displayed to the user.

...

You are not permitted to disable grouping controls such as panels or repeats. However, there is an Enabled property for Sections, each of the columns in a Table and each tab in a Tab control. If "enabled" is set on Tab or Section, controls inside of these group controls would be enabled. Conversely, if the property is unchecked, controls inside of a section or tab would be disabled. This property will make it easier to write Business Rules. 

You can enable/disable the selection controls via rules thereby enabling/disabling all the selection control options. It is not possible to enable/disable individual options.

Disabled tabs are still selectable and disabled sections can still be expanded and collapsed. This is as designed. If you are trying to show/hide the contents of a tab/section, use the 1063682390 property. 

...

The Save Value property applies to Message, Link, Image and Form Viewer controls. This property controls whether the control's value appears in the  form/flow submission document  . The property will be unchecked (default) for new Message, Link, Image or Form Viewer controls added to your form/flow. An example of the Properties pane for the Message control is shown in the image.

...

This property determines whether the value saved in the submissions repository is hidden when viewed in the  web submissions UI. Check the checkbox if the data users will enter into this field contains sensitive data that should not be visible when viewed in the web UI. Sensitive field values will be encrypted in the submissions database using an SHA algorithm. The control must be designated as a Saved Field in the form. This property does not enable hashing of the value stored in the XML document.

...

Another is the showhelp css class that is built into the Tight layout. For example, you can reduce white space even further with the Tight layout so that you have virtually no space between controls by selecting the hide label property on each control. This can be a way to implement a grid type layout as shown in this sample form below. 

When controls are this tight together there is no room to display the help icon for controls with help text. Notice that the first row of controls does displays the help icon. This is done by putting the string showhelp into the css class property for each control in the first row. This is a useful way to have help at the top of each column.

CSS Class to Set Font Size for the Table and Message Controls

...

The f-action- error css class displays text defined in a Message control if an Activity Document Action post returns an HTTP 422 status for a workflow step. Refer to Activity Document Action Behavior for Failed Post for the details.

Tip

If you are using Live Formsfrevvo in-house, Cascading Style Sheet code that was used in themes applied to forms/flows in previous Live Formsfrevvo releases, can be added to a newly created style.css file in the frevvo.war file . The context parameter, frevvo.css.url, in the web.xml file must be changed to point to it.

...

This property applies only to Submit controls. By default  disables the form's submit button until all required fields are filled and contain valid data. See Valid Forms for details of this feature. However, sometimes you may wish to override ' default behavior and allow the user to submit a form even if it is invalid. To do this, uncheck this property.

When "Enable if Valid" is checked and you click on the Submit button in a form that contains invalid data or required fields that are empty,  the form will not submit and the invalid fields will be highlighted with an orange background color. The designer can also display a message instructing the user what to do.

 This approach is very helpful to users when trying to determine why a form does not submit. Refer to this Invalid Form Notification for the details.

 

If "Enable if Valid" property is unchecked,  you can control the Submit button behavior in a business rule using the Submit.enabled = [true,false] property.

Prefix Property

Custom groups with rules included when dropped back onto the same or another form, will contain a special "Prefix" property. The property will automatically be given a unique value if you drop the group onto the same form 2 or more times. This ensures that the group controls have unique element name. You can view the impact the prefix has on the element names by viewing the form's schema or the control's property panel. Using the prefix property, you can write a separate rule to manipulate the 2nd or greater instance of the custom control. Refer to this documentation for the details.

...

Tip

The < sign is not allowed in a label for Input controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Control Type

This applies to selection controls (dropdowns, radios and checkboxes) and most input controls (text, text area, email, phone, quantity, number, table, and repeat) and is populated automatically when you first drag in a control.  You can change this property if you want to switch a control in your form to a different type of control. This saves you from having to remove the original control and drag in a new one. The Control Type property is also used to change a date control to a time or date/time control. See Date, Time, Date/Time for more information.

...

 adjusts the date to be within 80 years before or 20 years after if the date is expressed with a two digit year. For example, using a pattern of "MM/dd/yy" and the current date/time of Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only year strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits, is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC. Live forms frevvo will always format as 4 digit years.  

Note

The date will be converted to the standard xsd:date format of yyyy-mm-dd  in the submissions XML document. Here is an example: <Order Date>2012-03-06</Order Date>. Refer to Viewing XML Documents for more details.

Rules can be applied to the Date control in all variations.

...

By using this property, time entries entered into the form are reformatted to match the selected format. For example, if you choose a military time format of hh:mm:ss and enter 2:00 PM the time value will display in the form as 14:00:00. It will be saved in the submissions XML document as <Order Time>14:00:00</Order Time>. Refer to Viewing XML Documents for more details.  

If you choose a format other than automatic,  parses and formats the time and dateTime control values with a locale specific date formatter. Read this documentation for more information about date/time controls and internationalization.

...

Note

The local time will be converted to and saved in UTC format and the date will be converted to the standard xsd:date format of yyyy-mm-dd in the submission XML document. Here is an example: <OrderDate>2013-08-12T19:13:00Z</OrderDate>. Refer to Viewing XML Documents for more details. 

Max Length

...

You can change the color displayed by Required fields by modifying a Style and then applying it to your form/flow. If you prefer an asterisk to designate required fields, enable the Accessibility feature by checking the Accessible property on the form/flow Properties pane. This feature was built to allow visually impaired users to access forms. Enabling this property adds an asterisk (*) for all required fields. If users move ahead from that field without filling it, they will see the error, "You can't leave this empty <control name>".

...

The < sign is not allowed in an option label for Selection controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Tip

Design mode allows options with same value and different label. If you set the options of a Selection control as shown below then click the save and test icon, you will only be able to select one option of the Selection Control in Test mode.

  • a=b

  • a=c

This can be a issue when working with dynamic selection controls. Designers must be careful that the web services they are using do not return data with duplicates values.

...

  1. Click on the selection control (Checkbox, Dropdown, Radio)
  2. Select Web Service from the Option Src dropdown


     
  3. Enter the URL of the RESTful web service that you are going to to retrieve the option data from. Data is retrieved using HTTP GET. The URL can contain templates and the options will be automatically updated whenever the value changes of any control referenced by a template in the URL.

    Ex: /http(s)://10.0.0.27/:8081/database/BIRT/allCustomers?_mediaType=json - This URL returns a list of all customers from a database The _mediaType parameter specifies that JSON results are returned. In this example, the Database Connector integrates with the database to execute the query. The Database Connector is a Restful service that returns results in XML or JSON.
     
  4. After entering the Options URL for your web service, click the save and test icon. Examine the results in the debug console to determine the Value and Label Bindings.
  5. The syntax for selection control options is <value>=<label>. The <label> is what will be displayed on your form/flow and the <value> is what is saved as the selected value when the user submits the form or completes the workflow.

    1. Enter the Value Binding - this is bind path of the option VALUES within the XML or JSON returned by the RESTful web service. Binding paths are specified with the '/' character used as a delimiter i.e. /resultSet/CountryID. The path locates the values to be extracted and set into the selection control options. If the data pointed to by the path is repeating, then the data extracted will be a collection of items. This is the value that will be stored in the XML submissions document when the form/flow is submitted/completed.
      The Value Binding can be determined by examining the resultSet in the frevvo debug console.

    2. Enter the Label Binding - this is the bind path of the option display LABELS within the XML or JSON returned by the RESTful web service. This label is displayed in the selection control options in Use mode. The Label Binding can be determined from the debug console by examining the resultSet in the debug console.

      1. Type the URL to your WebService in the Options Source property then click the save and test icon. Examine the resultSet in the debug console to determine the Value binding.

        Code Block
        titleExample 1: Results returned in JSON format
        If this is the JSON Data returned:  "totalResultsAvailable":2,
"resultSet":[{"CountryName":"Argentina","CountryID":"1"},{"CountryName":"Aruba","CountryID":"12"},{"CountryName":"Bahamas","CountryID":"13"}]}

If the Value Binding property is set to /resultSet/CountryID - the country id of the selected country will be stored in the Live Formsfrevvo submission

If the Label Binding is set to /resultSet/CountryName - the country names are what the user sees as the selection control options - Argentina, Aruba, Bahamas
        Code Block
        titleExample 2: Results returned in XML format
        If the results are returned in XML:   Notice that the XML uses namespaces and that they must be part of the bind path.

<?xml version="1.0" encoding="UTF-8"?>
<p0:allCountries xmlns:p0="http://www.frevvo.com/database/allCountries">
   <row>
      <CountryID>1</CountryID>
      <CountryName>Argentina</CountryName>
   </row>
   <row>
      <CountryID>12</CountryID>
      <CountryName>Aruba</CountryName>
   </row>
   <row>
      <CountryID>13</CountryID>
      <CountryName>Bahamas</CountryName>
   </row>
</p0:allCountries

If the Value Binding and Label Binding properties are be set to the same path: /p0:allCountries/row/CountryName - the Country Name will be included in the submission and Users will see the Country Names as the options of the selection control: Argentina, Aruba, Bahamas


  6. Click the save and test icon to test your form/flow.
  7. The Example below uses the Database Connector to retrieve a Customer List from a database. It also shows to construct the Value and Label Bindings from the XML results returned in the Debug Console.


Excerpt
hiddentrue

The Edmunds API web service returns a “vehicle makes” options list in JSON format and lets you narrow the options to a specific year. Design a form with a field for the user to enter a year and a checkbox, radio or dropdown control.

Image Modified

Follow these steps to populate the options of your selection control with the results returned from the Edmunds web service

  1. Edit the form in the Forms Designer 
  2. Click on the Selection control (checkbox, radio or dropdown) 
  3. Set the Options Src to Web Service 
  4. Set the Options URL to: https://api.edmunds.com/api/vehicle/v2/makes?state=new&year={year}&view=basic&fmt=json&api_key=p9v6s4uv6998k464u33m8jx3

  5. Set the Value Binding to:   /makes/niceName

  6. Set the Label Binding to:   /makes/name

    Image Modified

  7. Save the form 

 When the user types something in the Year field, the web service is automatically called, the results are refreshed and the choices in the Car Makes checkbox will change based on whatever the web service returned. To test this, type in the year 2015 then the year 2017.


Dynamic Options Example

Let's say you have a form/flow with a Dropdown control named Customer. You want to populate the options of this control with a list of Customers Names. You also would like to store the Customer Number associated with the Selected customer in the form/flow submission. We will use the Database Connector as our Web Service. For this example, the Database Connector is configured in Standalone mode to work with a MySQL database named classicmodels.

The Customer dropdown options can be populated with a business rule but you can also use the Dynamic Options feature. The frevvo Database Connector executes a query against a database named classicmodels that will return a list of Customers in JSON format. We will determine the Value and Label bindings by examining the results returned in the debug console.

Follow these steps:

  1. Click on the Customer control.
  2. Select Web Service from the Option Src dropdown
  3. The Options URL is: http://localhost:8081/database/BIRT/allCustomers?_mediaType=json  This URL points to an instance of the Database Connector running on the save server/port as . The results of this query will show the Customer Number and Customer Name for each customer in the Customers database table in JSON format.
  4. After entering the Options URL ,click the save and test icon. 
  5. To determine the Value Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by the value from the results that you want to be stored in the submission XML - in this case - customerNumber
    3. The Value BInding should be set to: /resultSet/customerNumber
  6. To determine the Label Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by value from the results that you want to see as the option labels - in this case - customerName
    3. The Label Binding should be set to: /resultSet/customerName



  7.  Click the save and test icon to test the form. Note the options display the Customer Name.



  8. Click Submit.
  9. Navigate to the Forms Home Page and click the Submissions icon. Open the submissions and view the Document tab. Note the Customer Number is the value stored there.

...

The ComboBox control supports three types of data retrieval: frevvo Users, frevvo Roles and Web Service. Select the data source using the dropdown in the Options Src property. Selecting Web Service makes it possible to use the ComboBox to retrieve values from a database and enable a list of possible partial matches. There is also a blank option. Pick this one if you are going to populate your ComboBox options using a business rule.

Note
  • frevvo Users and frevvo Roles require security/authentication. When selecting frevvo Users and frevvo Roles as the Option Src, your form or flow must be set to Authenticated Users (login required).
  • The Dynamic Options feature using the ComboBox will NOT work with SOAP web services.

...

  1. Drag the ComboBox control into your form/flow
  2. Set the Options Src to one of two choices: frevvo Users or frevvo Roles.
    1. Selecting frevvo Users - returns a list of ALL users in the current tenant.  constructs a URL:/frevvo/web/tn/{form.tenant.id}/users?match= then replaces the form.tenant.id template with the name of the current tenant. 

    2. Selecting frevvo Roles returns the list of ALL roles in the current tenant. constructs a URL:/frevvo/web/tn/{form.tenant.id}/roles?match= then replaces the form.tenant.id template with the name of the current tenant.

Image Modified

3. The ComboBox supports the ability to specify single or multiple values. Check the Single Value checkbox if you want to limit the choice to one value.

Image Modified

Users can typeahead to narrow the choices based on the letters entered. User ids and roles are case sensitive so remember to use the correct case when typing. 

Image Modified

4. Check the Options Value Only checkbox to restrict the ComboBox value to available options. Options Value Only is only available when Options Src is set to frevvo Users or frevvo Roles.

Info

You cannot test the ComboBox Options in the form/flow designers. Click the  save and test icon for the quickest way to verify that the ComboBox is working as expected.

Populate Dynamic Pick Lists from a Database with the ComboBox

The ComboBox control can be used to retrieve values from a web service and enable a list of possible partial matches. This is helpful when you have database queries that return a large number of options. You can filter the number of options returned from a query based on the text typed into the ComboBox. Users typeahead and are only presented with the matching options as choices.

  • Your web service must be able to filter results and accept parameters that drive filtering
  • A dynamic Options URL that contains the {<combobox control name>.matchText} parameter. As the user types text into the CombBox, the text will be substituted into the URL. The web service returns only the options matching the typed in text as choices.  
  • The ComboBox control shows up to 100 matching options. If the web service finds more that 100 possible matching options, only the first 100 are to be shown. Informing users that there are additional matches that are not shown is not supported.

Set the Options Source property of the ComboBox to Web Service then provide the Options URL and Bind Path properties:

  • Options URL - The URL of the RESTful web service that will retrieve matching options. Be sure that the URL contains the  {<combobox control name>.matchText} template parameter. 
  • Bind Path - The bind path of the matching options within the XML or JSON returned by the RESTful web service. The Bind Path property determines the selected value that is included in the submission and what the user sees.

Example

It is very common to pull options for a typeahead control such as the ComboBox from a database. If you are using the frevvo Database Connector to integrate with your SQL database you already have a Restful service that returns data as resultSets.

Let's say you have a classicmodels MySQL database with a Products table that contains 121 records. You have a form with a ComboBox control named NameofProduct and you want to populate the options from the query results. However, you do not expect your users to scroll through 121 choices until they find the one that they are looking for. Ideally, you would like to filter the results coming back from the query based on the characters inserted into ComboBox. Users can then typeahead and select a value from the filtered choices.

For this example, the frevvo Database Connector is installed on the same machine as and configured in Standalone mode running on port 8081.

  1. You will need a query to run against the database. This query, which is included in the BIRT queryset in the configuration.xml file, uses the MySQL Like and % wild cards, to return all the products that match the value in the template (pname}.

    Code Block
    <query name="productsByName">
<retrieve>
                <!--maps to HTTP GET -->
                <statement> SELECT * FROM Products where productName LIKE '%{pName}%' order by productName </statement>
</retrieve>
</query>

     

  2. Click on the ComboBox control to display the Properties panel. Select Web Service as the Options Src.

  3. Provide the URL to the datasource - in this case the URL to the database query in the BIRT queryset- productsByName. Add the {<combobox control name>.matchText} parameter to specify the value of the variable - pname - in the query as the matching text typed into the Name of Product control.

    Code Block
    http://<server>:<port>/database/BIRT/productsByName?pName={NameofProduct.matchText}
  4. Click the Image Modifiedsave and test icon. Enter a value into the ComboBox. Determine the Binding Path from the resultSet. In the image, the number 1 was entered into the ComboBox.

    Image Modified

  5. The ComboBox Properties panel should look like this. If you want to limit the user selection to one value, check the SIngle Value checkbox.

    Image Modified
     
  6.  Users will see all the returned options that match the number 1 when it is entered in the ComboBox. Adding 8t into the ComboBox will further filter the options and display the choices that match 18t . Each time a character is entered it is added to the URL and the Web Service is invoked. Only the matching results is displayed to the user.

...

You are not permitted to disable grouping controls such as panels or repeats. However, there is an Enabled property for Sections, each of the columns in a Table and each tab in a Tab control. If "enabled" is set on Tab or Section, controls inside of these group controls would be enabled. Conversely, if the property is unchecked, controls inside of a section or tab would be disabled. This property will make it easier to write Business Rules. 

You can enable/disable the selection controls via rules thereby enabling/disabling all the selection control options. It is not possible to enable/disable individual options.

Disabled tabs are still selectable and disabled sections can still be expanded and collapsed. This is as designed. If you are trying to show/hide the contents of a tab/section, use the 1063682390 property. 

...

The Save Value property applies to Message, Link, Image and Form Viewer controls. This property controls whether the control's value appears in the  form/flow submission document  . The property will be unchecked (default) for new Message, Link, Image or Form Viewer controls added to your form/flow. An example of the Properties pane for the Message control is shown in the image.

...

This property determines whether the value saved in the submissions repository is hidden when viewed in the  web submissions UI. Check the checkbox if the data users will enter into this field contains sensitive data that should not be visible when viewed in the web UI. Sensitive field values will be encrypted in the submissions database using an SHA algorithm. The control must be designated as a Saved Field in the form. This property does not enable hashing of the value stored in the XML document.

...

Another is the showhelp css class that is built into the Tight layout. For example, you can reduce white space even further with the Tight layout so that you have virtually no space between controls by selecting the hide label property on each control. This can be a way to implement a grid type layout as shown in this sample form below. 

When controls are this tight together there is no room to display the help icon for controls with help text. Notice that the first row of controls does displays the help icon. This is done by putting the string showhelp into the css class property for each control in the first row. This is a useful way to have help at the top of each column.

CSS Class to Set Font Size for the Table and Message Controls

...

The f-action- error css class displays text defined in a Message control if an Activity Document Action post returns an HTTP 422 status for a workflow step. Refer to Activity Document Action Behavior for Failed Post for the details.

Tip

If you are using Live Formsfrevvo in-house, Cascading Style Sheet code that was used in themes applied to forms/flows in previous Live Formsfrevvo releases, can be added to a newly created style.css file in the frevvo.war file . The context parameter, frevvo.css.url, in the web.xml file must be changed to point to it.

...

This property applies only to Submit controls. By default  disables the form's submit button until all required fields are filled and contain valid data. See Valid Forms for details of this feature. However, sometimes you may wish to override ' default behavior and allow the user to submit a form even if it is invalid. To do this, uncheck this property.

When "Enable if Valid" is checked and you click on the Submit button in a form that contains invalid data or required fields that are empty,  the form will not submit and the invalid fields will be highlighted with an orange background color. The designer can also display a message instructing the user what to do.

 This approach is very helpful to users when trying to determine why a form does not submit. Refer to this Invalid Form Notification for the details.

 

If "Enable if Valid" property is unchecked,  you can control the Submit button behavior in a business rule using the Submit.enabled = [true,false] property.

Prefix Property

Custom groups with rules included when dropped back onto the same or another form, will contain a special "Prefix" property. The property will automatically be given a unique value if you drop the group onto the same form 2 or more times. This ensures that the group controls have unique element name. You can view the impact the prefix has on the element names by viewing the form's schema or the control's property panel. Using the prefix property, you can write a separate rule to manipulate the 2nd or greater instance of the custom control. Refer to this documentation for the details.

...

Tip

The < sign is not allowed in a label for Input controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Control Type

This applies to selection controls (dropdowns, radios and checkboxes) and most input controls (text, text area, email, phone, quantity, number, table, and repeat) and is populated automatically when you first drag in a control.  You can change this property if you want to switch a control in your form to a different type of control. This saves you from having to remove the original control and drag in a new one. The Control Type property is also used to change a date control to a time or date/time control. See Date, Time, Date/Time for more information.

...

 adjusts the date to be within 80 years before or 20 years after if the date is expressed with a two digit year. For example, using a pattern of "MM/dd/yy" and the current date/time of Jan 1, 1997, the string "01/11/12" would be interpreted as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4, 1964. During parsing, only year strings consisting of exactly two digits, will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits, is interpreted literally. So "01/02/3" or "01/02/003" are parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is parsed as Jan 2, 4 BC. Live forms frevvo will always format as 4 digit years.  

Note

The date will be converted to the standard xsd:date format of yyyy-mm-dd  in the submissions XML document. Here is an example: <Order Date>2012-03-06</Order Date>. Refer to Viewing XML Documents for more details.

Rules can be applied to the Date control in all variations.

...

By using this property, time entries entered into the form are reformatted to match the selected format. For example, if you choose a military time format of hh:mm:ss and enter 2:00 PM the time value will display in the form as 14:00:00. It will be saved in the submissions XML document as <Order Time>14:00:00</Order Time>. Refer to Viewing XML Documents for more details.  

If you choose a format other than automatic,  parses and formats the time and dateTime control values with a locale specific date formatter. Read this documentation for more information about date/time controls and internationalization.

...

Note

The local time will be converted to and saved in UTC format and the date will be converted to the standard xsd:date format of yyyy-mm-dd in the submission XML document. Here is an example: <OrderDate>2013-08-12T19:13:00Z</OrderDate>. Refer to Viewing XML Documents for more details. 

Max Length

...

You can change the color displayed by Required fields by modifying a Style and then applying it to your form/flow. If you prefer an asterisk to designate required fields, enable the Accessibility feature by checking the Accessible property on the form/flow Properties pane. This feature was built to allow visually impaired users to access forms. Enabling this property adds an asterisk (*) for all required fields. If users move ahead from that field without filling it, they will see the error, "You can't leave this empty <control name>".

...

The < sign is not allowed in an option label for Selection controls. Searchable Fields with values that contain the < sign will not display completely in the Submissions Table.

Tip

Design mode allows options with same value and different label. If you set the options of a Selection control as shown below then click the save and test icon, you will only be able to select one option of the Selection Control in Test mode.

  • a=b

  • a=c

This can be a issue when working with dynamic selection controls. Designers must be careful that the web services they are using do not return data with duplicates values.

...

  1. Click on the selection control (Checkbox, Dropdown, Radio)
  2. Select Web Service from the Option Src dropdown


     
  3. Enter the URL of the RESTful web service that you are going to to retrieve the option data from. Data is retrieved using HTTP GET. The URL can contain templates and the options will be automatically updated whenever the value changes of any control referenced by a template in the URL.

    Ex: /http(s)://10.0.0.27/:8081/database/BIRT/allCustomers?_mediaType=json - This URL returns a list of all customers from a database The _mediaType parameter specifies that JSON results are returned. In this example, the Database Connector integrates with the database to execute the query. The Database Connector is a Restful service that returns results in XML or JSON.
     
  4. After entering the Options URL for your web service, click the save and test icon. Examine the results in the debug console to determine the Value and Label Bindings.
  5. The syntax for selection control options is <value>=<label>. The <label> is what will be displayed on your form/flow and the <value> is what is saved as the selected value when the user submits the form or completes the workflow.

    1. Enter the Value Binding - this is bind path of the option VALUES within the XML or JSON returned by the RESTful web service. Binding paths are specified with the '/' character used as a delimiter i.e. /resultsSet/CountryID. The path locates the values to be extracted and set into the selection control options. If the data pointed to by the path is repeating, then the data extracted will be a collection of items. This is the value that will be stored in the XML submissions document when the form/flow is submitted/completed.
      The Value Binding can be determined by examining the resultSet in the frevvo debug console.

    2. Enter the Label Binding - this is the bind path of the option display LABELS within the XML or JSON returned by the RESTful web service. This label is displayed in the selection control options in Use mode. The Label Binding can be determined from the debug console by examining the resultSet in the debug console.

      1. Type the URL to your WebService in the Options Source property then click the save and test icon. Examine the resultSet in the debug console to determine the Value binding.

        Code Block
        titleExample 1: Results returned in JSON format
        If this is the JSON Data returned:  "totalResultsAvailable":2,
"resultSet":[{"CountryName":"Argentina","CountryID":"1"},{"CountryName":"Aruba","CountryID":"12"},{"CountryName":"Bahamas","CountryID":"13"}]}

If the Value Binding property is set to /resultSet/CountryID - the country id of the selected country will be stored in the Live Formsfrevvo submission

If the Label Binding is set to /resultSet/CountryName - the country names are what the user sees as the selection control options - Argentina, Aruba, Bahamas
        Code Block
        titleExample 2: Results returned in XML format
        If the results are returned in XML:   Notice that the XML uses namespaces and that they must be part of the bind path.

<?xml version="1.0" encoding="UTF-8"?>
<p0:allCountries xmlns:p0="http://www.frevvo.com/database/allCountries">
   <row>
      <CountryID>1</CountryID>
      <CountryName>Argentina</CountryName>
   </row>
   <row>
      <CountryID>12</CountryID>
      <CountryName>Aruba</CountryName>
   </row>
   <row>
      <CountryID>13</CountryID>
      <CountryName>Bahamas</CountryName>
   </row>
</p0:allCountries

If the Value Binding and Label Binding properties are be set to the same path: /p0:allCountries/row/CountryName - the Country Name will be included in the submission and Users will see the Country Names as the options of the selection control: Argentina, Aruba, Bahamas


  6. Click the save and test icon to test your form/flow.
  7. The Example below uses the Database Connector to retrieve a Customer List from a database. It also shows to construct the Value and Label Bindings from the XML results returned in the Debug Console.


Excerpt
hiddentrue

The Edmunds API web service returns a “vehicle makes” options list in JSON format and lets you narrow the options to a specific year. Design a form with a field for the user to enter a year and a checkbox, radio or dropdown control.

Image Modified

Follow these steps to populate the options of your selection control with the results returned from the Edmunds web service

  1. Edit the form in the Forms Designer 
  2. Click on the Selection control (checkbox, radio or dropdown) 
  3. Set the Options Src to Web Service 
  4. Set the Options URL to: https://api.edmunds.com/api/vehicle/v2/makes?state=new&year={year}&view=basic&fmt=json&api_key=p9v6s4uv6998k464u33m8jx3

  5. Set the Value Binding to:   /makes/niceName

  6. Set the Label Binding to:   /makes/name

    Image Modified

  7. Save the form 

 When the user types something in the Year field, the web service is automatically called, the results are refreshed and the choices in the Car Makes checkbox will change based on whatever the web service returned. To test this, type in the year 2015 then the year 2017.


Dynamic Options Example

Let's say you have a form/flow with a Dropdown control named Customer. You want to populate the options of this control with a list of Customers Names. You also would like to store the Customer Number associated with the Selected customer in the form/flow submission. We will use the Database Connector as our Web Service. For this example, the Database Connector is configured in Standalone mode to work with a MySQL database named classicmodels.

The Customer dropdown options can be populated with a business rule but you can also use the Dynamic Options feature. The frevvo Database Connector executes a query against a database named classicmodels that will return a list of Customers in JSON format. We will determine the Value and Label bindings by examining the results returned in the debug console.

Follow these steps:

  1. Click on the Customer control.
  2. Select Web Service from the Option Src dropdown
  3. The Options URL is: http://localhost:8081/database/BIRT/allCustomers?_mediaType=json  This URL points to an instance of the Database Connector running on the save server/port as . The results of this query will show the Customer Number and Customer Name for each customer in the Customers database table in JSON format.
  4. After entering the Options URL ,click the save and test icon. 
  5. To determine the Value Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by the value from the results that you want to be stored in the submission XML - in this case - customerNumber
    3. The Value BInding should be set to: /resultSet/customerNumber
  6. To determine the Label Binding, examine the resultSet in the frevvo debug console.
    1. Begin the path with the forward slash - / followed by resultSet.
    2. Add another forward slash - / followed by value from the results that you want to see as the option labels - in this case - customerName
    3. The Label Binding should be set to: /resultSet/customerName



  7.  Click the save and test icon to test the form. Note the options display the Customer Name.



  8. Click Submit.
  9. Navigate to the Forms Home Page and click the Submissions icon. Open the submissions and view the Document tab. Note the Customer Number is the value stored there.

...

The ComboBox control supports three types of data retrieval: frevvo Users, frevvo Roles and Web Service. Select the data source using the dropdown in the Options Src property. Selecting Web Service makes it possible to use the ComboBox to retrieve values from a database and enable a list of possible partial matches. There is also a blank option. Pick this one if you are going to populate your ComboBox options using a business rule.

Note
  • frevvo Users and frevvo Roles require security/authentication. When selecting frevvo Users and frevvo Roles as the Option Src, your form or flow must be set to Authenticated Users (login required).
  • The Dynamic Options feature using the ComboBox will NOT work with SOAP web services.

...

  1. Drag the ComboBox control into your form/flow
  2. Set the Options Src to one of two choices: frevvo Users or frevvo Roles.
    1. Selecting frevvo Users - returns a list of ALL users in the current tenant.  constructs a URL:/frevvo/web/tn/{form.tenant.id}/users?match= then replaces the form.tenant.id template with the name of the current tenant. 

    2. Selecting frevvo Roles returns the list of ALL roles in the current tenant. constructs a URL:/frevvo/web/tn/{form.tenant.id}/roles?match= then replaces the form.tenant.id template with the name of the current tenant.

Image Modified

3. The ComboBox supports the ability to specify single or multiple values. Check the Single Value checkbox if you want to limit the choice to one value.

Image Modified

Users can typeahead to narrow the choices based on the letters entered. User ids and roles are case sensitive so remember to use the correct case when typing. 

Image Modified

4. Check the Options Value Only checkbox to restrict the ComboBox value to available options. Options Value Only is only available when Options Src is set to frevvo Users or frevvo Roles.

Info

You cannot test the ComboBox Options in the form/flow designers. Click the  save and test icon for the quickest way to verify that the ComboBox is working as expected.

Populate Dynamic Pick Lists from a Database with the ComboBox

The ComboBox control can be used to retrieve values from a web service and enable a list of possible partial matches. This is helpful when you have database queries that return a large number of options. You can filter the number of options returned from a query based on the text typed into the ComboBox. Users typeahead and are only presented with the matching options as choices.

  • Your web service must be able to filter results and accept parameters that drive filtering
  • A dynamic Options URL that contains the {<combobox control name>.matchText} parameter. As the user types text into the CombBox, the text will be substituted into the URL. The web service returns only the options matching the typed in text as choices.  
  • The ComboBox control shows up to 100 matching options. If the web service finds more that 100 possible matching options, only the first 100 are to be shown. Informing users that there are additional matches that are not shown is not supported.

Set the Options Source property of the ComboBox to Web Service then provide the Options URL and Bind Path properties:

  • Options URL - The URL of the RESTful web service that will retrieve matching options. Be sure that the URL contains the  {<combobox control name>.matchText} template parameter. 
  • Bind Path - The bind path of the matching options within the XML or JSON returned by the RESTful web service. The Bind Path property determines the selected value that is included in the submission and what the user sees.

Example

It is very common to pull options for a typeahead control such as the ComboBox from a database. If you are using the frevvo Database Connector to integrate with your SQL database you already have a Restful service that returns data as resultSets.

Let's say you have a classicmodels MySQL database with a Products table that contains 121 records. You have a form with a ComboBox control named NameofProduct and you want to populate the options from the query results. However, you do not expect your users to scroll through 121 choices until they find the one that they are looking for. Ideally, you would like to filter the results coming back from the query based on the characters inserted into ComboBox. Users can then typeahead and select a value from the filtered choices.

For this example, the frevvo Database Connector is installed on the same machine as and configured in Standalone mode running on port 8081.

  1. You will need a query to run against the database. This query, which is included in the BIRT queryset in the configuration.xml file, uses the MySQL Like and % wild cards, to return all the products that match the value in the template (pname}.

    Code Block
    <query name="productsByName">
<retrieve>
                <!--maps to HTTP GET -->
                <statement> SELECT * FROM Products where productName LIKE '%{pName}%' order by productName </statement>
</retrieve>
</query>

     

  2. Click on the ComboBox control to display the Properties panel. Select Web Service as the Options Src.

  3. Provide the URL to the datasource - in this case the URL to the database query in the BIRT queryset- productsByName. Add the {<combobox control name>.matchText} parameter to specify the value of the variable - pname - in the query as the matching text typed into the Name of Product control.

    Code Block
    http://<server>:<port>/database/BIRT/productsByName?pName={NameofProduct.matchText}
  4. Click the Image Modifiedsave and test icon. Enter a value into the ComboBox. Determine the Binding Path from the resultSet. In the image, the number 1 was entered into the ComboBox.

    Image Modified

  5. The ComboBox Properties panel should look like this. If you want to limit the user selection to one value, check the SIngle Value checkbox.

    Image Modified
     
  6.  Users will see all the returned options that match the number 1 when it is entered in the ComboBox. Adding 8t into the ComboBox will further filter the options and display the choices that match 18t . Each time a character is entered it is added to the URL and the Web Service is invoked. Only the matching results is displayed to the user.

...

You are not permitted to disable grouping controls such as panels or repeats. However, there is an Enabled property for Sections, each of the columns in a Table and each tab in a Tab control. If "enabled" is set on Tab or Section, controls inside of these group controls would be enabled. Conversely, if the property is unchecked, controls inside of a section or tab would be disabled. This property will make it easier to write Business Rules. 

You can enable/disable the selection controls via rules thereby enabling/disabling all the selection control options. It is not possible to enable/disable individual options.

Disabled tabs are still selectable and disabled sections can still be expanded and collapsed. This is as designed. If you are trying to show/hide the contents of a tab/section, use the 1063682390 property. 

...

The Save Value property applies to Message, Link, Image and Form Viewer controls. This property controls whether the control's value appears in the  form/flow submission document  . The property will be unchecked (default) for new Message, Link, Image or Form Viewer controls added to your form/flow. An example of the Properties pane for the Message control is shown in the image.

...

This property determines whether the value saved in the submissions repository is hidden when viewed in the  web submissions UI. Check the checkbox if the data users will enter into this field contains sensitive data that should not be visible when viewed in the web UI. Sensitive field values will be encrypted in the submissions database using an SHA algorithm. The control must be designated as a Saved Field in the form. This property does not enable hashing of the value stored in the XML document.

...

Another is the showhelp css class that is built into the Tight layout. For example, you can reduce white space even further with the Tight layout so that you have virtually no space between controls by selecting the hide label property on each control. This can be a way to implement a grid type layout as shown in this sample form below. 

When controls are this tight together there is no room to display the help icon for controls with help text. Notice that the first row of controls does displays the help icon. This is done by putting the string showhelp into the css class property for each control in the first row. This is a useful way to have help at the top of each column.

CSS Class to Set Font Size for the Table and Message Controls

...

The f-action- error css class displays text defined in a Message control if an Activity Document Action post returns an HTTP 422 status for a workflow step. Refer to Activity Document Action Behavior for Failed Post for the details.

Tip

If you are using Live Formsfrevvo in-house, Cascading Style Sheet code that was used in themes applied to forms/flows in previous Live Formsfrevvo releases, can be added to a newly created style.css file in the frevvo.war file . The context parameter, frevvo.css.url, in the web.xml file must be changed to point to it.

...

This property applies only to Submit controls. By default  disables the form's submit button until all required fields are filled and contain valid data. See Valid Forms for details of this feature. However, sometimes you may wish to override ' default behavior and allow the user to submit a form even if it is invalid. To do this, uncheck this property.

When "Enable if Valid" is checked and you click on the Submit button in a form that contains invalid data or required fields that are empty,  the form will not submit and the invalid fields will be highlighted with an orange background color. The designer can also display a message instructing the user what to do.

 This approach is very helpful to users when trying to determine why a form does not submit. Refer to this Invalid Form Notification for the details.

 

If "Enable if Valid" property is unchecked,  you can control the Submit button behavior in a business rule using the Submit.enabled = [true,false] property.

Prefix Property

Custom groups with rules included when dropped back onto the same or another form, will contain a special "Prefix" property. The property will automatically be given a unique value if you drop the group onto the same form 2 or more times. This ensures that the group controls have unique element name. You can view the impact the prefix has on the element names by viewing the form's schema or the control's property panel. Using the prefix property, you can write a separate rule to manipulate the 2nd or greater instance of the custom control. Refer to this documentation for the details.

...