V3 Using Forms
From Frevvodocs
frevvo Live Forms™ v3
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
When you click the 
icon to make a private form public, the icon will change to this icon: 
. Once you’ve made your form public, you can let other users access it in several different ways; see sharing forms below.
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.
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.
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.
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 allows you to display 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. It also means users 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:
- 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...)
- 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
- 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...)
- 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 way 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>
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:
- Default values entered when the form was created in the Form Designer
- Values from an XML document(s) sent in the Post request for the form
- URL parameters appended to the form URL via the frevvo _data URL parameter
- Values retrieved as the form loads from any Document URIs
- 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.
Initializing Forms with Data
Coming soon...
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
- _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)"
_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.
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.
In v3.3 and prior _data could only initializes repeat items on the form by default. For example in the form designer if your repeating item was displayed only once, then _data for that item only was able to initialize that one item.
In v3.4 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.
In v3.4 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
In Live Forms v3.3 and later 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.
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/user/myUser/app/_uJKtwbesEduG2Me8fheS4Q/
formtype/_18go4Lx7EduG2Me8fheS4Q?_method=POST&embed=true
For portability, we recommend you use relative URIs such as:
For frevvo v3.0 and earlier version:
../../../app/_uJKtwbesEduG2Me8fheS4Q/formtype/_18go4Lx7EduG2Me8fheS4Q?_method=POST&embed=true
For frevvo v3.1 and later version:
frevvo/web/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
HTML Print
PDF Print
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, two additional icons are 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.
When a user clicks save for the 1st time an authentication dialog appears asking them to enter a valid email address and create a password. The user will then use this email address / password pair to re-authenticate to the frevvo Form Server to reload partially complete forms. This ensure that saved forms are secure.
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.
Logout
Logout was added in Live Forms v3.4.2. If you are running an earlier version you will not see this feature. Once authenticated you will see "Logged in as <name>" in the upper right hand corner of the form and a logout icon 
. Logout enables you to have multiple saved forms. This is useful for traveling salesmen and also for saving multiple copies of the same form.
Imagine you have an online mortgage application form used both by self service customers on your website and also by your sales people. Your sales person visits companyA at 9:00am in the morning and begins collecting the information needed to complete the mortgage application. However the customer does not have all the information required to complete the lengthy form so the sales person clicks the save icon intending to complete the form later. The authentication dialog appears and the sales person enters the email address for companyA and completes saving the form. Then the sales person travels to an appointment at companyB at 11:00am. Without the logout feature only one form can be in the saved state. With the logout feature the sales person clicks the logout icon and then clicks the Reset button at the bottom of the form to brings up a new blank form. The sales person begins using the online form to collect mortgage information from companyB. Unfortunately once again this customer does not have all the information required to complete the application. So the sales person clicks the save icon again. Since the sales person had logged out from companyA's form the authentication dialog reappears and the sales person can enter a different name into the email address input for companyB. Later that evening both customers call the sales person with the final information. The sales person can click the load icon and enter the email address for companyA and complete and submit the form. Then clicks logout and then load to enter the email address for companyB and complete and submit companyB's mortgage application.
To test your forms using Save/Load/Logout open up a new browser session in which you are not already logged into frevvo as a designer. When you are logged directly into frevvo designing forms the "logged in as <name>" and logout icon will never appear on the forms that you're testing. This is because you are already logged into frevvo and do not need to authenticate.
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. 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. 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:
(needs v3 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.
(needs v3 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 |
| [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.
US Zipcode 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}
For validation will permit values entered into this field only if they are five digits or five digits followed by the '-' character followed by 4 digits.
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])?
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:
- Edit <frevvo installdir>/data/users/types.xsd
- 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
- Drag a Text control to your form
- Add your pattern to the Text control's pattern property: \d{2}-\d{4}-\d{4}|\d{4}-\d{3}-\d{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.
