Integration

From Frevvodocs

If you have upgraded to Live Forms v2 please see the v2.x documentation.

Contents 1 Integration 1.1 Adding Forms to your web page 1.2 Integrating with REST applications 1.2.1 Document URIs 1.2.2 Customer Example 1.3 Form and Document Actions 1.3.1 Form Action 1.3.2 Document Action 1.4 Email Integration 1.5 Integrating with your database 1.6 Integrating with web services 1.7 Multi page forms

Integration

Adding Forms to your web page

To access your form outside of the frevvo application container, you will first need to mark the form public. Unless the form is marked as public, it can only be accessed by the owner (the user who created the form).

You can easily add frevvo forms to your blog, web site or web application - there are several options for doing so:

1. Embed the form in an iframe: This is an easy and convenient way to add a form to your site. The form itself is still hosted on frevvo’s site so any changes or updates are automatically reflected on your site. For your users, the form will look like it’s part of your own web page. The main disadvantage is scrolling: if your form has repeating items or collapsible sections the height is not fixed so a scrollbar may appear next to your form if it is too long to fit in the iframe. Another potential issue to be aware of is SSL encrypted forms. The browser will NOT show the secure site padlock if the containing web page is not using SSL even if the embedded form is using SSL and is secure. You can find the HTML for embedding the form in an iframe by clicking the Embed button for your form. This displays a dialog box from which you can copy and paste the necessary HTML. Note that you will probably need to alter the height and width to fit the requirements for your form.
2. Pop-up form: This is also easy and convenient – your web page simply contains a link. When the user clicks on the link, it opens a new window that contains your form. The form itself is still hosted on frevvo’s site so any changes or updates are automatically reflected on your site. This is a particularly good choice when using SSL encrypted forms since the pop-up window will show the secure site padlock icon. Once again, click the Embed button for your form. This displays a dialog box from which you can copy and paste the HTML for a pop-up form.
3. Direct link: This is simply a direct link to the form. You can use it to open the form if you don’t have a website or cannot modify it or if you simply want to create a form and email links to the form. Again, the form is hosted on frevvo’s site so any changes or updates are automatically available. Once again, click the Embed button for your form. This displays a dialog box from which you can copy and paste the required link into your email.
4. Direct embedding: This is for advanced users with a knowledge of HTML. This option copies the HTML code for your form directly into your web page. You can edit and customize it if you want. Since the form is no longer hosted on frevvo’s site, any changes or updates are not reflected automatically. We’re working on this and it’ll be available soon.

