V4 Using Forms

frevvo Live Forms™ v4

Testing and Using Flows

Testing and using flows is much like testing and using forms. Please refer to the forms chapter below for the bulk of information on this topic. Only the difference are detailed in the chapter Testing and Using Flows.

Common Issues

Why isn't the task appearing on a users's tasks list?

See suggestions in the Tasks chapter.

Testing Forms

When you click Test icon frevvo will display your form in “Use Mode”—in other words, the form will appear and behave exactly as it will when users access it. To test the form, just complete it as your users would and click Submit.

Each time you supply a value in a control, frevvo sends an asynchronous request to the server to validate the data. This means users do not have to complete the entire form before discovering data was entered incorrectly—try to type letters in a number control, for example, and you’ll immediately see an error message. And, if your form includes rules that are associated with a particular control, the server will apply these rules as soon as users enter data in the control. For example, perhaps your form has a rule that enables the “Guest Name” control when you select the Yes radio button in the “Are You Bringing a Guest?” control. In this case the Guest Name control will be enabled immediately--while you are still completing the form!

Any time you or your users access a form, the Submit button will be disabled until valid data has been supplied in all required fields. The Submit button also will be disabled if you supply invalid data in a field that is not required.

When you are done testing and are ready to roll out your form, mark it public via the icon and make it available by sharing it. See below.

Forms can be translated to multiple languages using the Internationalization feature which enables you to easily localize your forms for target audiences that vary in culture, region and language. The translation files you create and upload into frevvo are selected when testing and using forms via the Url parameter _locale. If this parameter is not set on the form Url or if it is empty then it defaults to the language you used when designing your form. In order to initialize the form with other languages, set _locale to the language string you want. See Multi Language Support for details on creating translations and testing locale translations for information on the _locale=<codes>.

Making a Form Public

The Visibility of a form is controlled by clicking the icon. This icon functions as a 3-way toggle. The icon tells you that your form is a private, meaning only you (the owner of the form) can edit, test or use it. Clicking this icon once will change it to this icon and make the form usable by anyone who has an account (username/password) and is logged in to your tenant. Clicking the icon again will change it to this icon and make the form public so anyone can use it even if they are not logged in. If the form is public, clicking the icon will make it private.

The visibility can also be changed directly in the form designer using the form visibility property as shown below. When frevvo is embedded in another product such as Live Forms for Confluence embeds the form designer in Atlassian's Confluence wiki product, this method of setting visibility is the approach as you do not have access to the icons described above.

You can publish any form regardless of whether it is public or private, but if it is private, only the person who created it can edit it or test it. Another user may log in using your ID and password, however, so it is possible to collaborate on a form without sharing it, as long as two of you not editing the same form at the same time. Two or more people may test the form and view submissions at the same time.

Similarly, if a form is public in tenant, only users with accounts in the tenant will be able to access the form.

NOTE: Until you make your form public all other users will see this error message when they try to access the form: "The requested resource is private. You must login as the owner to access it."

A form made public this way is accessible to anyone with the form's Url. There are other methods of sharing forms that have increasingly higher levels of security. See form security for details.

If you have made your form public and users have begun submitting it, you'll need to use caution when modifying your form. If users access it while you are editing it, they will see error messages indicating that the page is being refreshed or that the form is invalid.

You can mark your form private until you are done updating it, which will prevent new users from accessing the form, but if users happen to be completing the form when you switch it from public to private, they will see error messages. For Professional Edition users a better approach if feasible is to edit the form in a copy of your application running on a staging server. You can then replace the current form with the new form by removing the original application from the staging server and uploading the new application.

Submitting forms

Form submissions can easily be integrated with real business applications. When a users fills in and submits your form, the form can be configured to:

• Send the submission to your email address
• Store submission in frevvo's built-in submissions repository
• View the submissions in the repository
• Export the submissions into a Microsoft Excel Spreadsheet
• Store the submissions in a Google spreadsheet.
• Send the submissions via HTTP to a database connector (provided free by frevvo) that can read/write/update your database
• Send the submissions via HTTP to an endpoint of your choice - the data is available as standard name-value pairs or XML documents

When your form is submitted an xml document with the user's data is submitted to the frevvo server and saved in the document repository. The behavior the user sees, however, depends on the form properties you have defined--specifically, the form action property and the doc action property. See Form Properties for details.

Using forms

As forms are used, the values entered into form fields are cached on the frevvo Form Server until the form is submitted. Each time you navigate a browser to a form URL, for example the URL you can copy/paste into a browser from the Link (Email/Web Page) share choice, you will see a blank form. That is, the form fields will be blank if you left them blank when you were designing the form in the Form Designer, or will have any default values you entered into the Form Designer. Also the form fields may contain values from you back-end systems if you used the Advanced Document URI feature.

If you close your browser window/tab and again open the form via the share URL, you will again get a blank form.

