Form builder

From Frevvodocs

If you have upgraded to Live Forms v2 please see the v2.x documentation.

Contents 1 Forms 1.1 New Form 1.2 Deleting a Form 1.3 Using a Form 1.4 Copy a Form 1.5 Download Schema 1.6 View Documents 1.7 Download a Form 1.8 Upload a Form 1.9 Publishing Forms 1.9.1 Editing Public Forms 2 Form Designer 2.1 Control Types 2.1.1 Input Controls 2.1.2 Select Controls 2.1.3 Message Control 2.1.4 Group Controls 2.2 Adding Controls 2.2.1 From Palette 2.2.2 From Schema 2.3 Editing Controls 2.4 Setting a Default Value for a Control 2.5 Removing a control 2.6 Control Type 2.7 Styling Controls 2.8 Drag and Drop 2.9 Patterns 2.10 Rules 2.10.1 Control Type Id 2.10.2 Rule Identifiers 2.10.3 When are rules executed ? 2.10.4 Rule Examples 2.10.5 Working with Rules 2.11 Finish / Cancel 2.12 Form Properties 2.13 Previewing Forms

Forms

In any application, click the forms link in the navigation menu on the upper right hand side. You will be taken to the Forms page for that application. This page lists the forms that you have created in this application. On this page you can

• Click the icon to create a new form
• Click the icon to upload a form from disk.
• Click the icon to edit a form
• Click the icon to use a form
• Click the icon to make a copy of an existing form
• Click the icon to download the XML schema for a form
• Click the icon to view the documents associated with submitted forms
• Click the icon to a download of the form to disk.
• Click the icon for details on embedding the form in your web page or email.
• Click the icon to delete an existing form
• Click the icon to mark your form public.
• Click the icon to mark your form private.

Also when you hover over any form a tool tip will display the form's description.

New Form

Create a new form by clicking on the icon. The form will immediately appear at the bottom of the list of forms. It will be given a generated name and description. You can customize this name and description when you edit the form using frevvo's Form Builder.

You may create as many forms as you require for your application.

Deleting a Form

Click the icon next to a form's name to delete it. Confirm your choice in the dialog that pops up and the form will be immediately removed. This is an irreversible process so make sure you do not need the form before you delete it. You can always download the application and save it before you delete it.

Using a Form

Click the icon below the form's name to use it. Use Mode is discussed in Using forms.

Copy a Form

Click the icon below the form's name to make a copy of that form. The copy is similar to the familiar copy and paste function. The copied form is a completely independent copy. Any changes to the copy will not affect the original and vice versa.

Download Schema

As discussed earlier, frevvo is an XML schema-aware application. You can automatically generate forms from one or more uploaded XML schemas. However, you can also create forms from-scratch using the form designer's palette. When you add controls using the palette, frevvo will automatically generate an XML schema for you that represents the data that the form is designed to collect. You can download this generated schema by clicking on the icon below any form.

Note that if your form consists of only controls from your own XML schemas, then the generated schema will be empty. If your form contains a mixture of controls added using the palette and controls generated from one or more uploaded XML schemas, then the generated schema will only contain elements for the palette controls.

In the simplest case, your form will consist of a set of controls dropped from the palette. frevvo will generate an XML schema for this set of controls, which you can download and use. Submitted instances of this form will generate a single XML document that conforms to this generated schema.

In the general case, your form will consist of a set of controls dropped from the palette and one or more sets of controls that are generated from one or more uploaded schemas. frevvo will generate an XML schema for the set of controls dropped from the palette, which you can download and use. Submitted instances of this form will generate a set of XML documents, each of which conforms to its schema.

View Documents

By default when a user fills in your form and clicks the submit button, the xml document representing the values entered by the user is submitted to the frevvo server and saved in the document repository.

To view the xml documents click the icon. This navigates you to the documents page which lists all the submitted form documents.

Download a Form

Click the icon below the form's name to download it to a zip file on disk.

Upload a Form

Click the icon at the top of the Forms page to upload a form zip file from disk.

Publishing Forms

frevvo forms are initially created as private forms. A private form is only accessible to the owner of the form. You must be logged in to frevvo as the user that created the form in order to access it even for the purpose of using the form. When a form is private, it displays the icon. When your form is ready for public use, you can publish it by clicking the icon next to it.

A public form is accessible to anyone only for the purpose of using the form. Editing is still restricted to the owner of the form as described above. When a form is public, it displays the icon. You can make a form private again by clicking the icon next to it.

See Integration With Your Webapp and Embedded Forms for more information.

Editing Public Forms

Use caution when editing forms that are public. If someone is using your form while you are editing it, they may experience errors. For example: "page not found".

When editing a form that is public, consider temporarily marking the form private. While this does not prevent errors for anyone that is currently in the process of using your form, it will prevent new users from using your form until you mark it public again. One good approach is to edit the form in a copy of your application running on a staging server. Then test the form fully until you are satisfied that it is correct. Finally replace the current form with the new form by removing the original application from the staging server and uploading the new application.

Another approach for minor changes is to first make a copy of the form via the icon next to the form. Experiment with changes required in the copy. Than migrate those changes to the original form. This minimizes the form's "down-time" while users may experience error conditions. As every time you commit changes to a form in the form designer you risk invalidating all the use mode instances which in turn causes the use mode errors.

Form Designer

The frevvo Live Forms™ Designer is the heart of frevvo's simple, quick, no coding required, form creation. The form designer enables you to quickly add controls to your form, customize their appearance and layout, and to add rules that affect the behaviour of the form. To use the form designer, click the name of any Form, and frevvo launches the Live Forms™ designer.

The form designer has a number of components. The left pane has three areas:

• Control Palette - you can drop controls into your form from this palette. Click on any item in the palette and it gets added to the top of your form.
• Types - this is the list of document types that for your form. Document types are discussed below.
• Schemas - this is the list of XML schemas that have been uploaded to the current application. You may add one or more elements from any schema listed here to your form.

The right side of the form designer is the work area for the actual form.

