V4 Designing Forms

frevvo Live Forms™ v4

Forms Designer

The frevvo Live Forms™ Designer is the heart of frevvo's simple, quick, no-coding required form creation. The Forms Designer enables you to add controls quickly to your form, customize their appearance and layout, and add rules that affect the behavior of the form.

For insights and research on the principles of good form design, we recommend the UX matters and CX partners websites.

We also recommend that tenant admin users not create or edit forms, nor have roles assigned to them. These users should restrict themselves to administrative tasks.

Start by clicking New to add your first application. Then click the name of the application or the Edit icon and click New to create your first form.

A unique and arbitrary form name will be generated automatically--Form 31 in this example. You'll change this name when you begin working on your form. Also, you'll see that your form already has Submit and Cancel buttons, since these are part of every form.

The Form Designer has several components. Each is described below.

Palette

The palette contains the controls you can use in your forms. Click on the control you want and drag it into your form. See adding controls for more information.

Custom Area

This area stores controls you’ve already created and customized so you can re-use them. Maybe you’ve created a dropdown list with your ten branch offices, for example. To add a customized control to this area, drag it from the form you’re working on and drop it over the shaded area that says “Custom.” (You can’t drag the control into the area beneath this.) The name you see in the Custom Area will be the control’s label; if you can't see the entire label, hover over the control to see the full name.

For complete details on publishing, using and managing custom controls see Control Templates

To use a control from the Custom Palette, click on it and drag it into your form. Once the control is in your form, you can modify any of its properties or simply leave it as it was. To delete any control from the Custom Area, simply click the icon.

Any modifications you make apply only to the form you’re working on — your changes will not affect the version of the control that's inside the Custom Area and will not affect other forms where you also used this custom control.

To publish a control into the Custom Palette either drag/drop the control from an existing form onto the Custom tab header or click the publish link in the control's properties. See publishing a control template for complete details.

See this Custom Control Video.

Properties Area

This is where you define values in a dropdown box, set the max length for an input field, create tooltips, and additional control customization. When you click on a control in your form, the Properties area displays the control’s properties so you can view and edit them. There are also form properties; click the toolbar at the top of the forms work area to access these.

Data Sources

This area displays the list of XML schemas added to the current application. You may add to your form one or more elements from any schema listed here by clicking Add from Schema, but you first must upload the schema into your application from the Schemas tab. Please see Data Sources for full details.

Forms Work Area

The right side of the Form Designer is the work area for the forms you create. At the top of this area is the toolbar.

Toolbar

The toolbar at the top of the forms work area is visible when you are designing your forms but it is not visible to you when you test your forms or when your users access your forms. The toolbar includes the following buttons:

• Click Preview to see the form as it will appear to users. You cannot enter data or click buttons in Preview mode (but frevvo’s Test feature lets you do this).
• Click Controls when you are finished working in Rules mode. If your form has no rules, you don’t need to use this button
• Click Rules to display your form’s existing rules, edit the rules, delete them, or create new ones. When you click this button, the left-hand portion of the Forms Designer becomes disabled until you click the Controls button. Rules are discussed in detail below
• Click Form Action to configure what users will see when they submit your form
• Click Doc Action to configure what happens to the data when they submit your form
• Click Finish to save the changes to your form
• Click Cancel to discard changes you’ve made to your form

Submit and Cancel Buttons

At the bottom of the forms work area are a Submit button and a Cancel button. They are part of every form you create and are both disabled while you are designing your form. When you test your form or users access it, the Submit button will be enabled dynamically only after valid data has been supplied in all required controls. To turn off this feature uncheck the Enable if Valid property.

Both buttons have properties that you can customize, so you are free to change the names of these buttons by editing their labels. Additional submit controls can be added to the form by dragging/dropping the submit control from the palette.

There is a special template Uri variable named {_frevvo_submit_name}. This template gets converted to the name of the submit button the user clicked when they submitted the form. This feature makes it possible to pass to the back-end system which submit button was clicked (if the form contains multiple submit buttons), so the back end can switch the functionality based on which button the user chose.

An example use of this feature is to have one submit button labeled "Submit," and drop another onto the form and label it "Save". For the Save button, uncheck Enable if Valid. The back end system can then control a save/load feature.

It is also possible to hide one or both of these buttons by unchecking the visible property. It is common to hide the Cancel button and less common to hide the Submit. One example is if the outer application, a JSP for example, takes over the function of handling a submit and then programmatically submits the frevvo form.

Palette Controls

frevvo’s palette offers a rich variety of controls that let you create virtually any form. All controls provide functionality as soon as you drop them into your form but need to be customized (edited) to suit the form you are designing. The purpose of each control is described below.

Input Controls

Input controls allow users to enter data (text, dates, numbers, etc.) into your form and automatically prevent them from entering the wrong data types. For example, if users enter letters into a number control, your form will display an error message and the Submit button will not be enabled until valid data is supplied. This validation happens automatically; you do not have to do anything special. The purpose of each input control is described below.

To validate the content in each input control, frevvo assigns a default XML schema data type to each control. The table below shows the default data types for each 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

The explanations below describe the controls generically—before you edit them to impose additional restrictions or define behavior specific to the form you’re creating.

Text

Allows users to type any text and is intended for short, one-line entries.

TextArea

Lets users type any text and is intended for longer, multi-line submissions. When users enter data, scroll bars appear as needed to accommodate the text. This control has a # of Rows property that controls the default number of lines visible in the input area.

In HTML there is no way to set a maxLength on a textarea control which is why the textarea control does not have the maxlength property like the text control. If you need a maxlength, it's best to either choose the text control, or this can be accomplished via a business rule. See the Business Rule for textarea Max Length.

Since users typically enter multi-line text into textarea controls this can pose a challenge if you want to display that text in an html page. For example you may want to display the entered text in your form's Doc Action display message, in an html formatted email or in on a web page such as your Confluence wiki. The challenge is caused by the fact that line breaks entered into a web form text area are represented by a single newline character \n while line breaks in an html context are represented by the html break characters:

<\br>

In order to display the text in a html context you need to replace the \n with the html break characters. See the business rules chapter textarea newline vs break for a working example.

Date

The date control lets users enter a date by typing it or by clicking the calendar icon. If users click the calendar to choose the date, the date they pick will be displayed in mm-dd-yyyy format (e.g., 09-01-2008). If users hand-type the date they may enter any of the allowable formats below, but the date immediately will be redisplayed on the form in mm-dd-yyyy format. Note that in the submissions XML document, the date will be converted to the standard xsd:date format of yyyy-mm-dd.

Allowable Date Formats and Examples:

• yyyy-mm-dd (2008-09-15 or 2008-9-15)
• mm/dd/yy (09/15/2008 or 9/15/2008)
• m-d-yy (9-5-08)
• mmm dd yy (Sep 15 08)
• mmm dd, yyyy (September 15, 2008)

EMail

Requires users to enter a valid EMail address. The address must conform to the following syntax: <name>@<name>.<string>

Money

Allows users to enter U.S. currency. Users may type commas and a decimal point, but if they don’t, the form will display these symbols for them. For example if a user types 4000, the form will redisplay the value as 4,000.00. The form also will round all entries to two decimal places. (Note that if a user types more than two digits after the decimal place the XML submissions document will store as many digits as the user entered but will not include the dollar symbol, decimal point or commas.)

Phone

Used for entering a phone number and allows any of the following formats: xxx.xxx.xxxx, xxx-xxx-xxxx, xxx.xxxx, or xxx-xxxx. If you want to enforce one of the 10-digit formats (to require an area code), you can edit the control’s Pattern.

Quantity

Used for entering quantities or any whole numbers (integers). The form displays an error message if users enter decimal points, commas, or anything other than an integer.

Number

Used for entering decimal numbers. Users may enter any number of digits after the decimal place (although you can edit the control’s Max Length or Pattern property to impose a practical limit).

Selection Controls (Dropdown, Radio, and Checkbox)

Selection controls let users choose from a list of options instead of having to enter text.

• Dropdown - This adds a dropdown list to your form. By default the first choice in the dropdown list will be blank; you define the other choices by editing the control’s Options properties.
• Radio - This adds mutually exclusive radio buttons. You define the number of radio buttons and the specific choices by editing the control’s Options properties.
• Checkbox - This adds a set of checkboxes so users can check one or more. As with the other selection controls, you edit the control’s Options properties to define the number of checkboxes and the specific choices.

If you select a radio option as the default default and later decide you do not want a option selected by default, you must remove that option from the control and tab out of the options property so that it is removed from the control. Then add the option back to the control's option list. Now that option is no longer a selected default.