Another approach for minor changes is to make a copy of the form, make your changes in the copy, then migrate the changes to the original form. This minimizes the time period during which users may experience error conditions.

Making Forms Public

The Visibility setting in a form's Properties determines who can see and use a form, and whether other frevvo users can access your forms. You can set this property in the Forms Designer or on the Forms home page.

In the Designer, click the Visibility drop-down in the Properties panel and select the setting you want.

• Private means that the form is private; only you (the owner) can edit, test, or use it.
• Public means that the form is usable by anyone even if they are not logged in to the tenant.
• Public in Tenant means that the form is usable by anyone who has a user account and is logged in to the tenant.

On the Forms home page, use these icons to set Visibility.

• makes the form Private.
• makes the form Public
• makes the form Public in Tenant.

These icons function as a 3-way toggle; clicking changes the setting and the icon to the next state.

Sharing Forms

When you click the icon to share your form, you’ll see a Share Form page with five different options at the right. Three options (Embedded Form, Full Page/Pop Up and Just the iframe) are different ways to let users submit the form from your Web page without having to navigate elsewhere. These options have associated code on the left; this is for you to cut and paste into your Web page. Specific instructions for the code also are provided.

Be sure to use the Share icon in the Forms Designer when you want to share a form or add it to a web page. Do not use the browser URL you see when you're running or testing a form — this URL represents an instance of the form, not the actual form itself.

When you run or test a form, you'll notice that the browser URL includes a -extID parameter (for example, .../popupform?embed=true_extId=0.5427066243050674). This means that it's an in-memory instance of the form. You can use the _extID parameter yourself if you want to collaborate with others on an instance of a form. See the _extID topic for more information.

The two Link options give you a link to the form. You can send the link in an email or publish it on your web page.

Each option is discussed below. Remember to make your form public or users won’t be able to access the form no matter which method of sharing you choose.

• Embedded Form – This is the easiest option. Simply copy and paste the code into your web page where you want the form to appear. frevvo takes care of the rest. This option will render the form on your Web page in its entirety, without requiring users to click scroll bars when using the form. You cannot control the height nor the width that the form will use on your web page when embedded in this fashion. The length used by the form automatically resizes as repeats are added and sections expanded/collapsed or made visible/invisible.
• Full Page/Pop Up – This lets users access the form in its own pop-up window so users can complete the form and return to your Web page when they are done.
• Link (Email/Web Page) – This lets you add a link to your form on your Web page or simply email the link to the people whom you want to submit your form.
• Just the iframe – This is similar to the Embedded Form option but requires you to specify your form’s width and height. In fact the script tag is the same except it has different form Url parameters. For instance Just the iframe option does not contain center=true, so the form will not be centered nor have a border. Using this option, the user may see scroll bars when they use your form if you do not specify a height long enough to contain the form when it is fully expanded. (Remember that your form can "grow" from its initial height if users select repeat items, expand sections that are initially collapsed, and so on.) The height and width are form properties but the height property generally is blank since the form sizes dynamically when you design it. There are a number of freeware tools (for example, MeasureIt) that you can use to measure your form’s height.
• Raw Form Link – This lets you email a link to the form just as the Link (Email/Web Page) option does, but it is intended for filling out a form collaboratively and requires coordination between the parties filling out the form. The first person can fill out a portion of the form but must make sure not to submit it. He or she then can copy the URL (which will have been updated to collect the entered data) and mail this updated URL to the next collaborator. When this person accesses the URL, the form will be displayed with the values entered by the previous collaborator. The other difference between this option and the Link (Email/Web Page) option is that this option does not include an iframe border decoration.

Keep in mind that if you have shared your form via one of the link options and subsequently mark your form private, users will see an error message indicating that the "requested resource is private."

Form Security

When you create a new form, by default it is marked as private. At this time the only person who can use the form via any of the form's share choices, is the person logged into this frevvo account. Once you are ready to let others use your form you can mark the form as public. Now anyone that is given the form's Url via any of the form's share choices, has access to use and submit the form.

Private vs public appear to be a binary choice. Either no one has access unless you're logged into the frevvo account or everyone has access without the need to login. frevvo offers other ways of making the form accessible. In all case you will leave the form locked and share it via one of the the following methods:

1. Keyed Access. Given a form key and the form Url from any one of the share choices a person can use the form without logging into frevvo. (This feature is coming soon...)
2. Browser session restricted access. The frevvo API can generate form Urls that are only valid for the current browser session. The form Url generated in this way (not via the Share choices) cannot be passed to anyone outside of the session as it will not work
3. Date expiring access. The frevvo API can generate form Urls that expire after a certain date/time. This is useful for survey type forms where the survey results must be submitted by a certain date/time. (This feature is coming soon...)
4. Instance restricted access. The frevvo API can generate form instance Urls that can only be used/submitted once. After the form instance is submitted it cannot be reused to load a new copy of the form.