• Finish/Cancel buttons - these are displayed at the bottom of the form. Click the Finish button to save your changes or Cancel to discard them.
• edit tab - this tab displays the form in Edit mode. In this mode, various editing icons appear in the controls when the mouse is hovering over them. Clicking these icons allows you to customize the control in question. This is described in detail below.
• preview tab - this tab displays the form in Use mode or as it would appear to users of the form.
• rules tab - this tab displays any existing rules that have been created for this form. You can add, remove or edit rules via this tab. Rules are discussed below.
• form header - this area is only visible in the edit tab by default. You can edit properties of the entire form using the icons that appear in the header when the mouse is hovering over it.
• Submit/Cancel buttons - these buttons are part of the form and are greyed out in the form designer. In Use mode, these buttons will be dynamically enabled depending on the requirements of the form.

Control Types

frevvo supports a rich variety of controls in the form designer that enable you to create virtually any form that you desire. The various types of controls are described below.

Input Controls

These controls generate a text input field in the form. The different types of input controls cause frevvo to ensure that content entered by users matches the data type specified by the control. frevvo provides the following types of input controls:

• Text - this control allows any text.
• TextArea - free-form multi-line text input.
• Date - content must be a date. The entered date is visually normalized in the form field to the mm-dd-yyyy. The date submitted in the document is always converted to the standard yyyy-mm-dd xsd:date format. Here are examples of frevvo's supported date formats and their variants:
  • yyyy-MM-dd. Ex: 2007-09-15 or 2007-9-15
  • MM/dd/yy Ex: 09/15/07 or 9/15/2007
  • M-d-yy. Ex: 9-5-07
  • MMM dd yy. Ex: Sep 15 07
  • MMM dd, yyyy. Ex: September 15, 2007
  • etc...

All of the above examples will be display in the form as 09-15-2007. And will be submitted in the document as 2007-09-15.

• EMail - content must be a valid email address.
• Money - content must be a decimal number and may include a currency symbol prefix and ','s. frevvo formats the number entered into the money controls by adding a currency symbol and ',' as appropriate and base on the locale. Also decimal places entered are rounded based on the locale custom. For example, in the US, decimals with greater than 2 decimal places are rounded to two digits. The submitted instance document will contain full decimal precision and no added symbols. This example shows a value entered into a Money form field and their actual displayed value in the form:
  • 3067.749 -> $3,076.75
  • $4000 -> $4,000.00
• Phone - content must be a phone number. Currently, frevvo supports the following formats:
  • xxx.xxx.xxxx
  • xxx-xxx-xxxx
  • xxx.xxxx
  • xxx-xxxx
• Quantity - contents must be an integer.
• Number - content must be a decimal number.

In addition, the permitted content in any of these controls can be further restricted using a Pattern.

Select Controls

These controls generate selection fields that allow you to select one or more choices from a list of choices. frevvo provides the following types of select controls:

• Dropdown - this control generates the familiar dropdown list. The dropdown list has a blank item at the top. The user can select one of a list of choices. You can define the choices in the dropdown by editing the control as discussed later.
• Radio - this control generates the familiar set of radio buttons. The user can select one of the [mutually exclusive] choices. You can define the choices in the radio by editing the control as discussed later.
• Checkbox - this control generates the familiar set of checkboxes. The user can select one or more of the choices. You can define the choices in the checkbox by editing the control as discussed later.

Message Control

You may also add static text anywhere in your form using the message control from the palette. The message control can contain arbitrary XHTML, which will be formatted by the browser when it is displayed.

Buttons

You can add buttons to your form inside a message control. Here is an example of adding a button labeled Search that launches google.com when clicked. To add a button put this text into a message control.

<a href="http://www.google.com"> <input type="button" value="Search"/> </a>

Group Controls

Group controls may be used to organize the controls in your form. frevvo provides a number of grouping controls described below.

Sections

Section controls enable you to create groupings that can be expanded and collapsed again to help reduce visual clutter. Every section has and icons in theheader. Click on those icons to expand/collapse the section. You can drag and drop any other control or controls into a section to organize your form.

Tabs

Tab controls help you organize input controls in a tabbed view to reduce visual clutter. Click on the Tabs button in the control palette to add a tab group. The tab group will contain a single tab by default. Additional tabs may be added to the group via the icon on any one of the tab in the group. You can drag and drop any other control or controls into a tab to organize your form. And you can drag a single tab in the group on top of another tab in the group to rearrange the tabs. A tab group, as expected, only displays the controls in the currently selected tab.

Tabs have a default width. Limit tab labels to a length that fits on a single line in your tabs. If you required longer labels this is supported by customizing your theme to increase the tab widths.

Panels

Panels help you organize your form into columns. Panels have a width property. Add two panels to your form and change their width to 50%. Now the panels will float into a two column format on your form. Note that one of the widths will need to be slightly less than half - say 49% - for the panels to actually float next to each other in the edit tab. This is because the panel has a 1px border so that you can see its boundaries. Now drag other controls, text controls for instance, into the panels to group them into columns.

Panels are not visible in Use mode. If you click the preview tab or commit your changes and use the form, the panels themselves will not be visible. However, the contained controls are still visually organized according to the width of the panel.

Repeats

Repeat controls allow you to create a set of repeating items. The repeating item may itself be a simple control (input or select) or a group control. The repeat control manages the addition and removal of repeat items subject to any applicable minimum and maximum constraints.

Repeats are best explained using an example. A user may have multiple email addresses. If your form asks for an email address, you may wish to allow the user to enter as many email addresses as desired. You can also require a minimum of 1 email address and a maxiumum of 10, for example. This is accomplished using the repeat control. Click on the Repeat palette item. A repeat control is added to your form. Click on the EMail palette item to create an email input field. Drag and drop the email input into the repeat control. You can alter the minimum and maximum number of EMail addresses by editing the control as discussed below.

When the form is used, the repeating email address control will automatically display and icons depending on the minimum and maximum instances that are allowed.

If you add a control from a repeating element that was uploaded as part of a schema (maxOccurs > 1), frevvo will automatically generate a repeat control and nest the repeating item in that control. The behaviour is identical to that described above. The repeat control will always automatically enforce the minimum and maximum occurrences constraints.

Repeat controls are by default hidden in use mode forms. For example if your form has a repeat with a field name. When this is displayed in use mode, the repeat section will not be displayed on the form. Only the field name with a icon. The same is true if the repeat control contains a complex content such as a section control named address with multiple text controls for city, state and zip.

Since repeats are hidden in use mode, you must make sure that in edit mode you leave the repeat control in an expanded state. If you do not you will not only not see the repeat control itself, but you will never be able to see the fields contained within the repeat control. You can change this default behavior in the global narrow-vertical-green theme if you wish. See customizing forms for details.

