V2.0 Using Forms
From Frevvodocs
Contents |
Using Forms
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 and make it available by sharing it. See below.
Submitting forms
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 exact 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.
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.
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 XML 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.
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.
- 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."
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 v2.0 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 v2.0 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 |
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.
