Using forms
From Frevvodocs
If you have upgraded to Live Forms v2 please see the v2.x documentation.
Contents |
Using Forms
Use Mode
You can use your forms within the frevvo application. This is for testing purposes. Click the forms link in the navigation menu on the upper right hand side. You will be taken to the Forms page for that application. This page lists the forms that you have created in this application. Click on the 
icon next to a form's name to use it. frevvo will display the form in Use mode. In this mode, the form is displayed within the frevvo application framework. The frevvo header and footer are visible.
In this mode, the form is fully functional. You may enter values in the form, submit the form and it will behave as if it was a real user submitting the form. When your form is ready for external use, you must publish the form by marking it as public and use it in embedded mode as described in Embedded forms in the chapter on integration.
When a user enters a value in a field, frevvo automatically dispatches an asynchronous request to the server. The entered value is instantly validated, any relevant rules are applied and the changes are immediately propagated back to the browser. This may cause one or more controls to visually change their appearance, may cause controls to appear or disappear, or become enabled/disabled depending on the current state of the form as computed by the frevvo server. While this is happening, the user is entering values into the next control and is completely unaware of and unaffected by this underlying communication with the server.
Further, in use mode, the user cannot submit an invalid form. The Submit button is dynamically enabled or disabled depending on the current state of the form. This is discussed in more detail below.
This instantaneous feedback is one of the most appealing features of frevvo and breaks the annoying, normal cycle of form usage where the user fills in a set of values, clicks submit, waits for the server to validate the data and is then presented with any error information.
Submitting forms
What happens when your form is submitted? This depends on the selections you choose in the form's properties for Form Action and Doc Action. The Form Builder section describes these properties in detail. By default when a user fills in your form and clicks the submit button the xml document representing the values entered by the user is submitted to the frevvo server and saved in the document repository. And the user's browser navigates to a page displaying the default message "Your form has been submitted."
Embedding forms
In order to use forms, you can access them using URIs as shown in the table below:
| URI | Method | Description |
|---|---|---|
| .../formtype/{formtype.id} | POST | Create a new form instance |
| .../form/{form.id} | GET | Get form (XHTML) |
| .../form/{form.id} | POST | Submit form |
In practice, many users will want to embed frevvo forms in their own web site. The chapter on integration discusses integrating frevvo with your web applications including adding forms to your web page as well as integrating forms with your web application.
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 border.
When the user enters a valid value in the control, the submit button will automatically get enabled. 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 Age and Weight fields but the form may be submitted. However, if the user enters an invalid value in one of the fields, the submit button will again be disabled by frevvo.
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 of the section or the tab by an 
icon. This icon is only displayed for a section/repeat that is collapsed or for a tab that is not selected.
Optional sections
Optional sections can cause the validity of a form to change dynamically. For example, consider the following form:
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.
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.