Triggers

The trigger control adds a button to the form. When this button is clicked it generates a click event that can be evaluated in a rule. See the documentation on using triggers with rules for details on how to use trigger controls.

Adding Controls

Initially, a form is created with no controls except for a Submit and Cancel button. You must add controls to the form in order to make it useful. Controls can be dropped from the palette or generated from a schema.

From Palette

Click on any of the items in the control palette to add the corresponding control to the top of your form. You can later drag and drop the controls to organize them in your form.

From Schema

You must first upload your schema into your frevvo application before you can add controls from it. The form designer displays the schemas that are part of the application in the Schemas panel.

If you expand the folder for a schema, frevvo will display the list of global element declarations in that schema. You can add one or more elements from one or more schemas to your form. This creates a Document Type in your form. For each document type in the form, one XML instance document is created. You may add as many elements as you need. The document types for a form are displayed in the Types panel. You can now add controls for any node in any document type to the form. Just click the icon next to the node and frevvo will automatically generate the appropriate set of controls.

You can rearrange the controls generated by the form designer using drag and drop. frevvo will correctly maintain the required structure of the XML document irrespective of the arrangement of the controls.

When an element is added to the “Types” it becomes part of your form document even if you do not add any elements to the form from that type. It is important to understand this. When your form is submitted, it will generate a set of XML instance documents - one for each XSD element you added to the “Types” section.

Editing Controls

To edit the control’s properties, hover over the control and click the icon. A properties panel will appear displaying all applicable properties for this control type.

The contents of the properties panel are control type dependent. Everything in the edit container is optional. The possible properties are described below:

Label 

This is the label displayed on your form beside or above the control. Enter a string value here and the label of the control will change to the entered value. Note that a control's element name defaults to its label name. If you add a Label that is not an allowed xsd element name, make sure you also give that a control a valid Element Name.

Type ID 

This is a string ID that is used to reference all instances of this control. It is used for rules.

CSS Class 

The class name added to your form's XHTML markup for this control. You can use this CSS class to reference the control in any custom CSS or JavaScript when customizing themes.

Element Name 

The name given to the XML element corresponding to this control. You do not need to specify a value here. If you omit the name, it will be inferred from the label. The element name cannot be changed for controls that have been generated from an uploaded schema, since the schema specifies the element name. For such controls, this field will not appear in the edit container.

Pattern 

The pattern that an entered value must satisfy. Patterns essentially allow you to further restrict the space of allowed values for a control. The pattern cannot be modified for controls that have been generated from an uploaded schema, since the schema already specifies it. For such controls, this field will not appear in the edit container.

Hint 

If you enter a string, it will appear as a tooltip when the user's mouse hovers over the control.

Help 

You may enter help text here to provide more detailed help to the user. If a control has help text associated with it, then the icon appears when the mouse hovers over that control. If the icon is clicked, the help text is displayed in a floating box.

Required 

When a control is marked as required, frevvo will require the user to enter a valid value in that control before the form can be submitted. The Submit button in Use mode is automatically greyed out until then. If the data is optional, uncheck the Required checkbox. The required checkbox is not editable for controls that have been generated from an uploaded schema, since the schema already specifies this via the minOccurs attribute. For such controls, this field will appear disabled in the edit container. Sections, Repeats and other grouping controls also cannot be marked as required. Repeating items also cannot be marked as required since they may independently have a minimum and maximum number of occurrences as described below.

Password 

If this checkbox is checked, content will not appear in clear text when the form is used. Only input fields (of any type) may be marked as being password fields.

Enabled 

This checkbox determines whether the control is enabled or disabled when the form is initially loaded. If a control is disabled, then no value may be entered for that control. Sections, Repeats and other grouping controls cannot be marked as disabled. A disabled control may be enabled as applicable in the form using a Rule.

Visible 

This checkbox determines whether the control is visible or hidden when the form is initially loaded. If a control is marked as not visible, it will not be displayed in the form. A hidden control may be displayed as applicable in the form using a Rule.

Min # 

This is only applicable for a repeating item. Enter a positive integer value here and frevvo will enforce this required minimum number of occurrences. In Use mode, the user will not be able to remove an instance of the repeat item if doing so would violate this constraint. The min # field is not editable for repeating controls that have been generated from an uploaded schema, since the schema already specifies this via the minOccurs attribute. For such controls, this field will appear disabled in the edit container.

Max # 

This is only applicable for a repeating item. Enter a positive integer value here and frevvo will enforce this maximum number of occurrences. In Use mode, the user will not be able to add an instance of the repeat item if doing so would violate this constraint. The maximum number of occurrences also cannot be less than the minimum number. The max # field is not editable for repeating controls that have been generated from an uploaded schema, since the schema already specifies this via the minOccurs attribute. For such controls, this field will appear disabled in the edit container.

Options 

This is a repeating set of properties that is used to specify the choices in a select control. Enter a value in an option field and it will appear as a choice in the corresponding dropdown, radio or checkbox control. To add a new choice, click the icon next to any option field. A new option field gets added immediately below and you can type a value in order to create a dropdown item, radio button or checkbox. To remove an existing choice, click the icon next to the appropriate option field. Note that blank option fields do not modify the list of choices. The choices cannot be changed for controls that have been generated from an uploaded schema, since the schema specifies them. For such controls, this field will not appear in the edit container.

Message 

This is only applicable for message controls. Use this property to specify the message that is displayed in the message control. This content may contain arbitrary XHTML markup that will be formatted and displayed by the browser.

Width 

This is only applicable for panels. Use this property to alter the width of the panel. You may enter a value in %, px or em, for example, 45% or 200px.

Margin 

This is only applicable for panels. Use this property to specify margins for the panel. You may enter a value in %, px or em. The margin follows the standard CSS syntax, for example, "5px 10px 15px 20px" implies a top margin of 5 px, a right margin of 10px, a bottom margin of 15 px and a left margin of 20px.

Setting a Default Value for a Control

When designing your form, you can set default values for most controls. When users access your form, they’ll see the defaults you supplied.