Please contact frevvo support for help using these alternate sharing options.

Embedding Forms in Your Website

frevvo forms can easily be added into your existing web site. The option above in the Share section explain the code you need to copy into your web page and the different ways that the forms can be added to your site.

If your web server and frevvo form server are in the same domain (in-house likely scenario), you are able to embed as many frevvo forms into each of your .html web pages as you wish. In order to do this you must give each form a unique id. So if you copy the Share code into the web page a 2nd time, you must edit id to make them different from the 1st copy/paste. Id can be any string as long as it is unique.

<script xmlns="http://www.w3.org/1999/xhtml"
src="http://test.frevvo.com:80/frevvo/web/user/qaforms/app/_-PpqAeCSEdyckfEkZBXSmw/
formtype/_FUC50OCTEdyckfEkZBXSmw/embed?container=true&resize=true&id=form1"
type="text/javascript" language="Javascript"></script>

<script xmlns="http://www.w3.org/1999/xhtml"
src="http://test.frevvo.com:80/frevvo/web/user/qaforms/app/_-PpqAeCSEdyckfEkZBXSmw/
formtype/_FUC50OCTEdyckfEkZBXSmw/embed?container=true&resize=true&id=form2"
type="text/javascript" language="Javascript"></script>

If you experience problems with your web page not resizing correctly to accommodate multiple embedded forms, try setting the height of the form manually. Open the form in the Forms Designer, click the Style tab in the Properties panel, and and type a value in pixels (for example, 720px, 900px, etc.) in the Height field to set the form height.

Currently frevvo does not support the ability to embed multiple frevvo forms in a single .html web page if cross domain. This is the SaaS scenario, where the frevvo form is hosted on www.frevvo.com and your web site is on another domain. In this scenario you currently can only embed a single form into each of your .html web pages.

Default field values

If when you designed your form you left all the form fields blank (empty with no values) in the Form Designer, when you use your form the form will load blank with no default field values. There are several ways to populate your form with default values to assist the user in filling in your form.

In order of precedence, as the form loads (test/use) form fields are potentially populated with default values:

1. Default values entered when the form was created in the Form Designer
2. Values from an XML document(s) sent in the Post request for the form or OnInit.
3. URL parameters appended to the form URL via the frevvo _data URL parameter
4. Values retrieved as the form loads from any Document URIs
5. And finally default values set via Rules as the form loads and during use. See Setting default values in rules and using REST Services in rules for further details.

Url Parameters

You can change the behavior of your forms by adding frevvo Url parameters to the form Urls found in the various share choices. These frevvo Url parameters are each described in detail below. Here are the parameters that work for each share choice. You can think of the code you get via the Share Form page as a starting point. Then you can change the behavior to whatever you need by adding, subtracting and modifying the Url parameters in the share code.

Forms created via the frevvo API createInstance method are form instances. They are an actual form to be used by a specific user in memory on the frevvo Form Server. Please see the frevvo API for a list of the parameters that can be used with form instance Urls.

Raw form link

• edit=(true/false) -- The form will open in the frevvo Form Designer when edit=true and in use mode otherwise. The default is false
• print=(true/false) -- This form will be displayed in print view as if a user had clicked the print icon on the form
• dispose=(true/false) -- The form instance is deleted after the form is rendered in print view.
• _readonly=(true/false) -- The form will open but you not be able to enter values into the form when _readonly=true. The default is false.
• _data -- A way to pass default values into form fields via the form Url. See details below
• _extId -- A way to have multiple users connect to the same form instance. See details below.
• _themeId -- Dynamically select a theme which takes precedence over the theme selected at either the Application or in the Form. See details here
• _formActionUrl -- Override the form's action set in the Form Designer. See _formActionUrl section below. If this parameter is used but equals nothing it will close the window when the form is submitted.
• _formActionMethod=(get/post) -- Overrides the form action's method. Defaults to get. See _formActionMethod section below
• _formActionTarget=(frame/parent/top) -- Override a form action target. Defaults to top. See _formActionTarget section below
• _locale=<locale code> --- This parameter enables you to translate your form into multiple languages. If not set the form displays with the language used in the form designer. If set to one of the locale codes the form displays translated to that language.
• apikey --

Embedded form links -- "Just the iframe" and "Embedded Form"