NOTE: See also the Item Width and Option Width properties for styling options.

The frevvo palette does not include a Combo Box control — a dropdown list in which a user can type a new value or option — because they are not part of standard XHTML. However, many frevvo customers use dropdowns, radio buttons, or checkboxes with an Other option in combination with a business rule. If a user selects Other, the rule then displays a text control (such as Details or New Entry) the user can type in.

Upload Control

Use this to allow user to upload and submit attachments with your forms. The upload controls contains special properties to control the maximum attachment size allowed (in bytes) and the min and max number of attachments to accept per form submission. Attachments are viewable in the Submissions Repository. You can configure you form's Doc Action property to send attachments to a URL endpoint (ex: servlet) that can save the attachments locally within your company. For more details see handling attachments.

frevvo itself sets an upper limit on attachment sizes. If you enter a value into the control's max attachment size property greater than frevvo's internal default upper limit, you will see an error message displayed on the upload control.

In-house, a download customer can control frevvo's internal upper limit via the web.xml parameter frevvo.attachment.maxsize, and can also set the max attachment size per user by editing the user's profile as the admin user and editing the Configuration field shown below.

Message Control (for Static Text)

Use this when you want static text on your form. You provide the text in the control’s Message property and can include arbitrary XHMTL with your text—maybe you want two lines with different font sizes or colors, for instance. The browser will format the XHMTL when users access the form.

Lets say you wanted to add the following header information to your form:

This can be done using 2 panels and 2 message controls.

The first message control contains the following text:

<center style="font-weight:bold;">
Connecticut Surgeons, LLC
</center>
<center style="line-height:1.2em;">
82 Anderson Road<br/>
Branford, CT 06180<br/>
</center>

The 2nd message control contains this text:

<center style="line-height:1.2em;text-align:right;">
<br/>
Bruce Wainwright, M.D.<br/>
Nancy Smith, M.D.<br/>
Jennifer Lewis-Barr, PA-C
</center>

Link Control (for URLs)

Use the Link Control when you want to include a URL in your form. When users click the link, the target URL will open in a separate browser window.

Image Control

This control lets you include an image (picture, logo, etc.) in your form. The control allows you to use .JPG, .GIF, and .PNG files or any other image type that your browser supports.

When you drag in the control, you’ll see a Browse button and an Upload Image button. Click Browse, navigate to the image you want, and click Upload Image. After you upload the image, the Browse and Upload Image buttons disappear, so if you aren’t satisfied with the image, delete the image control and drag in a new one.

Choose images that fit sensibly in your form before you upload it. The “regular” form size is 600px. You can resize an uploaded image by selecting the image control in the designer, clicking on the style tab in the properties panel and setting the width. Units are px, % or em. Make sure you include the unit. For example 50% will resize the image to half the width of the form or panel.

Video Control

This lets you include video files in your form and works the same way as the image control. The control supports .SWF files and other video file formats that are supported by your browser.

Trigger Control

The trigger control adds a button to your form and is used in conjunction with rules. If your form does not have rules you will not need the trigger control. If your form does have rules, see Triggers & Dynamic Options for details on how to use trigger controls and examples of when you might want to use them.

Note: Triggers do not work in repeating items.

Submit Control

The submit control adds a new button to your form that, when clicked, will submit the form. By default, new forms already contain a single submit button labeled "Submit." Submit buttons can only be added to the bottom of the form in a special drag/drop area.

Group Controls (Sections, Tabs, Panels and Repeats)

Group controls help you organize your forms and give them a professional appearance free of visual clutter. Each group control is described below.

Sections

Use sections to create groups of controls that users can expand and collapse.

Click the icon to expand a collapsed section or to collapse an expanded section. When users access your form the section can be expanded or collapsed—it’s up to you. If you want the section collapsed initially, make sure it is collapsed when you save (finish) your form.

After you drag a section control into your form, you can drag any other controls inside it—panels as in the example below, or even another section control.

If you have a required control inside a collapsed section, the section label turns red to cue users that they must expand the section and supply the required information before they submit the form.

If you delete a section control while designing your form, frevvo will automatically delete all controls you dragged inside the section.

See Optional Sections for details on using the required property with sections and how that affects the validation.

Tabs

This group control lets you create a tabbed view as in the example below.

When you drag the tab control into your form you’ll start with three individual tabs. To add or remove a tab, click any tab and then click the or icon. Added tabs appear to the right of the tab from which you clicked the add icon.

To rearrange the tab order, drag one tab on top of another tab; the tab you dragged will move to the right of the tab upon which it was dropped. (Since you can’t move tabs left, if you wanted the Shipping Details tab before the Customer Info tab in the example above, you’d drag the Shipping Details tab and drop it on the Product Info tab.)

You can drag in other controls (including other group controls) into any individual tabs. As you’d expect, users will see only those controls in the currently selected tab—in the example above we dragged the First Name, Last Name, Phone and Email controls into the Customer Info tab, so these will not be visible when users select the Product Info or Shipping Details tabs. When users click the Shipping tab, they see different controls as shown below.

To move your entire group of tabs to another spot in your form, click the area to the right of your last tab and drag the entire group to the desired location.

Tab controls have some limitations:

• Individual tabs in a tab group must be the same size and fit on one row
• Individual tab labels must fit on one line

Tab Widths

Multiple rows of tabs are not fully supported, so if your tabs spill over to the second row, adjust the width of your tabs and also possibly the form width. To edit the tab widths, click the unlabeled area to the right of your last tab; this will display the tab group properties on the left side of the Forms Designer.

Type a percentage in the tab group’s Width property field. With five tabs, for example, typing 19% will cause each individual tab to take up 19% of your form’s width. As with panels you must account for space consumed by tab borders—so if you try to set the width to 20% the five tabs won’t fit on one row.

Deleting a Tab Control

Select the entire tab control by clicking on the unlabeled area to the right or your last tab; this will display a red X that when clicked will delete the entire tab control.

Panels

Use panel controls to create columns. If you want two columns in your form, drag in two panels; drag in three panels for a three-column layout, and so on.

By default a panel's width is set to 49%, so when you drag two panels into your form, the second panel automatically will line up next to the first panel. Panels have a 1px border so you can see their boundaries; so for a two-column layout this means you cannot make both widths 50% or there will not be enough room on your form to line up the panels side by side.

Since panels are group controls, you drag other controls inside them. Below are three panels that have been dragged in to the palette for use in a three-column layout. Inside the first panel is a text control (city), a dropdown control (state) and another text control (zip). Note that when you drag in the third panel, it will not align side-by-side with the first two columns, since at this point the width of all three panels adds up to 147%.

Since our example calls for three columns and we want the first larger than the others, we can modify our panels widths to be 55%, 20%, and 23% respectively. As soon as we adjust the width of the third panel, all three panels automatically will line up next to each other and look like columns, as in the illustration below.

If you want to rearrange the order of your panels, be aware of frevvo’s drag-and-drop restriction that prevents you from dropping a control below a group control. If you have three columns and want the middle column at the far right, you must drag the middle column above whichever control is directly beneath your panels. (If you haven’t dragged other controls into your form, drop the middle column over the submit button.) Also, in a three- or four-column scenario if you want one to move one of the middle columns or the right-most column to the far left, you must drag and drop it above your left-most column.

Although panels have labels you can edit during design, the panel labels and panels themselves are not visible to users or to you when you test or preview your form. (In the example above users will not see the "Three-column layout" panel label.) Only the controls inside your panels are visible; these controls will be organized visually according to the width of the panels. Although users don't see panels, you still may wish to give your panels meaningful labels if you plan to add them to your custom palette and reuse them in other forms.

If you delete a panel frevvo automatically deletes any controls you’ve dragged inside it.

Repeats

Say you want users to be able to enter one or more addresses, phone numbers, or other data. With repeating controls, your form can dynamically display as many controls as a user needs rather than always showing extra input controls that may not be needed.

Drag the repeat control into your form and then drag another control into the repeat control just like you would for sections, tabs or panels. When the control is inside your repeat control, click the control to see its properties (on the left hand side of the Forms Designer). Notice that two Settings properties have been added to the properties you normally see for the control: Min# and Max#. These properties default to 1, 1. You must change them as described below to make the control repeat.

These minimum and maximum properties control the behavior users will see on the form. In the example below we’ve set the phone control min # to 2 and the max # to 5, so when they access the form users will see two phone controls and both will be required. Also, both will have an icon; clicking this automatically displays another phone control. If you click during design, the min# property will be incremented automatically. (The icon above each control is optional and appears because we set the phone control's Help property.)