For checkboxes, radio buttons and dropdowns, simply pick the choice you want as a default. For text controls and other input controls, just type the value in the control. Save (finish) your form with the defaults you want. If during design you decide you don’t want the default, just delete the text (for input controls), uncheck the checked checkboxes (for checkbox controls), unclick the radio button (for radio controls), or pick the blank option (for dropdown lists).

Keep in mind that any default value you set must conform to the control’s data type requirements. For example, you cannot set a default of ABC in a quantity control.

Removing a control

To remove a control, just click on the icon that appears when the mouse is hovering over the control. The control is immediately removed from the form.

Control Type

When you initially add a control from the form designer's palette to your form, its default label is indicative of its type. But once you change its label it is sometimes difficult to know its type. You can determine this in two different ways. One way is open the control's edit properties panel via the icon, and to then hover over the properties panel. A tool-tip will display the controls type. Make sure to hover over an empty area of the edit properties panel and not over one of the property's input fields.

Another way is to determine the control's type is to download the form's schema. Navigate to your application and click on the icon next to the form. The schema contains all the from-palette controls and a type attribute.

Styling Controls

To edit a control’s style, hover over the control and click the icon. A properties panel will appear. Click on the Style tab in the properties panel to display all applicable style options for this control type. These styles are a quick and easy way to override the base style for each control specified in your application's theme. By using the style properties, you can avoid the need to create a new theme and can instead use one of frevvo's Global themes as a base style. For more complex styling consider customizing a theme.

The contents of the properties panel style tab are control type dependent. Many of the properties can be specified using the common CSS values and units. For instance, margins and padding can be specified in units %, px, em... Color can be the name 'red' for instance or a hexidecimal RGB value, ...

The possible properties are described below:

Control Width 

This specifies the width of a control's input area. For example, if your form contains a zip code field, you can use this property to reduce the default input width to 5 characters using 5em.

Margin 

This specifies extra space around a control. Margin can be specified with four values for top, right, bottom, left. Ex: 1em 0.5em 1em 2em. If you specify only one value, it will be applied to all four regions. Margin can be specified in em, %, px, ... This property works in conjunction with padding to effect the placement of the control on the form.

Padding 

This specifies extra space around a control. Padding can be specified with four values for top, right, bottom, left. Ex: 1em 0.5em 1em 2em. If you specify only one value, it will be applied to all four regions. Padding can be specified in em, %, px, ... This property works in conjunction with margin to effect the placement of the control on the form.

Background Color 

This specifies the color that appears behind a control. Color can be specified as a string, hexidecimal RGB, ... For Example 'red' and #aa2211 are both valid values for Background Color.

Border Width 

This specifies the thinkness of a border around a control. Ex: 4px. Note that to see the border, you must also specify a Border Color different from the form's background color. Certain controls such as Section controls, have a border by default as specified in the theme that you select for your application. Others like the message control do not have borders by default.

Border Color

This specifies the border's color.

Border Style

This specifies the border's style such as solid, dotted, ...

Label Color 

This specifies the color of a control's label displayed on the form. Color can be specified as a string, hexidecimal RGB, ... For Example 'green' and #00cc77 are both valid values for Label Color.

Label Size

This specifies the font size of a control's label.

Bold

This will make the control's label bold.

Italic

This will make the control's label italic

Horizontal

This specifies whether the control is arranged vertically with the label above the control's input area, or vertically with the label to the right of the control's input area.

Drag and Drop

You can organize and rearrange the controls in your form by dragging controls and dropping them in the appropriate place. Every control has a drag handle (the icon) that appears when the mouse hovers over that control in Edit mode. When the mouse hovers over the drag handle, the cursor will change to a move cursor. You can drag the control using the drag handle and drop it anywhere. When the dragged control hovers over a droppable area, the droppable area below it will change color to indicate that something is hovering above it. When a control is being dragged various feedback icons appear in the space next to the drag handle. These icons let you know where the dragged control may be dropped and what will happen to the control when it is dropped. You could see the following icons:

• This means the control cannot be dropped here. The dropped control will revert back to its original location.
• This means that the dropped control will move above the control on which it is being dropped.
• This means that the dropped control will move below the control on which it is being dropped.
• This means that the dropped control will move inside the [group] control on which it is being dropped.
• This means that the dropped tab will move to the right of the tab on which it is being dropped. This is only applicable for tabs.

Drag and drop follows a somewhat complicated set of rules that determine when a control may be dropped on another one. A few things to remember:

• Generally, the top half of a droppable area will cause the dropped item to move above the control on which it was dropped.
• The bottom half of the droppable area will cause the dropped item to move either below (simple) or inside (groups) the control on which it was dropped. The feedback icon will indicate the applicable action.
• You can drop on group controls (sections, repeats, tabs) by hovering over the header of that control.
• There is no way to drop a control below a group control. Instead, move the group above the target control.
• Tabs can only be dropped on other tabs.
• A repeat control cannot have more than one repeat item. If a repeat control already contains a repeat item, it will not allow additional controls to be dropped inside it. Repeat items that are created from the palette may be moved outside the repeat control, modified as desired (for example, add more controls to a section) and then dropped back into the repeat control. Repeat items automatically generated from-schema may not be dragged outside the repeat control since this would violate the constraints imposed by the schema.

Patterns

Frevvo applies default validation rules to Input Controls (Text, Money, EMail ...) used in your form from the control palette. Frevvo ensures the inputs entered by users of your form matches the data type specified by the control. Patterns enable you to further restrict the allowed content. Note that using patterns requires a knowledge of XML schema regular expressions and XML schema data types.

frevvo validates content entered into input controls by assigning a default XML schema data type to each control. The table below lists the default data types for each kind of input control.

Input Control	XML Schema Type
Text	xsd:string
Date	xsd:date
EMail	types:emailType, an xsd:string restriction pattern defined in types.xsd
Money	types:number, an xsd:double restriction defined in types.xsd
Phone	types:phoneType, an xsd:string restriction pattern defined in types.xsd
Quantity	xsd:integer
Number	types:number, an xsd:double restriction defined in types.xsd

To set a pattern on a control, edit the control and add a valid regular expression pattern into the pattern field. When the changes are committed, frevvo will ensure that content entered in the control matches the specified pattern.

For example, here is a pattern that restricts a frevvo text control to only allow strings formatted as a US zip code: (\d{5}-\d{4})|(\d{5}). frevvo will only permit values entered into this field that are either a 5 digit string or 5 digits followed by the '-' character, followed by 4 digits. If an invalid value is entered, frevvo will indicate an error:

