V3.0 Using Forms

From Frevvodocs

frevvo Live Forms™ v3.0

Contents 1 Testing and Using Forms 1.1 Testing Forms 1.2 Submitting forms 1.3 Making a Form Public 1.4 Sharing Forms 1.5 Using forms 1.5.1 Default field values 1.5.2 _extId URL Param 1.5.3 _data URL Param 1.5.4 _formActionUrl and _formActionTarget URL Params 1.6 Multi page forms 1.6.1 Go To Url 1.6.2 Post and XML Documents 1.6.3 Url Parameters 1.7 Save/Load 1.8 Valid forms 1.8.1 Optional sections 1.8.2 Input Validation 1.9 XML document management

Testing and 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 via the icon 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."

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.

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
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 using REST Services in rules and Setting default values in rules.

_extId URL Param

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.

_data URL Param

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)

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
• &_data=(A:good,B:!(one,two)!) sets A to good and expects to find two controls named B (a repeat) and sets them to one and two.

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.

_formActionUrl and _formActionTarget URL Params

The Form Action can be overridden by using these two special (reserverd) URL parameter. The presence of _formActionUrl overrides any Form Action set for the form in the Form Designer, and set the action to be Go To Url. And at the same time it specifies which Url to go to when the form gets submitted.

_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:

../../../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 Parameters

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.

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.

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

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.