• All Raw form link parameters
• id -- Use this when embedding multiple forms in the same web page. Each form needs a unique id. Not required for pages with only one form.
• width=(num) -- Sets the initial iframe width. Defaults to 600. Only effective when resize=false.
• height=(num) -- Sets the initial iframe height. Defaults to 600. Only effective when resize=false.
• resize=(true/false) -- Automatically resizes the space (height, width) used by the form when resize=true. Defaults to true. When resize=false the form will remain in the width & height you set and the browser will add horizontal and vertical scrollbars if/when needed.
• container=(true/false) -- Adds a border around the form and centers the form when container=true. Defaults to false.
• center=(true/false) -- This parameter applies to the container so is only effective when container=true. Defaults to true. Set to false to left/top justify the form on the page.
• border=(true/false) -- This parameter applies to the container so is only effective when container=true. Defaults to true. Set to false to remove the border.
• onInit -- A javascript function in scope that will be called before the form is instantiated.
• onSubmit -- A javascript function in scope that will be called after the form is submitted.

Popup form links -- "Full Page Popup" and "Link (Email/Web page)"

• All Raw form link parameters
• All Embedded link parameters

_extId

If you open a new form via, for example, the Link (Email/Web Page) share URL, you will always open a new form. As you use the form and enter values into the form, the values are immediately cached on the Form Server as you tab to the next form field. If you close the browser tab/window containing the form prior to submitting the form, the Form Server still retains this form instance. By using the special (reserverd) URL parameter called _extId, it is possible to reconnect to an in-memory form instance. To utilize this feature, try this example:

• Copy the the Link (Email/Web Page) share URL for one of your forms and append &_extId=123 to a formtype URL. Open that URL in your browser and start filling in a form. Do NOT submit the form.
• Next, open 2nd browser tab or window and use just formtype URL and it will be blank. A new form instance is created.
• Open a 3rd browser tab or window and use the share URL again appended with &extId=123, and you'll get back to the 1st instance.

If you do not use _extId and you click the Refresh button on your browser, the browser will open a new form. This is similar to clicking the Reset button on the form. If you prefer browser refresh to reconnect to the current form instance, use _extId.

_data

Form fields can be initialized directly from the form's HTTP URL. You can do this by using the special (reserverd) URL parameter called _data. Below is an example of a form initialized via _data. The syntax for _data is based on Rison. This form was initialized by appending the following to the URL from the form's Share Raw form link URL.

&_data=(EMail2787:'joe@gmail.com',Name:'Joe',Desc:'Please send details',Q:'20')

NOTE:

While not manditory in all cases it is highly recommended that you enclose the values in single quotes. Thus Name:Joe should be added to the URL instead as Name:'Joe'. Also certain characters may need to be URL encoded. See quoting values below for details. Also note that the only supported format for dates is the XSD schema date format; you must use YYYY-MM-DD.

The form fields are addressed in the _data parameter by their Name property. In the example above the form has 4 controls. The control labeled Email Address has the name EMmail2787. The controls labeled Full Name has the name 'Name'. Description is named Desc and Quantity is named Q. See the Form Designer below with the Quantity control selected and you can see that it's name in the Properties Settings is 'Q'.

Here are some examples:

• &_data=(EMail2787:'joe@gmail.com') sets the value of the control named EMail2787 to joe@gmail.com
• &_data=(A:'good',B:'bad') sets the controls named A and B to good and bad respectively

One common use for _data is in the Form Action Post. You can use URL template variables to set the Url parameter values dynamically from the form field values. One example: imagine your form contains a field named 'custName'. &_data=(fname:'{custName}') sets the value of fname to the value in the form field named custName. If the post is to a frevvo form Url and that next form has a field named 'fname' that field will automatically be initialized to the value of 'custName'.

Quoting values

Values such as 02 are converted to numbers and would actually become a 2 rather than 02. If your form does require an 02 rather than a 2 you can quote the value to prevent this conversion. Thus &_data=(customerId:'02') would set the value of the control named customerId to 02. Whereas if you used &_data=(customerId:02) then the value in customerId would be set to 2.

We highly recommend quoting all values, and it is even more important when using templates because you may not have control over the values users enter into your fields. Thus &_data=(customerId:'{Id}') is preferred over &_data=(customerId:{Id}).

If you are using _data to pass values entered into form 1 to initializes fields in form 2 AND the fields in form 1 are not required (meaning when the form is submitted the fields may not contain values), you must quote the templates. For example if Id is not a required field then this &_data=(customerId:{Id}) will fail when the field has no value. To prevent this failure always use quotes.

Certain character such as % need to be URL encoded. The w3schools.com describes in detail the reason certain characters must be encoded when used in Urls. And also contain a tool that lets you enter your string and converts it to a properly encoded string. For example if your value is '% complete' this must be written as '%25 complete'.

The single and double quote characters themselves must be escaped with the frevvo escape character '!'. For example the string 'Nancy's Horse' must be written as 'Nancy!'s Horse'. If the '!' is missing from the string the apostrophe will be mistaken as the end of string character.

Repeat Controls

Initializing repeats requires a special syntax. :!(<value1>,<value2>,etc..!). In the current release Url Templates variables are not supported for repeats.

• &_data=(A:!(one,two!)) expects to find two controls named B (a repeat) and sets them to one and two.