Note that you can also embed using an HTML frameset (similar to #1) but these are considered outdated and a bad idea. One of the main reasons is that they make it much harder for search engines to index your site. But, if you need to use them, it’s very easy to embed a frevvo form. Just point the src=”" of the frame to the same URL as the iframe.

Integrating with REST applications

From the point of view of the user interface, most web applications can be thought of simply as CRUD (Create, Retrieve, Update & Delete) operations on documents. In the diagram below, the form is being used to initially display a Customer and Order and then to update them. If you think in REST terms, the form is a View Resource that composes multiple Entity Resources (in this case a Customer Resource and an Order Resource), displays their current state and allows you to update them.

frevvo provides a very flexible and powerful mechanism for interacting with documents (and the web in general). You can download source code and forms for the discussion below. We strongly recommend that you download the example, study it and use it as a template for integrating with your own web applications.

Document URIs

For each Document Type that you add to your form, frevvo permits you to assign

• a document URI Template resolved either using query parameters or form fields.
• a Read method and
• a Write method.

This is best described using several examples. Consider the example above. Here are the interactions a Customer Resource supports:

Resource	Method	Description	Returns
Customer List	GET	List of customers (may be criteria based)	XML list of customers
Customer List	POST	Create new customer	URI of newly created customer
Customer	GET	Get customer data	XML representation of cutsomer
Customer	PUT	Update customer
Customer	DELETE	Remove customer

Updating a document

Consider the case where a form is used to update a particular customer. To create the form:

1. Upload your customer schema to the designer, add the customer element to the document types for the form and add the customer to the form (which automatically generates controls). See the section on Adding Controls from Schema for further details.
2. Drag/drop, change labels etc. directly in the browser
3. Specify URI template .../customers/{customer}, choose Read Method GET and Write Method PUT
4. Specify a Form Action URI if desired (we'll get to this later).

That's it. As usual, you access the form using its URI. When the form is used (instantiated), you may specify one or more query parameters along with the URI. For this example, we might use a URI and query parameter: .../form/1234?customer=02. frevvo will resolve the URI template above to: .../customers/02, GET the customer, and display the initialized form. When the form is submitted, frevvo will automatically PUT the customer document to the same URI thereby updating the customer. The diagram below shows the interactions. Here's an example form that uses the Customer entity described above. In the example:

1. We instantiate the form with a parameter customer=02. This causes the form to resolve the URI template and GET the customer data from: http://[server]/customers/02. The resulting XML document provides the initial state of the Customer and is used to initialize the form.
2. Modify a value and click Submit. The form will automatically PUT to the correct resource and update the customer information.
3. Finally, frevvo will store the generated document set and assign it a unique URI. The document set and the documents therein can be accessed at this URI.

Creating a new document

Consider the case where a form is used to create a new customer. Follow the same steps above, except use the appropriate URI template .../customers and change the Read method to POST. That's it. As usual, you access the form using its URI. When the form is used (instantiated), frevvo will perform the POST and create the customer. It will then follow the server redirect (to the URI of the newly customer) and display the form. When the user enters customer information and submits the form, frevvo will automatically PUT the resulting XML document to the URI of the newly created customer resource thereby updating it. The diagram below shows the interactions:

Here is an example form that creates a new customer using this method.

Dynamic documents

A document URI template can also be linked to a form control. To do this, use the Control Type ID. Consider the Updating a document example above and the sample form therein.

The form has a Customer document and we have specified URI template .../customers/{customer} and Read method GET. In this form, there is a control which has Type ID 'customer' as shown in the figure below.

If you enter a value in this control, frevvo will automatically resolve the URI template using the new value and attempt to GET a new document. If it succeeds, the form will be initialized with the new document and all relevant control values will automatically update. In the example above, try changing the value to 03 or 04. Notice how the customer information fields change to reflect the new document that is being edited by the form.

If you enter an ID that does not exist, the GET will fail (return an empty document or a 404 HTTP status code). In this case, frevvo will automatically revert back to the default document with default values as specified by the designer.

In either case, if you modify/fill in fields and submit the form, it will PUT (since we chose PUT as the Write Method, the form will send an HTTP PUT) the resulting XML document to the resolved URI.

For example, if you enter ID 03, frevvo will GET .../customers/03, display the form with fields initialized from the returned XML document and PUT the modified XML document to the same URI when the form is submitted. This PUT will update the customer with ID 03.

If you enter ID 99 (which does not exist), frevvo will GET .../customers/99, which returns an empty document. The form will be displayed with default values (as entered originally by the designer). When submitted, the resulting XML document will be PUT to .../customers/99. This PUT will create a new customer with ID 99 (the behaviour depends on the implementation on the server - in our example, the PUT creates the customer).

Customer Example

This example is a good way to understand frevvo's handling of document URIs and the powerful capabilities of composing multiple document resources into view resources. You can download the entire example including source code and forms by clicking here.

This example follows the principles of REST and uses the Restlet framework but you can use any framework or server-side model that you like. As mentioned earlier, frevvo forms can be thought of as View Resources that compose one or more Entity Resources (documents). In this example we have entities Customer and List of Customers. Reproduced here are the methods that they support.

Resource	Method	Description	Returns
Customer List	GET	List of customers (may be criteria based)	XML or JSON list of customers
Customer List	POST	Create new customer	URI of newly created customer
Customer	GET	Get customer data	XML representation of cutsomer
Customer	PUT	Update customer
Customer	DELETE	Remove customer

This is implemented in the two classes: com.frevvo.restlet.customer.CustomersResource and com.frevvo.restlet.customer.CustomerResource. These simply provide implementations of the above methods returning the desired representation of the resource for a GET, creating a new customer for a POST and updating an existing customer for a PUT. In general, the representation that is returned depends on content negotiation via the Accept headers.

Select Customer

There are three forms. The first one is the Select Customer form. This form allows you to search for a specific customer. It uses the first GET method from the table above, and populates a drop down with the list of customers returned according to the search criteria. This is done using a rule. Edit the form, click on the Rules tab and open the Get Customer List rule.

if (S.value.length > 0) {
eval('x=' + http.get('http://<hostname>/customers/?pattern=' + S.value));
C.options = x.customers;
ID.options = x.ids;
}

This rule populates the dropdown Customers based on the list of customers returned by the GET method that is invoked by the rule. When a rule invokes http.get(), it also sets the Accept header in the request to 'application/json'. This causes the implementation to provide the JSON representation of the customer list. In this example, we return two JSON arrays: an array of names and an array of IDs. These arrays are used to populate the two dropdowns in the example - the Customer Names dropdown and the hidden Customer IDs dropdown. Try typing a search string (e.g. A). This will return the list of customers whose names start with A. Select a customer from the list. The second rule in this form ensures that the hidden Customer ID field is in sync with the selected customer.

The Form action for this form is set to the URI template: http://<hostname>/frevvo/web/user/gallery/app/_73zHwep_EduZgK0BUzi1Ug/formtype/__AKE4PgqEdusGKt5_HoCDw?_method=POST&customer={ID}. As described in the Multi Page Forms section above, when the user clicks submit, the URI template above will be resolved based on the selected customer ID and the browser will be redirected to the resulting URI, which is simply that of the next form with a query parameter (customer=02, for example). This form is described below.

Customer Information

This form is described in the Updating a document section above. It GETs the XML representation for a specific customer using the third method in the table above, initializes the form with that information and displays it to the user. When submitted, the updated customer information is automaticlly PUT to the same [resolved] URI using the fourth method in the table above.

Create Customer

This form is described in the Creating a new document section above. When instantiated, it does a POST to the Read URI using the second method in the table above. This causes the server to create a new customer and return the URI of that customer. frevvo will automatically follow this URI, GET the representation of the customer and display the form (presumably with empty values). When the user enters all required fields and submits the form, frevvo will automatically PUT the resulting XML document to the URI for the newly created customer thereby updating the customer.

In this manner, the combination of URI templates, read/write methods and form parameters provides a very powerful and flexible way to interact with the web.

You can find further discussion of this example on the frevvo blog. The relevant articles are: Part 1 and Part 2. Other articles that may be of interest are How do I use my brand new WOA? and Ajax+REST: the next killer app?.

Form and Document Actions

In addition to manipulating documents via document URIs as described above, frevvo forms also provide form and document actions. The form action describes what the browser should do after the form is submitted. The document action permits the document to be POSTed to an arbitrary URI independent of the browser's actions. For example, you can POST the document to http://.../myServer/documentHandler but have the browser display a Thank You message. These are also discussed in the section on Form Properties.

Form Action

The form action simply describes what the browser should do after the form is submitted. There are three options:

• Display Message. This is the default option and is likely useful just for debugging. This causes the browser to simply display a standard frevvo page with a message that is customizable by you such as "Thank you for participating. A confirmation email will be sent to you". You can customize this message by typing it into the input field below.
• Go to URI. Select this option and type in any URI in the input field below. When the form is submitted, the browser is redirected to the specified URI. This URI is interpreted to be a relative URI, so make sure you add the http:// prefix otherwise you will likely see an error.
• POST document. Select this option and type in any URI in the input field below. When the form is submitted, frevvo POSTs the document set to the specified URI and displays whatever is returned. If this option is selected, the document action is greyed out and will be ignored. This is similar to standard XHTML forms - when submitted, the data is sent to the server which returns the next page to display.

Document Action

The document action provides for the ability to POST the document set to an additional URI. For example, you may wish to POST the document set to an email service (which sends an email) but display a different page to the user. There are three options:

• Save document. This is the default option. The document set that is generated upon form submission is stored in frevvo's document repository. It may be accessed using its unique URI. Currently, document sets are always saved even if one of the other document actions is selected.
• Email document. Select this option and specify an email address in the input field below. When the form is submitted, frevvo will send an email message with the XML documents generated by the form attached.
• POST document. Select this option and type in any URI in the input field below. When the form is submitted, frevvo POSTs the document set to the specified URI. Any returned XHTML or redirect is ignored. This option may be used for additional processing of the document set.

The document action can be synchronous (default) or asynchronous. If it is synchronous, the document action is first completed and then the form action is executed. For example, the document may be POSTed to a URI and a Thank You message displayed to the user. This POST will complete before the message is displayed. However, you may set the document action to be asynchronous by unchecking the checkbox in the form's edit container.

Email Integration

Integrating with your database

frevvo provides a simple connector that integrates forms with your database. The connector is freely available for download and is licensed under an open source model. The documentation can be found at Connecting with your database.

Integrating with web services

Multi page forms

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 Embed icon for your form on the Forms list page.

Here is an example of a form's URI:

http://www.frevvo.com/frevvo/web/user/myUser/app/_uJKtwbesEduG2Me8fheS4Q/formtype/_18go4Lx7EduG2Me8fheS4Q?_method=POST

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

../../../app/_uJKtwbesEduG2Me8fheS4Q/formtype/_18go4Lx7EduG2Me8fheS4Q?_method=POST

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.