Patterns only make sense when they restrict the default types shown in the table above. It does not make sense to enter a pattern [a-z] for a Number control. Since Number controls only allow decimals and the pattern only allows lower case letters, there is no intersection between these two collections. Hence, there are no valid values for this control and the field will always be flagged as invalid by frevvo.

Another example is a pattern to restict the Phone control to only Connnecticut area codes 203 and 860: 203-\d{3}-\d{4}|860-\d{3}-\d{4}. This pattern contains the '|' character to combine the two pattern sets.

Default values entered into controls in the form designer must also match any patterns you have applied to the control. Thus for our zip code example you would have to enter a 5 digit or 5-4 digit string as a default.

The pattern cannot be modified for controls that have been generated from an uploaded schema, since the schema already specifies it. Patterns do not make sense for Dropdown, Radio & Checkbox controls or for grouping controls such as Sections, Repeats etc. For such controls, this field will not appear in the edit container.

Rules

Rules add behavior to forms. For instance, you can add a frevvo rule that will show/hide certain form controls or entire sections based on the state of other form controls. Displaying form fields in a context-sensitive manner reduces clutter and makes it easier for users to navigate your forms. Rules can also be used to update form values. For instance, you can compute the total invoice price on an order form from values of other form fields such as item quantity and price.

You can create rules for any form by clicking the Rules tab in the form designer. In this version of frevvo, a rule is created as a piece of JavaScript code. A future version of frevvo will provide a Rules wizard that makes it easier to create rules in a visual manner. Rules are saved and runable after you commit your form. In order to test a rule you must first commit your form. Then either test it in use mode by clicking on the icon, or edit the form and test the rule in the preview tab.

A rule is of the form:

if (condition)
{
   true actions;
}
else
{
  false actions;
}

You can create more advanced rules primarily for the purpose of looping over repeating items. We will describe these later.

Rules do not currently support the syntax:

• if (condition) statement1 else if (condition) statement2
• switch statements

Control Type Id

Rules usually need to reference form controls. This is accomplished by assigning each control a Type Id. The edit container for each control has a Type Id field. You may enter any string as the Type Id.

Note that this is [in a sense] the Id of the type meaning all control instances of that type will have the same Id. This is important for repeating controls. Let's say you have a repeating control 'Email Address' and you assign it a Type Id of Email. If the user wishes to enter three email addresses and creates three instances of the repeating 'Email Address' control, all three instances will have the same Type Id (Email). The rule must reference these repeating items as an array. We will describe repeating items in more detail below.

For now, it's important to understand that you must assign a Type Id to every control that you wish to reference in a Rule.

Rule Identifiers

As described above, rules refer to form controls using a Type Id. Let's say you have a control to which you have assigned the Type Id 'T'. You can refer to properties of this control in rules using identifiers.

Rules identifiers must always be of the form Type Id.<property>. In the current version of frevvo, the following properties are supported:

• visible : Set to false to hide a control and true to make the control visible.
• value : Read or write the value of a control. This is not applicable to sections, tabs and other controls where it does not make sense to set a value.
• enabled : Set to false to disable (grey out) a control so that a user can not change its value and true to enable it. This is not applicable to sections, tabs and other controls that do not make sense to disable/enable.
• expanded : Set to false to collapse a group control (sections & repeat controls only) and true to expand a group control.
• valid : The value of this property is true if the control contains a valid value otherwise false. Validity is based on the control’s type. For instance a numeric control will be invalid if the user enters a string value that cannot be converted to a number. This property can be read as well as written.
• required : Set to true to make a control required and display the red asterisk.
• options : A write only property that enables dynamic select control options (radio, dropdown & checkbox controls only).
• clicked : This property works with trigger controls. Its initial state is false. When a user clicks a trigger its state turns true.

Examples of identifiers used in frevvo rules are:

• FirstName.value
• BillingAddress.visible
• Email[1].value
• Email[i].visible

The latter two are examples of repeating controls. We will discuss repeating controls in more detail below. Note that the case of the properties is important. FirstName.value is a valid rule identifier but FirstName.Value or FirstName.vAlUe are not.

When are rules executed ?

Rules execution is triggered by a change of state on any of the controls the rule depends on. A rule will typically refer to one or more form controls and their properties and it will be executed if any of those properties change value. Note that Rules are not fired when the page is loaded. For example, the rule below will only be executed when N1.value changes its value.

if (N1.value > 0 || N2.value > 0) {
  T.value = N1.value + N2.value;
}

Now let's assume a use case where you want to show a message if a user enters an invalid email. The form has a required email input control (Type ID=E) and an action should be executed if the email control 'valid' property is 'false'. One could write the rule:

if (!E.valid) {
// code to show message here.
}

The code above would not work as expected. E is a required field and therefore E.valid initial value is 'false' since the field is in initially empty. When the user enters an invalid email address, E.valid would still have the value 'false' and the rule would not execute since there is no state change. The code below would work properly.

if ((E.value.length > 0) && (!E.valid)) {
// code to show message here.ita
}

Now, the rule depends on both the value of E.valid and E.value.length and therefore, when a string longer than zero characters is entered the rule will be executed and the message will be shown.

Rule Examples

Rules are probably best described using a number of examples.

Calculate a Total

You have a form with three controls and you have assigned them Type Ids N1, N2 and T respectively. When the user enters a value in either N1 or N2 you want to set the value of T to the sum of N1 and N2. The rule would be written as

if (N1.value > 0 || N2.value > 0) {
  T.value = N1.value + N2.value;
}

This rule will automatically fire whenever the user types something in N1 or N2 and will set the value of T appropriately. You can use any legal JavaScript operators in the expression such as subtraction or multiplication. However, it's important to ensure that the calculated value is valid with respect to the type of T. For example, if T was of type integer and the computed value of the expression was decimal (such as 1.5), then the rule would be attempting to set an invalid value in T. This is an error. The rule will set the value as requested, but will mark the field as invalid and take appropriate action such as disabling the submit button, displaying the control with a red background etc. Also, if controls are added to the form from the palette, it is important to ensure they have the correct type. For example, for a numeric calculation as described above, the controls should be of type Numeric (found in the palette).

Show/Hide Billing Address