It is often helpful to tell the user how to add additional repeat items. You can easily do this by dragging a message control into the form with the following text:

<center>Click on the <img src="/frevvo/images/icons/add.gif"/> icon to add 
more phone numbers to the list.
<br/></center>

The first items in order up to the min# must be filled in when the form is used in order for the submit button to be enabled. Thus if the user enters a value into the 1st repeat item and then the 2nd repeat item, and then clicks plus on the first repeat item, a new item will be added to the form between what was the 1st and the 2nd moving what was the 2nd item to the 3rd position in the list. The new 2nd item will become required because it has no value. Until the new 2nd item is filled with a value the form will not be submittable.

Thus it is not enough that 2 items contain values when min# is 2. The 1st two items must contain values.

If users elect to supply the maximum number of values, after all controls are displayed, the icons will disappear from the form and only the icons will remain.

When you edit the label or any properties of a control inside a repeat control, your changes will be applied to every instance of the control inside the repeat control. The same is true if you decide to delete a control inside the repeat control—all instances of the control will be deleted.

As with panels, repeat controls are hidden when testing or using forms and only the controls inside your repeat controls are visible. (The input controls will have icons as a visual cue to users.)

There are some key differences between repeat controls and the other grouping controls:

• You may drag in only one control, and you may not drag in tab controls, panels or other repeat controls.
• You may not drag in trigger, message, image or video controls.

You can have multiple controls inside a repeat. To do this, first add your controls to a section control, and then dragging the section into the repeat control.

NOTE: If you need to add more controls to the section, you must first drag the section back out of the repeat. Add the additional controls, and then drag the section back into the repeat. Panels are the exception: you can drop a panel into a section without first dragging the section out of the repeat.

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

When referring to repeat controls in various places such as Form Action display message, you must use a special template syntax. See templates for repeat controls for details.

Adding Controls (Drag & Drop)

From the Palette

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.

When you create a new form from scratch, it has no controls other than the Submit and Cancel button. To make your form useful you must start by dragging in controls from the Palette and dropping them in your form.

As you begin to drag a control from the Palette, you’ll see this icon, which means the control is not yet over a droppable area. You must drop controls into the body of the form; you can’t drop them into the toolbar nor can they be dropped below the Submit and Cancel buttons.

As you bring the control over the body of your form, the icon will change to one of the icons below:

• This means your control will be placed above the control over which you are hovering. You’ll see this icon when you drag the control over the top half of a droppable area.
• This means your control will be placed below the control over which you are hovering. You’ll see this icon when you drag the control over the bottom half of a droppable area.
• If you are hovering over a group control--tab, panel, section or repeat--this means your control will be placed inside the group control. (If other controls already are inside your group control, this icon appears only when you hover over the group control header and means your control will be placed inside the group, at the top. You’ll see the and icons as you hover over any controls inside your group control so you can govern exactly where inside the group control your new control will go.)

If you are not dragging your control over a group control, this means your control will be placed at the top of your form. Anywhere to the left of the print icon is a droppable area.

• This means your tab will move to the right of the tab on which it is being dropped. This applies only to tab controls.

Other important drag-and-drop rules:

• If you let go of a control while the icon is showing, your control will go back to where it was—either back to the Palette or where it was in your form before you tried to move it.
• You can only drop individual tabs in a tab group on other tabs in the tab group (and you’d do this only if you wanted to rearrange the order of the individual tabs inside a tab control).
• You can never drop any control directly below a group control. If you want the control you are dragging to go below the group control, drop your control above a different control that is below the group control or first move the group control. Remember that the Submit and Cancel button are controls, too.
• You can never drop two different controls into a repeat control—for example, you cannot drag in a quantity control if your repeat control already contains an email control. If you need multiple controls inside a repeat control, first drag the controls into a section, then drop the section into the repeat. Once the section is inside your repeat you may not add anything else to the section, so build the section first in this case. You also may never drop a panel, tab or another repeat control inside a repeat control, nor may you drag in trigger, video, image or link controls. See Repeats for more details.

Note that repeat items automatically generated from a schema may not be dragged outside the repeat control since this would violate the constraints imposed by the schema.

From Schema

You can generate controls automatically from schema elements, but you must first upload your schema into your frevvo application. Once you've uploaded the schema and added schema elements to your form's Data Sources area, you can generate controls from these elements automatically. See Generating Controls from Schema Elements

Editing Controls

To edit a control’s properties, click on the control in your form. The Forms Designer’s Properties area will display the control’s existing properties, so you can edit them.

Controls have Setting properties and Style properties. Generally speaking, Setting properties affect the control’s behavior and Style properties affect its appearance. The specific properties you see depend on the type of control you’ve selected in your form; some controls have more properties than others. All properties are optional, with the exception of the control label.

Control Setting Properties

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

Label

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.

You aren’t restricted to plain text for labels. You may use arbitrary XHMTL when typing the label name. Say you want two different font sizes and colors for a label as in the illustration below.

In the Label field, type this XHTML: Password <span style = "font-size:0.9 em; color: red; "> (6 characters) </span>.

When typing labels you are free to use any special characters with the exception of the less-than sign (<). If you need a less-than sign in your label, substitute the characters & l t ; (with no spaces between) for the less-than symbol.

Labels can also contain templates that will be replaced by values entered into your form as the form is used. See Templates for details.

Note that a control's name defaults to its label minus any spaces and special characters. Spaces and special characters are removed in order to make the name valid for use in rules and, for XML users, valid as a xsd schema element name. If the name begins with a numeral (for example,123Name), frevvo preppends an underscore to the it (for example, _123Name) to make it a valid XSD element name.

Also note that if you have two controls with the same label, the control's name will automatically be made unique. If you try to edit the name such that it would no longer be unique frevvo will prevent the edit.

Pattern

Most controls automatically ensure that users provide the correct data type, but patterns give you the flexibility to impose additional restrictions on what users enter in a particular control.

In the Pattern field in the Properties area, type your pattern using XML schema regular expressions. A simple example is a pattern that restricts a text control to only allow strings formatted as a US zip code: \d{5}|\d{5}-\d{4}. If you type this expression in the Patterns property, your form will permit values entered into this field only if they are five digits or five digits followed by the '-' character, followed by 4 digits.

When you define patterns you don’t have to restrict what the control handles automatically. It is not necessary to enter a pattern [a-z] for a Number control, since users can’t type letters in a number field anyway. Since essentially you would be attempting to expand the allowed data types in the control, frevvo would ignore this pattern if you entered it.

Note that you may have to first save the form before the pattern takes effect. Patterns take effect immediately the second and subsequent times you edit the form making it convenient to test the pattern in the designer.

See Patterns and Validation for more information and useful patterns.

Hint

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.

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.

Error Message

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.

For example, if you are using a pattern that requires the user to enter an area code of 203 or 860 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.

Control Type

This applies to selection controls (dropdowns, radios and checkboxes) and most input controls (text, text area, email, phone, quantity and number) 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.

There are some limitations: you cannot change a selection control to an input control or vice versa. This means you easily can switch a checkbox to a dropdown list, but you cannot use this property to change a checkbox to a text control.

This property is also useful for verifying what kind of controls are in your form. Since you assign new labels to your controls after you drag them in, you occasionally might forget whether you are looking at a text control or phone control, for example. This property lets you know what kind of controls are in your form no matter what the labels say.

Note: If your control was generated from a schema element, it will have a Format As property instead of a Control Type property. See below.

Format As

This property applies only to controls generated from XSD schema elements. (If the control was dragged in from the palette, it has a Control Type property; if the control was generated from a schema element, it has a Format As property instead, as shown below.)

You can adjust the Format As property to change the way your control looks on your form (for example, by changing a dropdown to a text control or vice versa). This will change the control's appearance but will not affect how the control validates data. If you need to modify the control's validation behavior, you must update the schema.

To see the control's underlying data type you can hover over the property tab.

If you change the Format As to one of the select control types: radio, dropdown or checkbox, a new property called Labels becomes visible. By adding strings into the labels property you can restrict the values allowed to be entered into this control when users use your form. When the form is submitted the value will be equivalent to the selected option label.

Another way to set the labels is via a rule to dynamically initialized the options when the form loads. See the Business Rules chapter for more details. Also see the section on dynamic initialization from database SQL queries.

Date Format

This property applies only to Date controls. It supports European date formatting. By using this property, dates entered into the form get translated according to the chosen format and be reformatted to match the selected format.