If _data contains more instance of the repeating item then on the form by default, then it will create new items as the form is loading, as if the user had clicked the "+" button.

This membership list form contain a single default empty member item. The controls First Name and Last Name are named fn and ln respectively.

Appending _data=(fn:!(Joe,Liz!),ln:!(Caprio,Smith!) to the form's share URL will cause the form to automatically add a 2nd repeating member and to initialize the first and last names for both members. This form also contains a templatized label in the section control. Notice how the templates are also replaced with the _data values when the form loads.

Checkbox Controls

In the current release selecting multiple check box options is not supported via _data. Also when using Url templates on the 1st item from the named template will used.

Unbound Controls

Variables passed into your form via _data need not be bound to actual form fields. Since _data is used as a way to initialize form fields why would you want to do this?

One place this is very useful is in business rules. See the section on templatized URIs in business rules for more details. However anywhere that you can use templates in your form: labels, help, hints; display message, etc... the value can either come from the value in an actual form field or from _data values that are not in any way bound to the name of a control.

_formActionUrl, _formActionMethod, _formActionTarget

The Form Action can be overridden by using these special (reserverd) URL parameter. The presence of _formActionUrl overrides any Form Action in the Form Designer by specifying which Url to go to when the form gets submitted.

_formActionMethod is optional and can be set to either "get" or "post". If unspecified it defaults to "get" causing the user to get forwarded to this web page when the form is submitted. If set to "post" it will also post the data to this Url.

_formActionTarget is optional and only taken into account when _formActionUrl is specified. It can be set to one of the values: Frame, Parent, Top. And defaults to Top if not specified.

When the _formActionUrl parameter is set but no Url is given (i.e. ...&_formActionUrl =&embed=...) the top frame will be closed. It is as if you set Form Action to Close" in the Form Designer.

For example... the Url http://www.frevvo.com/....&_formActionUrl=http://www.google.com, will cause the form to display google.com when it's submitted, even if in the Form Designer you had set the Form Action to be "Display Message" or one of the other options.

onInit/onSubmit

onInit and onSubmit are useful when you need to embed a frevvo form in your own form and you want to programmatically submit the frevvo form and initialize the form with your own document.

The value of onInit must be an in scope javascript function. This onInit javascript function will be called before the form is instantiated. For example &onInit=getData will cause frevvo to call the getData() javascript function. The onSubmit function will be called after the submit button is clicked.

Here is a sample html page an embedded frevvo script tag and an onInit javascript function. The frevvo script tag copied was from the Share dialog and the &onInit Url parameter was appended. Each xml document is placed inside a container element (input, textarea or any other element such as a div) and assigned and xml id. In this example there is a single xml document placed inside a <textarea> tag.

<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<script language="JavaScript" type="text/javascript">
			/**
				Called before the form is rendered in the iframe
				Return - docs - [{
						xml: *
					}]
			**/
			function getData(){
				alert('onInit called');
				var textarea = document.getElementById('form');
				return [{
					xml: textarea.value
				}];
			}

			/**
				Called after the form is submitted
				Parameters:
					docs - [{
						element:{
							name: *,
							namespace: *
						},
						xml: *
					}]
			**/
			function onSubmit(docs){
				alert('onSubmit called');
				var textarea = document.getElementById('form');
				if( textarea )
					textarea.value = docs[0].xml;
			}
		</script>
	</head>
	<body>
	    <textarea id="form" name="doc1" rows="4" cols="100">
		<ns:form xmlns:ns="http://www.frevvo.com/schemas/_07IOYMUdEeCuRePmBeMwTQ" name="Order">
		  <Item>
			<Color>Red</Color>
		  </Item>
		  <Item>
			<Color>Blue</Color>
		  </Item>
		  <Item>
			<Color>Red</Color>
		  </Item>
		  <Item>
			<Color>Green</Color>
		  </Item>
		</ns:form>
	    </textarea>

	<script xmlns="http://www.w3.org/1999/xhtml"
src="http://localhost:8082/frevvo/web/tn/nancy.com/user/designer/app/_yVkhYcUdEeCuRePmBeMwTQ/
               formtype/_07IOYMUdEeCuRePmBeMwTQ/embed?container=true&resize=true&onInit=getData" 
type="text/javascript" language="Javascript"></script>

	</body>
</html>

Things to note:

1. The Url parameter &onInit=getData used matches exactly the name of a javascript method in the html page also named getData().
2. The xml data is also embedded in the html page in the <textarea> tag.
3. The <ns:form> content came directly from a prior form submission and was copied out of the frevvo submission repository's Documents tab.

This is how the form looks when initialized via the onInit method. The particular form used in this sample has a repeat control. By default this form has a single repeating item. When frevvo initializes the form with repeating data returned from the getData() method it auto creates the additional items. This form also contained a Item Added Rule which is why there is also a value in the Quantity field.

Multi page forms

Go To Url

You can forward the user from one frevvo form to another by specifying the URI of the second form in the form action for the first. For example, suppose you have two forms in your application. One named formA and the other named formB. When the user clicks the submit button on formA you want them to next see formB. In formA you open the form's edit properties and set the form action to "Go to URL" and in the URL property field you put the URI for formB.

This URI can be found by clicking the Share icon for your form on the Forms Home page.

Here is an example of a form's URI:

http://www.frevvo.com/frevvo/web/tn/{tn.id}/user/designer/app/_DrBPUXM5Ed-glKSGT35lJA/formtype
/_2j2vsJNAEd-Hauq_h2T-4Q?_method=post&embed=true

You can also hard-code the tenant id (../tn/{tn.id}/..).

For portability, we recommend you use relative URIs such as:

frevvo/web/tn/{tn.id}/user/app/_uJKtwbesEduG2Me8fheS4Q/formtype/_18go4Lx7EduG2Me8fheS4Q?_method=POST&embed=true

It is important that both frevvo forms have been made public. If formA is public but formB is not, when the user submits formA they will get a page not found error.

Post and XML Documents

If form A and form B both contain the same data source, and the Form Action in form A is set to Post to the form Url of form B, then form B's fields from schema will be initialized with the values entered into form 1.

This occurs because the Post request to the Form Server contains the XML document(s) from form A. If one data source was added from XSD schema to form A. Then it will contain two documents. The first is the form's from-scratch document containing elements for all controls added from palette. The second is the schema document.

Form B's from schema document is in the same namespace as form A's since we added the same XSD data source to both. So the values entered into form A's fields will be used as an initial instance document to initialize form B's fields.

See default field values to understand the precedence that XML documents sent in the Post request to form B take over the other possible methods of defaulting form field values.

Url Template Variables

Fields in form B can also be initialized with data from form A using Url Parameters. Imagine form A contains a from palette text control labeled 'Customer Name' with Name property set to 'custName'. And form B has a palette text control labeled 'Full Name' with Name properity set to 'fname'. Using either Form Action Go to Url or Post with the URL set to that of Form B, append &_data=(fname:'{custName}') and when form B loads it's 'Full Name' field will be set to the value entered into form A's 'Customer Name' field.

See initializing via _data Url Parameters in the chapter Testing and Using forms for more details on using _data.

Because you many not be in control of what a user enters into a form field used in this way, you should always quote template variables. The only time it is not needed is for numbers but even then it will work with quotes. For example, in the Form Action URL the template variable should have '{name}' quoted as follows: _data=(Name:'{name}').

Read-Only Forms

Any form can be rendored as read-only by appending the form Url with the parameter _readonly=true. In read-only mode, all controls are disabled from entry including dropdowns, repeats, upload controls. And Rules are not executed.

Printing Forms

A form's print view refers to the pdf (or other image types such as tiff, png..) generated with the form is submitted (ex: Pdf attached to an emailed submission) as well as the html print view from a click on the form's printer icon.

You can configure your forms to control which fields are visible in the printed view. This is done via the printable property set in the form designer. Printable is checked by default. If you un-check this property then the control will not appear in the printed view. This property can also be set dynamically via a business rule by setting <control>.printable = [true|false].

Page breaks can be added to the print view by adding the special f-page-break to any control's CSS Class property. Any control with f-page-break will start at the top of new page. In the example below, the Room Information tab prints on a new page.

You can also style your form's print view via a custom theme. This enables you to have one look & feel in use mode and a different look & feel in print mode. See the themes chapter for details and examples.

&format=pdf appended to the URL from clicking on the Print Icon will give you a PDF of the form instance. This can be done manually by first clicking the Print Icon which will open the HTML print view in your browser and then editing that URL by appending a &format=pdf and clicking the browser's go button again. Or you could add a clickable link into your form. To do this:

• Add a message control to your form
• Add the following HTML to your message control
• Escape the '&' in the URL before the format=pdf with & followed by amp;

<center>
<a href="javascript:void(0);" onClick="window.open(document.location.toString().split('?')[0] + '?print=true&format=pdf')">Print PDF</a>
</center>

The same technique above can also be used for forms in workflows. In the case of a workflow the "Print PDF" will print the currently visible workflow step and not the combination of all the steps in the workflow.

Save/Load

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. This feature is enabled via the form's save/load property.

When save/load is enabled, an additional icon is added to the top of the form: . Form users can partially complete the form including leaving required fields blank and even having invalid data in form fields. They click save and the partially competed form is saved on the frevvo Form Server. Later the user can re-open the form either in the same browser or a different browser or even from a different computer, and reload the partially complete form and continue working on it.

• Users load their saved forms from their Task list. See Perform a Task for more information.

When a user clicks save for the 1st time, if they are not already logged into frevvo, an authentication dialog appears asking them to enter their username and password.

Once a user has authenticated a first time they will not have to authenticate again until their browser session expires as a cookie is maintained. If the user clears browser cookies or opens the form in a different browser they will have to re-authenticate.

As a form designer you can also use the save/load feature for testing purposes. Since the frevvo Form Server has already authenticated you when you logged into frevvo, the save/load authentication dialog will never be displayed.

Saved forms are not the same as submitted forms. Saved forms do not appear in the Submissions Repository. Saved forms can contain invalid data and also contain required fields with no values yet entered. When such a form is re-loaded the missing and invalid values are again flagged as such by frevvo. And the form cannot be submitted (the submit button will be grey'd out) until corrections are made to those fields.

Valid forms

One of frevvo's most powerful and useful features is its ability to automatically ensure that any submitted form generates a set of XML documents that are valid with respect to their corresponding XML schemas. The frevvo application does this by:

• always generating valid XML instance documents and
• disabling the submit button for a form which is invalid.

frevvo controls may be marked as required or optional by editing the control in edit mode. Controls that are generated from an uploaded schema will automatically be designated as required or optional depending on the schema (for example, whether the control is required based on the minOccurs value).

When a form is initially created, frevvo will automatically disable the Submit button if there are any required controls that do not contain valid values. Validation for controls you generate from schema elements depends on the element’s XSD type and other schema-specific information.

Any controls with invalid values have a visual indicator. The visual indicator depends on the theme chosen for the application. For example, in the default theme, an invalid control has a red asterisk when a required field is missing a value, and additionally, a red background when a control (either required or not) contains an invalid value.

Here is a form that is missing values in required fields.

Here is the form when the user has entered valid values into the required fields.

And another that has a value in the field but the value is invalid for the given field type.

When the user enters a valid value in the control, the submit button will automatically get enabled. Until that point the submit button remains disabled. This automatically ensures that it is not possible to submit a form with an invalid value.

Note that controls that are optional do not cause the submit button to be disabled unless the value entered is invalid. As the figure above shows, there are no values in the optional Email Address and Phone fields but the form may be submitted. However, if the user enters an invalid value in one of the fields (required or not), the submit button will again be disabled by frevvo.

And here is a form missing values in required fields. Therefore again the submit button in disabled.

When a form has sections or tabs, the submit button may be disabled due to invalid controls that are not currently visible. For example, a section that is collapsed or a tab that is not currently selected may have an invalid control. This is indicated in the header the section and tab label color changing to red.

Optional sections

Optional sections can cause the validity of a form to change dynamically. For example, consider the following form:

(need screen shot)

The only required field in the form is Name and since it contains a valid value, the Submit button is enabled and the form may be submitted. The entire Address section is optional. However, if the user chooses to enter an address, then the entire address is required. If the user enters a value in the Street field, the City, State and Zip fields will become invalid and the Submit button will be disabled until valid values are entered in the three newly required fields.

(need screen shot)

If the user changes his/her mind and removes the value from the Street field, frevvo will recalculate the validity of the form and infer that the Address section is no longer invalid since it is optional. The generated XML instance document will also not contain an address element. Once again, frevvo is automatically ensuring that it is not possible to submit a form that is in an invalid state and that would generate an invalid document.

Input Validation

Form fields added from frevvo's control pallet have built-in validation rules. The table below details the default validation for each control type in frevvo's palette. Patterns added to a control change change the defaults.

Control Type	Default Validation Rule
Text	xsd:string
TextArea	xsd:string
Date	yyyy-mm-dd
Email	[a-zA-Z\-_][a-zA-Z0-9\-_]+(\.[a-zA-Z0-9\-_]+)*@([a-zA-Z0-9\-_]+\.)+[a-zA-Z]{2,6}
Money	xsd:double
Phone	xxx-yyy-zzzz, yyy-zzzz, xxx.yyy.zzzz, yyy.zzzz
Time	hh:mm:ss
Quantity	xsd:integer
Number	xsd:double

Patterns

Patterns imposes additional validation on what users enter in a particular control. See Designing Forms for information on setting a pattern on any control in your form. Patterns are XML schema regular expressions.

NOTE: The one difference between common regex patterns and frevvo patterns is that the latter should not contain a typical leading '^' and trailing '$' characters. These two characters represent the beginning and end of line markers and do not apply to frevvo form field values. Do NOT use these in your patterns.

NOTE: It is important to use a text control for most patterns. This pattern for example requires one of the characters to be a '-'. Used in another control types such as a quantity, this pattern will fail, as a quantity control doesn't not allow non-numeric characters.

US Zip Code Pattern

A pattern that restricts a text control to only allow strings formatted as a US zip code: ##### or #####-####:

\d{5}|\d{5}-\d{4}

The form will flag an error unless the value entered is either five digits or five digits followed by the '-' character followed by 4 digits.

US/Canada Zip/Postal Code Pattern

This pattern validates US zip codes (##### or #####-####) and Canadian postal codes (L#L #L#).

(\d{5}(-\d{4}))|(\d{5})|([ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1} *\d{1}[A-Z]{1}\d{1})

SSN

This pattern ensures that the user enters a valid Social Security Number:

\d{3}-\d{2}-\d{4}

Money

You should not try to apply a pattern to a money control. If you need to apply special behavior to a money control (for example, using three decimal places), we recommend using a text field, which affords a wider range of patterns you can apply. You could also use a number field and apply rules to it — such as rounding up to three decimal places.

Number Range

Patterns for number ranges are not as straight forward as you might imagine. If you want a quantity control allow to only numbers in the range 1-42 it is not sufficient to use the pattern [1-42]. Here is the pattern that will work:

([1-9]|[1-3][0-9]|4[0-2])

Numbers with commas

frevvo's default number control supports digits followed by an optional decimal point and multiple decimal places. Suppose instead you want to allow numbers containing commas and optionally starting with a '$' and only up to 2 decimal places. For example: $1,000.50 2,500. But also to allow numbers without the comma such as $1000. To do this:

• Add a text control to your form
• Set the pattern to: \$?([0-9]{1,3},([0-9]{3},)*[0-9]{3}|[0-9]+)(\.[0-9][0-9])?

If you do not want to allow the optional '$' then:

• Set the pattern to: ([0-9]{1,3},([0-9]{3},)*[0-9]{3}|[0-9]+)(\.[0-9][0-9])?

EMail pattern

If you use Live Forms In-house (downloaded and installed on your computer), you can change frevvo's built-in patterns for the Email control by editing the types.xsd file located in <frevvo installdir>/data/users directory. This file includes the email type definition shown below, and you can edit its pattern value.

	  <xsd:simpleType name="emailType">
		    <xsd:restriction base="xsd:string">
			    <xsd:pattern value="[a-zA-Z0-9\-_][a-zA-Z0-9\-\+_]*(\.[a-zA-Z0-9\-\+_]+)*@([a-zA-Z0-9\-_]+\.)+[a-zA-Z]{2,6}"/>
		    </xsd:restriction>
	  </xsd:simpleType>

Phone pattern

Lets say you would like to change the phone control validation from the frevvo's current built-in pattern to: ##-####-#### or ####-###-###

If you are using Live Forms In-house (downloaded and installed on your computer), you can change frevvo's built-in patterns for the Phone control by:

1. Edit <frevvo installdir>/data/users/types.xsd
   
2. Change the element phoneType as follows:

<xsd:simpleType name="phoneType">
    <xsd:restriction base="xsd:string">
        <xsd:pattern value="\d{2}-\d{4}-\d{4}"/>
        <xsd:pattern value="\d{4}-\d{3}-\d{3}"/>
    </xsd:restriction>
</xsd:simpleType>

Restart your frevvo form server. Now all you phone controls will validate against this pattern.

If you are using Live Forms Online, you will not have access to types.xsd. You can override the pattern in the phone control by setting its pattern property. You can only restrict a built-in pattern (such as the phone control) but not change the pattern via the pattern property. For example you can add the pattern 203-\d{3}-\d{4}. Now all phone numbers must start with area code 203.

A pattern such as ##-####-#### or ####-###-### is not a simple restriction. To impose validation against this pattern you must start with a Text control rather than a Phone control

1. Drag a Text control to your form
2. Add your pattern to the Text control's pattern property: \d{2}-\d{4}-\d{4}|\d{4}-\d{3}-\d{3}
3. Change the error message and help properties to assist the user in understanding the required pattern

XML document management

frevvo automatically manages the set of XML instance documents that are generated by a submitted form to ensure that it is valid with respect to the document types in the form. The validity of values is enforced as described above and in discussion on patterns.

However, frevvo also ensures that the structure of a submitted document conforms to its type. This is best explained with an example. Consider the following schema fragment uploaded to frevvo

<xsd:element name="customer">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="firstname" type="xsd:string"/>
      <xsd:element name="lastname" type="xsd:string"/>
      <xsd:element name="fullname" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:element>

and assume that the user adds the element customer to the form's types. All three elements (firstname, lastname and fullname) are required by the type. But, the form designer is not obligated to add all three controls to the form. Let's say the designer adds controls for firstname and lastname but omits fullname. The form will have two invalid controls when initially loaded and the submit button is disabled.

When the user enters values in both fields, the form can be submitted.

However, this would generate an invalid XML document with respect to the schema since the schema specifies that a customer must also have a fullname. frevvo manages this automatically by creating an empty fullname element in the document. The generated document looks like:

<customer>
  <firstname>Joe</firstname>
  <lastname>Smith</lastname>
  <fullname/>
</customer>

The document will always be valid with respect to the schema.