You have a form with two controls and you have assigned them Type Ids B and S respectively. B is a checkbox with a single option - Yes. If checked the user wishes to enter a different billing address in S and you want to display S. The rule would be written as

if (B[0].value == 'Yes') {
  S.visible = true;
} else {
  S.visible = false;
}

This rule will automatically fire whenever the user checks or unchecks B and will show/hide the billing address section S. Again, you could use any legal JavaScript expression to compute the visible property of S as long as it evaluates to a boolean true or false value.

In this example, you would typically set the checkbox B to be initially unchecked and the section S to be initially hidden.

Enable/disable a question

You have a form with two controls and you have assigned them Type Ids B and Q respectively. B is a checkbox with a single option - Yes. . If checked the user is a smoker and you wish to ask an additional question in Q. The rule would be written as

if (B[0].value == 'Yes') {
  Q.enabled = true;
} else {
  Q.enabled = false;
}

This rule will automatically fire whenever the user checks or unchecks B and will enable/disable the question in Q. Again, you could use any legal JavaScript expression to compute the enabled property of Q as long as it evaluates to a boolean true or false value.

In this example, you would typically set the checkbox B to be initially unchecked and the control Q to be initially disabled.

Compute a subtotal for each item

This rule is an example of working with repeating items. Let's say, you have a form with a repeating section representing an Item that the user may purchase. Each section has a Price (with Type Id P), a Quantity (Type Id Q) and a Subtotal (Type Id S). There are multiple items on the page and the number of items on any given page is unknown. The price field is filled in automatically. When the user enters a value in the quantity field for any item, you wish to compute the subtotal.

The rule would be written as:

for (var i = 0; i < S.value.length; i++) {
  if (Q[i].value > 0) {
    S[i].value = Q[i].value * P[i].value;
  }
}

This rule will automatically fire whenever the user enters a value in the quantity field for any item. It will compute the subtotal for each item, for which the quantity is greater than 0 and fill in the subtotal field for that item with the computed value. If a particular item does not have a quantity, the subtotal is not computed.

Compute an invoice total

Consider the same form as the example above. Let's say you have a control named Total with Type Id T. You want to set the value of Total to be the total invoice price, which is the sum of all the computed subtotals above. This rule would be written as:

var tot = 0;
for (var i = 0; i < S.value.length; i++) {
  tot = tot + S[i].value;
}
T.value = tot;

This rule will fire whenever a subtotal is updated, for example, when it is updated via the rule above. It will add the values of all the subtotals to arrive at an invoice total. Note that you must use a temporary variable to compute the total. If you write the rule as:

T.value = 0;
for (var i = 0; i < S.value.length; i++) {
  T.value = T.value + S[i].value;
}

it will not work correctly. This is due to internal limitations in the way rules are evaluated.

Dropdown Options

This example automatically sets the option selected in one dropdown based on the option selected in another. This is often useful when you have a form with choices that were dynamically populated. For example, imagine product choices which are descriptive text. When the user selects a product, your form needs to perform an action based on a product ID rather than the descriptive product text. A nice way to do this is to have the rule that dynamically populates the product choices dropdown also populate a product ID dropdown which remains an invisible control in the form. The product choices dropdown control was assigned TypeId 'P' and the product ID dropdown control was assigned TypeId 'ID'

if (P.value.length > 0)
{
  var i;
  for (x in P.options) {
    if (P.value == P.options[x])
      i = P.options.indexOf(P.options[x]);
  }

  ID.value = ID.options[i] + '';
}

Here is a rule that dynamically populates both the product choices and product ID dropdowns.

if (S.value.length > 0) {
  eval('x=' + http.get('http://localhost:8182/products/?category=' + S.value));
  P.options = x.products;
  ID.options = x.ids;
}

Here's another example of a rule that uses the frevvo Database Connector to retrieve the product choices from a Database.

if (searchproducts.clicked) {
  eval('x=' + http.get('http://localhost:8181/database/products?category=' C.value)); 

  var opts1 = ['']; // default 1st option to blank
  var opts2 = [''];

  for (var i=0; i < x.resultSet.length; i++) {
    if (x.resultSet[i]) {
       opts1[i+1] = x.resultSet[i].docdescript;
       opts2[i+1] = x.resultSet[i].docnum;
    }
  }

  P.options = opts1;
  ID.options = opts2;
}

Clearing Dropdown Options

This sample resets a dropdown option to the automatically added blank option. For dropdowns added from palette controls and from schema, frevvo automatically adds a blank option so the dropdown initially shows no choice by default. To reset the dropdown to this state via a rule, you must set the dropdown control's value to null not the empty string. Since the empty string is not a valid option. Type size form field had a typeId named 'size'. And the selection form field when set to a new value requires the size field to be reset back to the default blank option.

if ((selection.value != Hselection.value) 
       && (!form.preload))
{ 
  // Store new Hselection in hidden field for use in next comparison
  Hselection .value = selection.value;

  size.value = null;
}

Checkbox Options

Checkbox controls are different from all other frevvo palette controls in that they are multi-select. Therefore the way to write rules with checkbox controls are in many ways similar to rules with repeat controls. This rule has a checkbox controls with id colorPalette with the options: purple, green, blue, yellow, orange. The form also contains a text control with id colorChoice. This rule assigns colorChoice the choices selected from colorPalette.

var choices = '';
for (var i = 0; i < colorPalette.value.length; i++)
{  
  choices = choices + colorPalette[i].value;
}
colorChoice.value = choices;

Notice that similar to repeat controls, due to an internal evaluation limitation, you must collect the choices in a variable inside the for loop. And then assign that control ID.value to that variable outside the for loop.

This rule is another example showing how checkbox controls are array types.

if (colorPalette.value.length > 0)
{
  colorChoice.value = 'Thank you for choosing colors';
}
else
{
  colorChoice.value = 'Please choose colors...';
}

Visible/Invisible

This rule makes the message control nickNameThankYou visible when the user enters a value into the nickName input text control. And then hides the message control if the user deletes the value in nickName.

if (nickName.value.length > 0 )
{
  nickNameThankYou.visible = true;
}
else
{ 
  nickNameThankYou.visible = false;
}

Multiple Choice

This rule makes the appropriate input text controls visible depending on the choice a user makes in a radio option controls searchChoice.