1. A date typed into a form field will be reformatted to match the selected Date Format
2. A date entered into a form field will be translated according to the selected format. For example,if you choose a European format of DD-MM-YYYY and enter 10-05-2009 the date value will be translated as May 10, 2009. If you choose a US format of MM-DD-YYY the date value will be translated as October 5, 2009.
3. If you choose any of MM-DD-YYYY using either - or / or . as the separator, all will be valid for that format but will be translated to the selected separator
4. Users can still enter dates like Feb 3, 2001. It will be translated into the specified format

Max Length

This property is available for text controls and other input controls and limits how many characters users can supply in the control. Simply type a number (positive integer) in the Max Length field. Text area controls do not support this property due to an HTML limitation. However it is very easy to add this functionality to the text area control using a business rule.

# of Rows

This property applies only to text area controls and lets you define the initial size of the text area. Scroll bars will appear automatically when the user reaches the # of rows you specify.

Required

Make a control required when you want to force users to enter a valid value in the control before they submit your form. To do this, check the Required checkbox in the Properties area. If the data is optional, leave the checkbox unchecked.

As soon as you mark a control required, red asterisks appear next to it on your form. Until users populate all required controls with valid data, they will not be able to submit the form because the Submit button will be disabled.

You cannot mark grouping controls (tabs, sections, panels and repeats) required. Input controls that are direct children (directly inside) of repeat controls also cannot be marked required, nor do they need to be, since the min# and max# properties take care of this already. You may, however, make controls required when they are inside sections, tabs and panels.

You cannot edit the required property for controls that have been generated from an uploaded schema, since the schema already specifies this via the minOccurs attribute. If a control from schema appears as required and you don't want it to be required, edit the XSD and set minOccurs=0. Re-upload the XSD. Then the control will no longer appear required.

This property is very useful when using rules to hide/show sections depending on something else in the form. If you hide the section you may have to set the required property to false . See Visible/Invisible Sections in Rules Examples for full details.

Options

This property appears for dropdown, radio and checkbox controls and is how you populate the choices the user sees in these controls.

You may have option labels different from option values. The syntax for the options is <value>=<label>. The <label> is what will be displayed on your form and the <value> is what is saved as the selected value when the user submits the form.

When you first drag one of these controls into your form they have generic values: Option 1, Option 2 and Option 3. This matches the generic text you see in the Properties area. To supply your own values, simply overlay the values in the Options property with the values you want and add more (or delete) as necessary.

If you do not enter both <value> and <label> using the <value>=<label> syntax, then the value will default to the label. As soon as you tab off the options property, options without values will automatically be converted to the syntax.

Here the options are entered without values. In this case frevvo will default the value to the label.

As soon as you tab out of the Options property the options will be automatically converted to the <value>=<label> syntax.

If you would like the submitted values to differ from the visible label then edit the options as follows. In this case the values are A, B, C, while the visible labels remain morning, afternoon, evening.

The order of choices in your control will match the order in the Properties area. If you have choices that need a logical order (you’d want a dropdown of US states to be sorted alphabetically, presumably), make sure the order is correct in the Properties area. (You can’t sort the text you enter in the Options property field but you can cut and paste.)

In addition to the generic Option 1, 2 and 3 choices, a dropdown control also includes a blank option that by default will appear first in the list. This blank option will appear no matter what text you supply in the Options property. You cannot remove the blank option but you can make one of the other options the default. See setting defaults.

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.

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

Labels

This property applies only to controls generated from schema elements. (If you drag a control in from the palette, it has a Options property; if the control was generated from a schema element, it has a Labels property instead.)

You can change the controls labels, although the XSD values for the control in the the schema do not change. In other words, you can change what a user sees in the form, but not the underlying values (i.e., you cannot use the [value=label] syntax you use for palette controls to change the element values).

For example, the schema below specifies choices for an event registration as: A, B, C. However, the form would be easier to understand if the labels for A, B and C were morning, afternoon, and evening. You can edit the labels, and the form will show morning, afternoon and evening. However, when this form is submitted, the submission will still correctly contain the required values A, B or C. If you want to change these values, you must edit and re-upload the schema.

         <xsd:element minOccurs="0" name="Registration">
              <xsd:simpleType>
                 <xsd:restriction base="xsd:string">
                   <xsd:enumeration value="A"/>
                   <xsd:enumeration value="B"/>
                   <xsd:enumeration value="C"/>
                 </xsd:restriction>
              </xsd:simpleType>
         </xsd:element>

Note also that you cannot add more labels to the control than the number of XSD values defined for the control in the schema. Using the example above, you cannot add a fourth label to the control because the schema specifies only three possible values (A, B, C) for the control.

The Labels property is also very useful when used in conjunction with the Format As property. For example, imagine your XSD schema contains an element named "product" which is of the type xsd:string. But you know for a fact that there are a limited set of product types that are allowed by the back-end system (a database, for example). An xsd:string element will create a text control on your form by default. But you can easily change the form to restrict the types by using the Format As property to change the control from text to dropdown. Then use the labels property to enter the list of product choices. The submission values will now be restricted to that set of options rather then any text string.

Though you can still edit the underlying schema to add an enumeration or set the options in a business rule, using the labels property makes this common task easier.

Enabled

This property determines whether the control is enabled or disabled when users first access your form. If you check the DISABLED checkbox, users may not enter a value in the control until the control is enabled. (You can enable the control using a Rule.)

For example, say you are creating a wedding invitation form and want to know if the people completing your form are bringing a guest. Your form might include a text control for the guest’s name that becomes enabled only after users indicate (in another control) that they are in fact coming to the wedding.

You are not permitted to disable grouping controls.

Visible

This property determines whether the control is visible or hidden when users first access your form. It is almost identical in concept to the Enabled property, but instead of disabling the control you hide it and write a Rule that makes it visible based on what users enter in another control.

Hide Label

This property determines whether the control’s label will be displayed on your form. Check the checkbox to hide the label on your form; leave it unchecked to show the control’s label.

Message

This property applies only to message controls and is where you enter the static text that will appear on your form. In addition to regular text, you may include in this property field arbitrary XHTML markup that will be formatted and displayed by the browser.

Min# and Max#

These properties appear only when your form has an input control inside a repeat control and apply to the input control. Simply type a number (positive integer) in the two property fields. If you specify a min # of 1 and max # of 10, users must enter values in at least one input control or they will be unable to submit the form, but they may enter as many as ten. See repeat controls for more details.

If you set the min# to 0, users initially will see one email control but won’t be required to supply an EMail address to submit the form.

Min/Max properties are not editable for controls generated from an uploaded schema, since the schema already specifies this via the minOccurs and maxOccurs attributes.

Password

This property applies only to text controls and other input controls. If you check the Password checkbox, the text the user enters will appear on the form as asterisks (it will be submitted as normal text, however).

Sensitive

This property determines whether the value saved in the submissions repository is hidden when viewed in the frevvo web submissions UI. The value is not currently encrypted in the database. 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. In a future release sensitive field values will be encrypted in the submissions database using an SHA algorithm.

CSS Class

This is the control’s class name that was added to your form's XHTML markup. You can use this CSS class to reference the control in any CSS when customizing themes.

One built-in css class name is 'f-page-break'. If you want to add a page break to the printed view of the form (html, pdf, tiff, etc.), add f-page-break to the control that you want to start at the top of a new page. See printing forms for more details.

Name

Every control has a name. The name is automatically generated and defaults to the control's label minus any spaces and special characters. Spaces and special characters are removed in order to make the name valid for use in rules and, for XML users, this makes the name valid as a xsd schema element name.

If you have two controls with the same label and at the same level, the control's name will automatically be made unique. If you try to edit the name such that it would no longer be unique, frevvo will prevent the edit. In order to use a control in a rule the name must be unique in your form. When a control is dropped inside a section control, it is at a different nesting level then a control dropped outside a section. Also two controls, one inside a section called Car and another in a section called Boat are also at different nesting levels. In both cases the form designer will allow you to name the controls the same. For example both Car and Boat can contain a control named VIN.

The Name property is instrumental in several usages within frevvo:

• Name is how you refer to your control in Rules.
• Name is also used when initializing form fields via the frevvo _data URL parameter for controls added from the palette. Note: For controls added from XSD schema, you must use the underlying element name to initialize the control via _data.
• Name is how you refer to form fields from Document URIs.
• Name is used in Form Action Display Message and Go to URL Templates.
• Name is used in Doc Action Email Address Templates.
• This is the name given to the XML element corresponding to the control you drag into your form from the palette.