if (searchChoice.value == 'Organizations')
{
 orgname.visible = true;
 firstname.visible = false;
 lastname.visible = false;
 clientId.visible = false;
}
else if (searchChoice.value == 'Individuals')
{
 orgname.visible = false;
 firstname.visible = true;
 lastname.visible = true;
 clientId.visible = false;
}
else if (searchChoice.value == 'Client ID')
{
 orgname.visible = false;
 firstname.visible = false;
 lastname.visible = false;
 clientId.visible = true;
}

Triggers & Dynamic Options

This rule is executed when the user clicks the trigger controls with Type Id search. It then dynamically sets options on a dropdown list control with Type Id coffeeShopList.

if (search.clicked)
{
  coffeeShopList.options = ['Koffee', 'Starbucks', 'Willoughbys', 'Dunkin Donuts'];
}

Now replace the hard coded list of coffee shops with a rule that invokes an http.get. This must return an X-JSON header which containing a JSON object. The object is evaluated and assigned to the variable x. In this case the JSON object contains an options field of type array. See the section on dynamic content for more details.

if (search.clicked)
{
  eval('x=' + http.get('http://<webhost>/getCoffeeShopList')); 
  coffeeShopList.options = x.options;
}

Verify User

This rule executes when the user enters a value into the Username text field. It invokes a Url that returns a JSON object that has a boolean field name exists that is set to true if the user already exists. If the user already exists this rule then sets the value of a message control, makes that message control visible on the form and sets the Username valid property to false so that Username field displays as invalid to guide the user to make a correction. See the section on dynamic content for more details.

if (U.value.length > 0) {
  eval('x=' + http.get('http://<webhost>/uniqueUser?username=' + U.value));
  if (x.exists) {
    M.value = 'User: ' + U.value + ' already exists';
    M.visible = true;
    U.valid = false;
  } else {
    M.visible = false;
  }
}

Database Connector REST Services

The database connector REST services can be invoked via a rule. The http.get returns a JSON object that contains a resultSet array containing each row returned from the SQL query. For details on configuring the database connector see the documentation for Connecting to your database. For an overview of using JSON to dynamically populate dropdown controls click here.

In this example the database connector contains the following three <query> elements in configuration.xml:

<query name="lastnames">
   <retrieve>SELECT lastname FROM Customer</retrieve>
</query>

<query name="firstnames">
   <retrieve>SELECT firstname FROM Customer</retrieve>
</query>

<query name="names">
   <retrieve>SELECT firstname,lastname FROM Customer</retrieve>
</query>

The form contains a radio control with Yes/No options and a typeId getCustomerList. When the Yes option is clicked this rule executes the http get to the database connector URI http://<host>/database/lastnames. The returned JSON resultSet object is an array of all the lastnames returned by the select specified above in configuration.xml. The resultSet is then used to set the options in a dropdown control with typeId customerLastNames.

if (getCustomerList.value == 'Yes')
{
eval('x=' + http.get('http://<host>/database/lastnames')); 

var opts= [];
for (var i=0; i < x.resultSet.length; i++) {
  if (x.resultSet[i]) {
    opts[i] = x.resultSet[i].lastname;
  }
}
customerLastNames.options = opts;
}

This example is similar except the URI uses the names query which returns both first and last names for each row in the customer table.

if (getCustomerList.value == 'Yes')
{
eval('x=' + http.get('http://<host>/database/names')); 

var opts= [];
for (var i=0; i < x.resultSet.length; i++) {
  if (x.resultSet[i]) {
    opts[i] = x.resultSet[i].firstname + " " + x.resultSet[i].lastname
  }
}
customerFullNames.options = opts;
}

This example is similar except the event that triggers the execution of the rule is an initial instance document loaded into the form when it opens. See the section on Document URIs for details on configuring your form to load an instance document. This rule executes before the form becomes visible in the browser. Thus the dynamic options are populated prior to the user seeing the form.

The form's Document URI read method is set as follows. When the form loads frevvo will perform a get to this URI. Notice that the URI specifies the database connector. So the values come from a database resource. Also in this case the URI contains a parameter so you can indicate which particular document to get from the DocMgmt resource.

http://<host>/database/DocMgmt?docId={docId}

The database configuration.xml contains the following <query> element.

     <query name="DocMgmt" autocreate="true">
         <create>
             <!-- Maps to the HTTP POST method -->
             INSERT into documents SET docId='{docId}'
         </create>
         <retrieve>
             <!-- Maps to the HTTP GET method -->
             SELECT docname,docId FROM documents WHERE docId='{docId}'
         </retrieve>
         <update>
             <!-- Maps to the HTTP PUT method -->
             UPDATE documents SET docId='{docId}',docname='{docname}' WHERE docId='{docId}'
         </update>
         <delete>
             <!-- Maps to the HTTP DELETE method -->
             DELETE from documents WHERE docId='{docId}'
         </delete>
     </query>

First, the URL http://<host>/database/DocMgmt/schema was opened in the browser to automatically generate an XSD describing the resultset returned from the DocMgmt <retrieve> method. This XSD was then uploaded into the frevvo application and the resultSet type added to the form. The docname control from that schema was edited and given a typeId 'docname'.

The form URL was then opened in the browser. The URL was obtained by clicking the Embed button for this form and copying the URL from the displayed dialog box. A query parameter &docId=02 was appended to that URL to specify the exact document resource to load when the form loads. Notice that the query parameter name exactly matches the template name '{docId}' in the form's Document URI above.

When the form loads in the browser, frevvo initializes the docname controls from the database resource. If a document is found, the docname control will have a value whose length is > 0. This triggers the following rule which executes the firstnames query's retrieve method to populate the dynamic dropdown options in the customerFirstNames form field.

if (docname.value.length > 0)
{

eval('x=' + http.get('http://<host>/database/firstnames')); 

var opts= [];
for (var i=0; i < x.resultSet.length; i++) {
  if (x.resultSet[i]) {
    opts[i] = x.resultSet[i].firstname;
  }
}
customerFirstNames.options = opts;
}

Working with Rules

Creating a New Rule

In the form designer, click on the Rules tab. The page will display any existing rules that you may have created for this form. You may create a new rule by clicking on the icon. Your new rule is given a randomly generated name. You can edit the name as described below.

Editing an existing Rule

You can edit an existing rule by clicking on the icon. This opens an Edit Container for the rule, using which you can change the name, description and statement (JavaScript code) for the rule.