You can change the Name of controls from schema, although schema controls maintain their underlying XSD element name. For example, suppose you are using controls from two schemas in a form and both contain a control named FName. You could change the name of one of these controls to FirstName to make them unique within the form. This is helpful if you're adding rules to the form, or if you want to use the form as a template.

Except for _data, controls from XSD use the same rules (as above) as controls from palette.

Printable

This property determines whether or not this form field will appear in the HTML print view of the form and in the PDF document view. If unchecked, the field will not appear in either view.

You can set the property on a section control and it will automatically apply to all controls inside the section control. This is often used in business rules. See Show/Hide/Print.

Enable if Valid

This property applies only to Submit controls. By default frevvo 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 frevvo's default behavior and allow the user to submit a form even if it is invalid. To do this, uncheck this property.

Control Style Properties

To access a control’s style properties, click on the control in your form, then click the Style tab in the Forms Designer’s Property area.

Some controls have more style properties than others, so the specific style properties you see depend on which control you click in your form. As you define style properties for individual controls, remember that these will override any form-level properties you have defined.

Each control style property is described below. For more complex styling consider customizing a theme.

Width

Most controls have a width property. For input controls, the property specifies the width of the area in which users enter data; for example, you might narrow a control used for entering zip codes or widen a control for a full first, middle, and last name. A common example is setting a text control's width to 90% for street addresses when you use the text control inside a panel as part of a two-column layout. (When a control is inside a panel or other grouping control, the width percentage is relative to the grouping control. When a control is not inside a grouping control, the width percentage is relative to the entire form.)

This property is crucial for panel controls because you must adjust the panel widths before your columns will line up side by side. For tab controls, you access the width property by clicking the unlabeled area to the right of the last tab in your tab group; the width you specify will be applied uniformly to each tab in group. (See Panels and Tabs for more details.)

There is no Width property for section or repeat controls; however, you can edit the Width property of controls you drag inside these controls. Also, if you drag a section or repeat inside other group controls, frevvo automatically adjusts the width to a sensible size.

When setting a control’s width property you may use standard CSS-relative values; for example, 5%, 5em, 5ex or 5px.

Item Width

Radio and Checkbox controls have an extra property called Item Width. You can use this property to change the layout of the options from vertical (one radio/checkbox button below the next) to horizontal. This is useful to save vertical space on long forms. And also useful to improve ease of use for forms with questions that each have the same set of options.

See this image as an example:

Option Width

Radio and Checkbox controls have an extra property called Option Width. This property is useful when you option values are longer than a single line. In some cases this may cause the option value to start below the radio or checkbox on certain browsers. You can correct this by selecting a smaller option width such as 80%.

Here is an example of a checkbox option that spans multiple lines:

In order to adjust the formatting so the option aligns next to the checkbox, option width was set to 80%. This is how the checkbox looks after setting option width:

Margin and Padding

These are two separate style properties, but they are similar and often used together. The margin lets you add extra space around the outside of your control, while the padding permits you to add extra space within your control’s boundary.

In this example below, the controls have margin and padding properties of 30 px (pixels).

Type your margin and padding properties using standard CSS syntax. Type a single value such as 5% to apply a 5% margin or padding uniformly on all four sides of the control.

You also can type specify different margin or padding on the various sides of the control: for example, a 5px 10px 15px 20px margin property will give your control a five-pixel top margin, a ten-pixel right margin, a 15-pixel bottom margin and a 20-pixel left margin.

Background Color

This lets you specify the color that will appear behind the control. Type any valid CSS color name or its hexadecimal RGB equivalent. For example, if you want a red background, you can type the word RED or #aa2211.

Border Width, Border Style and Border Color

These properties let you specify the thickness, format and color of a border around any control. With the exception of sections and repeats, the border is applied only to the area where the user enters data and does not surround the control’s label.

For tab controls, click the unlabeled area to the right of your right-most tab to access the border properties. Your border properties will be applied uniformly to each individual tab in the tab group. You may not apply borders to panels but you may create borders around controls you drag inside panels.

Remember to make the border color property different from the form’s background color or users will not be able to see the borders. Specify the color using the standard CSS convention of typing the name of the color or its hexadecimal equivalent. When specifying the border width property, using pixels (5px, for example) works best.

Label Color and Label Size

These properties give you an easy way to change the font size and color for any specific control on the form. Specify the color by typing any valid CSS color name or its hexadecimal equivalent.

These properties work well when you want your entire label to have the same size and color, but for more sophisticated labels you can type XHMTL in the control’s label property field. For instance, use XHMTL if you want to apply two different font colors inside the same label. Typing XMHTL also gives you more font precision, since the label size property lets you pick generic font sizes only--small, medium, and so on. There may be controls for which you want a font size somewhere between the small and medium options in the dropdown, for example.

Bold

Check this checkbox to make the control's label bold.

Italic

Check this checkbox to italicize the control’s label.

Digital Signatures

Signatures can be added to any form. The granularity is at the section control, so that different parts of the form can be signed by different people rather than a signature being applied only to the entire form.

To add signatures, select any section control on your form and click the Security tab in the properties panel. The Must sign property makes the signature required. With Must sign, a form cannot be submitted or a workflow sent to the next person until the signature is added. Lock sign means that the next person in the workflow can not remove the signature and edit the signed data. A good use case is a employee performance review where the manager starts the form, and signs the review, and sends it to the employee. You would check Lock sign so the employee cannot unsign and edit the data entered by the manager.

frevvo uses public key cryptography. When a frevvo server is first started, it generates a public and a private key. This is automatically generated using the RSA algorithm. There is no official certificate authority (CA); however, if you want one you can supply your own public and private keys that are certified by some authority (like Verisign). An official CA is not required, since the data is signed by frevvo and verified by frevvo using keys generated by frevvo. You must keep the private key "private" by setting up good security practices to the frevvo server's disk. The public key may be shared with anyone and, in fact, if you manage the server as the admin user, and click on Security you can see the public key displayed there.

When a section is signed, the data in the section, together with a time stamp, the signing user, and a few other things are used to generate a message digest. The message digest is digitally signed using the private key. The signatures (there can be more than one) are included with the submission – in the repository and sent in the HTTP POST so you can save it yourself if you want.

When the form is re-initialized from the submission documents, you must also supply the signatures. The initialization process will verify that the data has not changed (i.e., has not been tampered with) and the signature is still valid. If the signature is not valid, it is removed and the entire Section is displayed with a visible error (large red background). If it is valid, there is a green background and the Section cannot be edited.

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.

Undoing Design Changes

The current version of frevvo does not include an “Undo” or “Redo” feature. If you accidentally delete a control, you must re-add it.

Removing a Control

To remove a control, click on it in your form. You’ll see a red X in the right corner of the control; click the X and your control will be deleted immediately. Keep in mind that there is no Undo feature and that deleting a group control automatically will delete all input controls inside it.

As noted earlier, you cannot delete a tab control in one keystroke. You must delete the individual tabs one by one.

Control Templates

A control template is a control that was published by the form designer so that it can be reused in other forms and by other designers within the same tenant. You typically want to publish control templates after you spent hours working on a complex control with sophisticated layouts, field patterns, business rules, etc., and want to avoid redoing the work in another form. You also may consider using control templates when you need to split the work among a number of form designers, where each designer is responsible for creating a subsection of a complex form and another designer is responsible for assembling these control templates into a final form or flow.

Before we go into more detail here, it is important for you to understand the two types of control templates that you can create in frevvo. In some cases may you want to publish a control template and allow them to be completely modified when used in other forms. These modifiable control templates are basically a starting point to a sightly or entirely different control at the discretion of the designer using it. Note that by changing the name of a control, you may break rules published with the control. In other cases, you may want to publish read-only control templates. A designer using a read-only control will not be able to remove nested controls nor change any properties that affect the underlying data binding (e.g., the name property). However, the designer will be able to change other UI-related properties such as styles and labels, and rearrange any nested controls.

In general, if you have rules associated with the control or it is essential to guarantee a consistent XML binding, then you want to publish your controls as read-only.

Another key thing to understand here is that the Custom pane is like a favorite's area for the current designer. So adding control templates to or removing them from the Custom pane is not adding or removing control templates; it is basically adding or removing control templates from the designer's Custom pane. There could be 100's of control templates published by designers in a given tenant, but only 10 of them, e.g., the 10 most used ones, in the Custom pane. In addition, each individual designer will have their own Custom pane with their own set of favorite control templates.

Publishing a Control Template

There are two ways you can publish a control in frevvo:

• Clicking the Publish Control Template link, in the control properties pane, or
• Dragging and dropping the control onto the Custom pane's header

There is small difference between these two ways of publishing controls, though. When clicking the Publish Control Template link, you are only publishing the control as a template, but when you drag & drop you are also adding the published control to the Custom pane, in one shot.

Next, you will see the Publish Control Template dialog where you can enter a name and description for this template, a category, and any number of comma or space-separated tags. See the Manage Control Categories topic for instructions for adding or removing control template categories.

Click Submit and you will see a confirmation page that once closed will refresh the page. If you used the drag & drop approach above, you should see the published control automatically added to your Custom pane.

Publishing Controls with Rules

You can also publish controls that are referenced by rules as long as:

• the control is a Panel or a Section (support for simple controls will be added in the future)
• the rule only references the control being published or any of it's nested controls

When the above conditions are met, the Publish Control Template dialog will list the candidate rules (see next screenshot) allowing you to select the ones you want to publish with the control. Note that as soon as at least one rule is selected the read-only checkbox will also be selected: you can only publish controls with rules in read-only mode. Since it is not possible to edit rules after the control is published, this restriction exists to make sure that no changes that could break the rules will be allowed when using the template.

Adding/Removing Templates to/from the Custom Pane

You can add control templates to the Custom pane by clicking the Search link found there. This will show the Search Control Templates dialog where you can search for the template you are looking for.

This search dialog will show, by default, the first 10 templates ordered by the date when the control was published. You can then page through the templates by clicking Next or Previous.

The search result will show a table with 5 columns:

• Column 1: Include/exclude from Custom pane (checked/unchecked)
• Column 2: Control type icon (Section, text, dropdown, etc)
• Column 3: Template name
• Column 4: Template created date
• Column 5: Template tags (space separated)

You also can get see who created the template and when by hovering over a given row in the results table.

You can add a control to the Custom pane by selecting (checked state) the check box in the first column in the table and remove a control from the Custom pane by deselecting (unchecked state) it. Click Finish when done and you will see an updated Custom pane after a page refresh.

Searching Control Templates

You can also perform simple case-insensitive searches through all the published control templates using the Search Control Templates dialog. Here are some sample searches:

• perso -- searches for all templates that have the sub-string 'perso' in the name, description, tags or categories (case-insensitive, partial matches).
• name:PersonalInfo -- all templates with name containing PersonalInfo (partial match)
• descr:Somewhat -- all templates with description containing Somewhat(partial match)
• author:john -- all templates created by john (exact match)
• tag:personal -- all templates with a tag personal (exact match)
• cat:hr -- all templates with a category named hr (exact match)
• type:Checkbox -- all templates of type Checkbox (exact match, options are: Checkbox, Text, Repeat, Section, Dropdown, Panel, TextArea, Number, Phone, Radio, Tabs, Message, Link, Date, Email, Quantity, Image, Video)

The search will be updated by either clicking the Search Controls button or by tabbing off the search field. You can also perform automatic searches by clicking individual columns in the search results: e.g. clicking on a tag will automatically filter the search by that tag and the search field reflects the new search criteria.

Removing Control Templates

If you want to remove control templates (instead of removing from the Custom pane) from frevvo, you need to make sure you are logged in as the tenant admin and navigate to the Templates > Templates by Category or Templates > Templates by Tags page from the top menu. There you will see the list of published controls and can remove them one by one.

Form & Doc Action Wizards

Wizards make it easier to configure what happens to the data when a user submits your form and what the users see after submitting the form. The wizards are accessible from the form designer toolbar via the one button labeled Form Action and another labeled Doc Action. The action settings are summarized in the form properties form info tab.

Form Action Wizards

The form action wizards configure what users will see when they submit your form.

Using these wizards you can:

• Close the form window
• Display a message to the user in the existing form windows
• Forward to a nicely formatted web page that you have created elsewhere
• Forward to Paypal if your form has sold items to the user
• Post the form data to a service and then forward the user to a web page
• Display a message formatted using a Google Document

The wizards help guide you through the configuration process. Many of the wizards allow you to use form controls as templates to dynamically create what the users sees rather than hard coding this. See the section on using templates in form/error actions for full details.

Close the Window

After the user submits the form, if the form was shared via "Full Page/Popup" or "Link (Email/Web page)", the window containing the form will be closed.

Display Message

After the user submits the form, the browser will display a standard frevvo page with a text message. For example, the message might say, “Thank you for completing our form.” You supply the specific text in the Message field. This option works best for relatively brief messages. It can be tricky to enter or edit large amounts of text in the wizard's Message field, so for verbose messages consider creating a simple HTML page for your message and choosing the Forward User to your Web Page wizard.

The message can be customized, using the wizard's control dropdown, with values the user enters into the form. For example if your form contains a fields named firstName and lastName, you can set your message to "Thank you {firstName} {lastName}". Now when a user submits the form the controls templates {firstName} and {lastName} will automatically be replaced with field values "Thank you Joe Smith". See using templates in form/error actions for full details

Another useful message is to display a link back to the form. For example the display message:

The display message would be written as follows. The URL back to the form is the share dialog Raw Form link.

Thank You!<br/><br/>
{Company}'s account will be created within 24 hours.<br/>
A "A New Account" email will be sent to {Email}.<br/><br/>
<i>RedStone Customer Support</i><br/><br/>
Click <a href="http://test.frevvo.com/frevvo/web/tn/redstone/user/designer/
app/_OLlAYUouEd-0jOS-XMShUg/formtype/_YRsQYEyBEd-OltN4g8wchQ?_method=post
&embed=true&locale=">here</a> to request another demo account.

Note: Javascript is not allowed in the display message. Plain text, html and control templates are allowed. Anything else will break the message and nothing will be displayed.

Show In

Both the display message wizard and the forward to web page wizard allow you to select where the message is displayed on the page using the "Show In" dropdown. There are three choices: Frame, Parent and Top. This tells the browser where to show the text (if you chose Display Message) or the new Web page (if you chose the Forward to Web Page).

• Frame means inside the form's iframe
• Parent means inside the form iframe’s immediate parent
• Top means at the top of the page, regardless of how many parents are outside the iframe.

Forward to Web Page

After the user submits the form, the browser will be redirected to another URL, which you supply in the URL field. You must include the http:// prefix (e.g., http://myhost.com/thankyou.html). The application can have a Form Action Base URL which you set in the application properties. For example, you can have http://myhost.com/ in the application baseURL and simply “thankyou.html” in the Form Action URL field.

Show In

These are the same options as described under the display message wizard above. Unless you have created a special page that you know will fit correctly within the form’s iframe you should not choose iframe. Choose the Parent or Top option instead.

Forward to Paypal

When the form is submitted, users will be forwarded to Paypal to complete payment. This multi-step wizard guides you through configuration:

• Paypal account login
• Paypal invoice description based on form values
• Paypal payment amount from form values

and more...

The frevvo Paypal tutorial can help you get started quickly.

Post Data then Forward to Web Page

After the user submits the form, the browser will POST the user’s data to the URL you specify in the wizard’s URL field and display whatever is returned—the next page to display.

You URL field must include the http:// prefix (e.g., http://myhost.com/services/processPayment). The application can have a Form Action Base URL which you set in the application properties. For example, you can have http://myhost.com/services/ in the application baseURL and simply “processPayment” in the Form Action URL field.

The URL can also include control templates. This can be useful when you wish to specify a production versus a test server. For example: http://{serverURL}/services/processPayment/{customerId}. Using this form URL, you can specify serverURL using &_data=(serverURL:'testhost'). This makes switching from a test server to a production server a matter of setting the form URL parameter "serverURL" rather than editing the form itself. See Testing & Using forms for more details on _data usage.

You have the option of also sending the data as a pdf attachment or other image type using the Send Snapshot dropdown. You can also attach an XML data document using the Send XML checkbox.

Display Message formatted Using a Google Document

As of Live Forms v4, the Google Document wizard is deprecated. The standard Display Message now supports HTML and CSS formatting plus form fields templates to pull any data entered into the form into your email message subject and body.

frevvo Live Forms supports direct connectivity with Google Documents. This wizard allows you to format a display message using an online Google Document.

After the user submits the form, the browser will display a standard frevvo page with text formatted using your google document. This wizards steps you through the process of logging into your google account and locating the document you want to use to format the message. See the frevvo Google Documents connector for details.

Here is an expense report form that shows what you can do using the Google Documents Wizard. Click here to try this form.

frevvo form	formatted display

Error Action Wizards

These wizards optionally allow you to customize what the user sees if an error occurs. You can either display a message or forward users to a web page of your choice. The wizards behave exactly like the corresponding Form Action wizards above.

Using Templates in Form/Doc/Error Actions