Deleting an existing Rule

Click the icon next to a rule's name to delete it. Confirm your choice in the dialog that pops up and the rule will be immediately removed. This is an irreversible process so make sure you do not need the rule before you delete it.

Disabling a Rule

Rules can be temporarily disabled. To disable a rule go to the form designer's Rule tab and open the rule's edit property and uncheck the enabled' checkbox.

Rules Wizard

Future frevvo releases will support a rule wizard making it easier to create rules without needing to understand simple JavaScript expressions and making it quicker to reference controls without needing to first assign them a unique ID. Also at this time rules support a single condition, true action and false action. Future frevvo releases will support multiple conditions and actions.

When are rules executed?

When you create or edit a rule, frevvo figures out the list of controls and properties of those controls that the rule depends upon. The rule will be automatically executed whenever there is a state change that is relevant to the rule. Rules are also executed sequentially in a top to bottom order as they are seen in the rules panel.

Note that rules can trigger the execution of other rules. So, if a rule, R1, sets the value of a control with Type Id A, and there is a rule R2, that depends on A.value, then rule R2 will be triggered and executed.

Infinite Loops

It's easy to create rules that run forever. An example, is a rule that updates A.value based on B.value and another rule that updates B.value based on A.value. They could continually trigger each other.

The frevvo server will prevent this from happening by setting an execution time limit for each rule. Any rule that takes longer than 5 seconds to execute will be forcibly stopped. Note that this is a very lengthy period of time for most computational tasks and the vast majority of rules will not be impacted by this constraint. However, since frevvo is a hosted site that may be simultaneously used by numerous users, there is a time limit imposed on these computations.

Rule Timeout

By default a rule that takes longer to execute then 5 seconds will be timed out by the Form Server. Customers using the in-house download version can customize this timeout. This is often necessary when rules have to perform longer running operations such as sending email messages, database stored procedures, etc... To configure the timeout add the following line to your web application containers property file. For the frevvo-tomcat bundle this file is .../tomcat/conf/Catalina/localhost/context.xml.default and is specified as follows:

<Parameter name="frevvo.rule.timeout" value="5000" override="false"/>

To set the timeout to 15 seconds set value="15000"

What is not permitted in a rule?

Setting the value of a control to an array or to a random JavaScript object is not allowed.

Select Controls

Radio controls, dropdowns and checkboxes are all examples of select controls. Radio & dropdown controls are single select. That is, if one item in the dropdown is selected then all other items in the dropdown are deselected. The same is true for a radio. Only one radio button can be depressed at any time. Thus the ID.value of radios and dropdowns are similar to the other input and output controls. The value is a single item.

Checkbox controls are multi-select. That is, multiple items can be selected at any given time. Thus the ID.value of a checkbox is an array. Therefore on checkboxes a valid expression is ID.value.length which returns the number of items in the value array. And ID[0].value would retrieve the 1st item in the list and ID[1].value the 2nd and so on. If you have a checkbox control with only one checkbox and that checkbox is unchecked, the array will contain no elements. For an checkbox control a useful expression is ID.value.length == 0. Note that ID.length is not a valid expression. Also since a checkbox control is an array it is not a valid expression to write ID[0].value == . Because if at option in the checkbox control is unchecked, it's value will not be an empty string. It will simply not exist in the array.

Message Controls

It is often useful to update text in a message control when a user performs a certain form action. Since the text set in a messageControl.value is displayed in the brower, embedded newlines must follow the html syntax and not the JavaScript syntax. Thus <br/> set in a messageControl.value will effect a newline but /n will not.

Initial Control State

Every control in your form has an initial default property states for the visible, expanded, value, valid & enabled properties. However you can change a controls initial state in frevvo’s form designer Edit tab. A control’s initial state can be modified several ways. One way is by simply tying a value into an input control. This sets the default value for the control when the form is first opened in use mode. Another way is by expanding or collapsing group controls. This sets the initial expanded state. The default state for the visible and enabled properties is set via the controls edit property panel. The edit property contains checkboxes for visible and enabled for controls on which those properties make sense like input controls.

Dynamic Content

Real business forms often require dynamic content in dropdown list. Often based on the value entered into one form field, the values in other fields or options available in select controls need to be dynamic.

Rules allow invocation of http gets that return X-JSON headers with JSON objects. This allows complete flexibility in assignment of default values populated into form fields such as text controls and select (radios, dropdown, checkbox) controls.

Here is an example that shows the syntax of the http.get. This rule invokes the http get which must return a JSON object. The method on the servlet can do whatever necessary such as querying a database given the itemName to retrieve the itemPrice. In this example the JSON object returned contains a field called price. The eval converts and assigns the JSON object to the javascript variable x. Then x can be used in the rule as necessary. In this case it is used to set a value to the form field called Price.

eval('x=' + http.get('http://<webhost>/test/json/getPrice?itemName=' + itemName.value)); 
Price.value = x.price;

Imagine another example where the JSON object returned in the http.get response contains an array called clients. This array can then be used to set the options in a dropdown list.

eval('x=' + http.get('http://<webhost>/test/json/getClients')); 
Clients.options = x.clients;

Form complete details of integration with your backend systems to provide dynamic data into your forms, see the section on integration.

Finish / Cancel

If you leave the form designer via the browser back button you will have neither committed nor canceled your changes. If you return to the form designer in the same browser session your latest updates will be in the form for you to finish or cancel.

Form Properties

Hover your mouse over the green area at the top of the form containing the form’s default name. An icon will appear. This icon opens an edit properties panel where you can change your form’s name and description.

The form properties also contains several properties to control what happens to the data when the user enters values and clicks the submit button. For each Document Type that you add to your form, frevvo permits you to assign

• a document URI Template
• a Read method and
• a Write method.

You can find additional information on these document URIs in the Section on Integrating with web applications.

The form properties also contain form and document actions which control what happens to the browser and the document set after the form is submitted. You can find additional information on these actions in the Section on Form and Document Actions.

Previewing Forms

frevvo’s form designer contains a preview tab. This tab display exactly how your form will look to an end user. By default, the header of the form is not visible in Use mode, panels are not visible, and edit mode icons (for drag and drop, remove and edit control) are not visible when the mouse hovers over the control. The preview tab gives you a quick look at the final appearance of the Use mode form.