The values set in the following wizards can be customized with data from the form:

• Display a message
• Forward users to a web page
• Post data and forward users to a web page

For instance, in the display message, you may wish to display a customized message with the user's name. You can use templates in the display message to do this.

• Make sure you have two controls in the form called FirstName and LastName.
• Click on Form Action
• Click on Display a Message.
• In the Message area of the wizard, type: Thank You {FirstName} {LastName} for submitting my form.
• As a shortcut, you can also select the appropriate control from the drop down immediately below the Message area.
• Click Finish.

Use the form by clicking on the Test button. Enter something into the First Name and Last Name controls. When you click submit, frevvo will display the above message with {FirstName} and {LastName} replaced by the values entered by you.

Templates work the same way when used in URLs for forwarding to a web page or Post data.

When referring to repeat controls you must use a special template syntax. See templates for repeat controls for details

Doc Action Wizards

The doc action wizards configure what happens to the entered data when a user submits your form. See Doc URI Wizards below for details on using the wizards to config the doc URI settings. Please also refer to the processing submissions tutorial.

This wizard has three tab as show in the screen images below:

• Doc Actions
• Additional Email
• Doc URIs

Using these wizards you can:

• Do nothing with the data
• Email the data to an email address
• Post the form data to your web application
• Format and Email the data using a Google Document
• Save the data to a Google Spreadsheet
• Save the data to PaperVision®/ImageSilo®
• Save the data to a Google App Account.

The wizards help guide you through the configuration process. Many of the wizards allow you to use form controls as templates to dynamically configuring wizard parameters hard coding this. For example you can dynamically set the email address to send the data to instead of hard coding an email address. See the section on using templates in doc action/doc URI wizards for full details.

Do Nothing

This is the default option, which simply stores the data in frevvo's submissons repository if desired. (The other options also store the data in the repository if desired, but provide additional functionality.)

Do nothing is typically selected when you plan to do one or more of the following:

• View the submissions using frevvo submission repository
• Save submissions to a Google spreadsheet
• Save submissions to your own database or other backend system using Manual Doc URIs
• Use the form action wizard to post data then forward to your web page

Note: The form's save property controls whether or not your form submission data is also stored in frevvo's submission repository.

Email Data

When the form is submitted, frevvo will send an email message with the submission data, an optional XML document(s) , and optionally a image of the filled form via the Send Snapshot dropdown. The email can be sent to multiple comma separated email addresses. See Email Integration for further details.

The tenant admin can configure the from email address on the tenant admin's Edit Tenant page.

Save to PaperVision® / ImageSilo®

frevvo Live Forms integrates directly with Digitech Systems' PaperVision® and ImageSilo® document management products. This Wizard enables an easy way for you to save form submissions to your PaperVision® and ImageSilo® document management repository as PDF, TIFF, .JPG and .GIF format.

The wizards walks you through simple steps to login to your PaperVision®/ImageSilo® account:

To select the correct PaperVision®/ImageSilo® project where you want to store the form submission:

And finally to map your form fields so that the entered form field values become the index field values for your document.

Now when a users fills and submits your form and image of the form and any uploaded attachments will automatically be stored into the selected PaperVision®/ImageSilo® project. The document's index fields will be set to the values the user entered into the form.

See ImageSilo® integration for ful details.

Save to Google Spreadsheet

Form submission can be saved directly to an online Google spreadsheet. See the documentation for connecting to Google for full details. Also refer to the Google spreadsheet tutorial for step by step instructions.

Save to Google Apps

Form submissions can be saved to your Google Apps Premier account. See the documentation for connecting to Google Apps for full details. Also refer to the leave approval workflow tutorial for step by step instructions.

Post Data

When the form is submitted, frevvo POSTs the document set to the specified URI and ignores any returned XHTML or redirect. This option may be used for additional processing of data. Use form action post if you want to both submit data to your URI and forward to a web page or display returned XHTML.

You have the option of also sending a filled form image using the Send Snapshot dropdown as well as sending an XML attachment containing the form data.

Format & Email Using a Google Document

As of Live Forms v4, the Google Document wizard is deprecated. The standard Email wizard now supports HTML and CSS formatting plus form fields templates to pull an data entered into the form into your email message subject and body.

frevvo Live Forms supports direct connectivity with Google Documents. This wizard allows you to format an email message using an online Google Document.

After the user submits the form, the data will be formatted using your google document and then emailed to the addresses of your choice. The wizard supports multiple comma separated addresses. This wizards steps you through the process of logging into your google account and locating the document you want to use to format the message. See the frevvo Google Documents connector for details.

Here is an example of a form submission that was formatted using a Google document.

Additional Email Wizard

When the form is submitted, frevvo can send an additional email message with the submission data, an optional XML document(s) , and optionally a image of the filled form via the Send Snapshot dropdown. The email can be sent to multiple comma separated email addresses. This is in addition to any document action you may have configured. For example, consider a Vacation Request Approval workflow. When the workflow is complete, we want to send a PDF to the internal HR system (using the document action) but in addition, we want to notify the employee requesting the vacation by email. Use the Additional Email wizard for this scenario.

To use the wizard, click Doc Action in the toolbar at the top of the form and select the Additional Email Tab. See Email Integration for further details on configuring the content of the email.

Doc URI Wizards

The doc URI wizards enables you to manually set a URI to which the data will be sent when your form is submitted. The Google Spreadsheet wizard provides additional assistance in setting up the login to your google account and in selecting the spreadsheet.

Using these wizards you can:

• Unset the document URI - do nothing
• Save Submissons to a Google Spreadsheet
• Manually set document URIs - to connect to database and other backend systems

Unset the Document URI

This is the default option. If one of the other 2 options is set you can clear them by clicking this one.

Save Submission to Google Spreadsheet

frevvo Live Forms supports direct connectivity with Google Spreadsheets. This wizard allows you to save submissions directly into Google Spreadsheets

After the user submits the form, the data will be written into a new row in the Google spreadsheet. This wizards steps you through the process of logging into your google account and locating the spreadsheet you where you want to save the submissions. See the frevvo Google Spreadsheets connector for details.

Here is an example Google spreadsheet that is updated with a new row each time the frevvo form is submitted.

Manually set Document URIs

For an example of using Document URIs, see the chapter Integrating with REST applications and also the chapter on connecting to your database.

Using Templates in Doc Action/Doc URI Wizards

The values/entries in all doc action/doc URI wizards can be customized with data entered in the form using templates. Templates work the same way when used in Form/Error action wizards as documented above.

Editing Form Properties

At the top of the Forms Work Area click the toolbar (where you see the Finish and Cancel buttons) to access the form’s properties,which are shown in the lower-left portion for the Forms Designer. Forms have Settings, Style and Form Info tabs.

Form Settings Properties

Each form setting property is described below.

Form Name

This is the name you see on the Forms home page where your forms are listed. We recommend changing the name to make it more meaningful than the arbitrary name assigned when you create it, but keep in mind it is a working name only, so users will not see it.

Description

By default all form descriptions say, “Edit the form to change this description,” but you can change this if you wish. The description appears as a tooltip when you mouse over the area just to the right of the form’s share icon on Forms home page. You also see this description when you view individual submission documents.

Visibility

This field provides access control for the form. If you select Private, only you (the owner) can edit, test or use it. Select Public in Tenant to allow anyone who has an account (username/password) and is logged in to your tenant access to use the form. Select Public to allow anyone to use it even if they are not logged in. Note that irrespective of the Visibility setting only the owner can edit or remove the form.

Deployment

This field lets you toggle a form between two states: PRODUCTION and DEVELOPMENT. When a form is in development state it contains a watermark. Deploying the form into the production state removes the watermark.

Use this field to toggle between production and development. Forms can also be deployed/undeployed via button on the forms home page.

See managing production forms for more information.

Task Info

When you save a partially filled form to continue it later, the saved form is accessed via your task list. This field controls the name that gets displayed in the task list. For more details, see the Tasks documentation. This field can use templatized strings for dynamic content, e.g. the Task Info can contain "Vacation Request for {FirstName} {LastName}" where FirstName and LastName are the names of fields in a form. Before putting the task on your task list, frevvo will resolve the Task Info string using the actual values of the FirstName and LastName fields e.g. "Vacation Request for Tom Smith".

You access your Task list from your applications home page. You use the Task list to perform tasks, complete a saved form or work flow, to view a task's history, or search for tasks you've participated in — a tenant admin can also search for other users' tasks.

Tracking Id

When your form loads it will send a page view event to your Google Analytics account if you enter your Google account tracking ID into this form property. Please refer to the Google documentation for finding you Google Analytics tracking ID.

Setup Key/Saved Fields

This setting controls which fields are saved to the built-in submissions repository. By default, all your data is saved as an XML document. This is the most efficient way to store/access your data both in terms of speed as well as storage. However, if you prefer to view your data via the submissions user interface, you can choose which fields are saved in addition to the XML data. See submissions data for more information on making this choice. Note that this could incur significant performance overhead and will also consume additional storage in the repository.

Clicking on the link displays a wizard. Your wizard will display the fields from your form.

Saved Fields

You may select the fields you want saved separately in addition to the XML. The fields you select will be displayed in the Submission Detail for each submission. You can also search the submissions repository for these fields using the frevvo API.

Key Fields

Click the Key Fields tab. Up to five key fields may be efficiently stored along with the form submission. Key fields do not significantly reduce performance nor do they consume significant additional storage in the repository. It is also very efficient to search the submissions repository using these key fields. Key fields are also directly displayed in the Submissions Table so you can easily view them in a tabular view.

Watch a video on how to setup key/saved fields.

Error Page

If you supply a Url in this property field, frevvo will display this page whenever it fails to load a default document from one of the form's Document URI Read methods and also when it fails on a document URI Write method. If this field is not set a default error page will be displayed.

Printable

If you check a form's printable checkbox a print icon will be displayed at the top of your form. If you don’t want users to print your form, uncheck the checkbox so users will not see the print icon. You can control which form fields are visible in html print view via the printable property on each field in your form.

Save

This property is checked by default. When check all submissions for this form will be stored in frevvo's submission repository. If you uncheck the checkbox, the form submission will still be logged in the submission repository and you will be able to view the metadata about the submission (time/date submitted, success/failure conditions, etc...) but NO form field data is saved.

The submissions repository can store your form data in three ways -- as data values; as an xml document; and as a pdf form image. By default for efficiency, data is only stored as xml. If you plan to export your form data to an Excel spreadsheet or plan to view your form data in the submission repository detail view, you must configure your form to save the data field values. See the documentation for setting up key/saved fields. Also see the documentation for viewing your data in frevvo's submission repository

Save PDF

This property can only be check if you have the save property checked. When checked a PDF image of the file is also saved in frevvo's submission repository. See the documentation for the submissions repository for details on viewing the PDFs saved there.

Show Logo

This property is checked by default and causes the “powered by frevvo” logo to appear on your form. Uncheck the checkbox to remove the logo from your form.

Captcha

This feature helps to protect your forms against spamming by automatic submitters. By selecting captcha, an image is displayed when a user submits your form, containing a string and also an audio recording. The user must enter the string into the specified input box. If the string is correctly reproduced, the form submission will be processed as usual. If it is not a new string is displayed and the user may try again.

Save/Load

This feature is only available to users with tenant accounts. If you check this checkbox a save icon icon will be displayed at the top of your form. If you don’t want users to be able to save/load your form, uncheck the checkbox so users will not see this icon.

This feature is useful for lengthy forms where your users may not have all the information required to complete the form in a single session. By clicking on save a copy of the form with all the current values is saved on the frevvo Form Server. Later the user can re-open the form from their task list; see Perform a Task for more information.. The form will populate the fields from the saved values.

Users can repeat the save/load steps as many times as they wish.

See the Save/Load feature, for full details.

Show in History

If this checkbox is unchecked, tasks for the form or flow will not appear in Task History searches. If you want them to appear, make sure this box is checked. Checking or Un-checking it affects all tasks including ones that were created prior to the action.

Force Auth

If this is checked and the frevvo tenant supports SSO (single sign on) such as the LDAP Security Manager enabled tenants, then the frevvo authentication mechanism will be in effect even when a user is already authenticated via SSO.

For example, if you leave force auth unchecked and your form is public in tenant, and you are already authenticated via SSO you will not have to login directly to frevvo to use the form. If instead you check force auth frevvo will force you to login directly even though you are already authenticated via SSO.

See Working with LDAP and Single Sign On for more details.

This property is currently ineffective for tenants with the default delegating security manager. However the delegating security manager may support SSO in the future.

Form Style Properties

Each setting property is described below.

Width

This specifies how wide your form will be. The default “regular” width is 600px, but the dropdown also includes thin (400px) and wide (800px). You also may pick the custom option; this will enable the box to the right of the Width dropdown and let you specify your own width.

Height

This property specifies an initial height for your form as it is loading into the browser. It does not dictate the actual height. You typically do not have to edit your form’s height property since the form can resize dynamically. However if your form is very small it can improve the appearance as your form loads if you set height to the actual height of your form.

See Embedding and Using Forms for details on configuring the actual form height.

Controls

This property applies whether the options you define for checkbox and radio controls will be displayed vertically or horizontally. In the current version the property is always to set to vertical and cannot be changed.

Theme

You can choose a theme to alter the appearance of your form. frevvo provides two global themes : Clear or Professional Blue. The Clear theme gives your form a clear (white) background and the Professional Blue gives your form a soft blue background.

Of course, you may create a custom theme instead of using the default themes. After you have added the customized them it will appear in the dropdown list along with the pre-defined options.

Font Name, Font Size and Font Color

Your form’s font name, size and color properties will be applied to all labels and text on your form. You can override these properties for a particular control by editing the control’s properties.

When you create a form from scratch these properties are blank; the specific font, size and color of the labels and text in your form will depend on the theme you have chosen or the template you used when you created the form. Simply supply values in any of the three font property fields to change the form defaults.

Form Info Properties

The form info tab summarizes the settings selected and configured via the form and doc action wizards.

• What users will see? depends on the form action wizard configuration
• What happens to my data? depends on the doc action wizard configurations
• Doc URI settings depends on the doc URI wizard configurations

Templatized Strings

Templates are like variables in your form that will be replaced with the actual values users enter into the form during use. Templates make your form feel more interactive and are useful in summarizing information in collapsed section controls. Templates can be used in the form designer in the following control properties:

• Labels
• Hints
• Help
• Error Msg

Templates can also be used in:

• Business Rules
• Form Actions
• Doc Actions
• Display Messages
• Email Action
• Form Url Parameters _data

See the sections on integration, Testing & Using forms and Url Template Variables for more details on these other uses.

Templates have the syntax: {<control name>}. For example, this form contains three controls labeled "Apples", "Oranges" and "Pears". The controls are named "Q1", "Q2" and "Q3" respectively and would be referenced in a template as {Q1}, {Q2} and {Q3}.

Templates can have default values. The syntax is {<control name>=<default>} For example, this form also contains a controls labeled "Total Items in Cart" which is named "T". A template {T=0} would resolved to the value "0" when the field named T is empty otherwise it would resolve to the entered value.

The Shopping Cart section control contains templates its Label, Hint and Help.

The Help property contains this text:

You have {T} items in your cart.<br/>
{Q1=0} Apples<br/>
{Q2=0} Oranges<br/>
{Q3=0} Pears

Before the user starts entering values into this form they will see:

As a user begins entering values into the form fields, the templates will immediately begin appearing, and the user will see:

Repeat Controls

The template syntax is extended for controls inside repeats. The name of the repeating control must be proceeded with the '|' character. For example if you have a control name Phone inside a repeat, the template must be written as {|Phone}. The result of this template is to output the list of all phone numbers items entered into the form.

The syntax also allows for a optional separator. If you would like to get the list of phone number items separated by ", " (comma and space), use the following template: {, |Phone}. Other examples are {|Phone}, {,|Phone}, { |Phone}. The 1st template lists all the entered phone numbers with no separator. The 2nd uses a comma and the 3rd a space. If you used these three in a form's Doc Action Display Message and two phone numbers were entered 203.208.3117 and 203.208.3118 you would see this output for those three templates:

203.208.3117203.208.3118

203.208.3117,203.208.3118

203.208.3117 203.208.3118

Another examples is {<br/> |Names} for a control named Names inside a repeat you would see the output:

Joe
Nancy
James

Repeat Item Labels

It is very useful to use templates with repeat controls. Imagine a long list of medications that appear on the form in a collapsed state. It is helpful if the section labels are not simply a static text such as "Medication" but rather dynamic and indicative of the values entered into the form.

Backspace Key

Unless you are editing text in a property field or inside an input control, clicking the backspace key will cause you to jump to the frevvo home page. Just click your browser’s Forward button to return to where you were. You will not lose any changes if you were in the middle of editing a form.

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.

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. Your form is not clickable in preview mode. To interact with the form use the Test feature.

Click the button to preview your form.