...

...

...

...

Document URIs

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

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

...

Updating a document

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

...

That's it. As usual, you access the form using its URl. 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. Live Forms will  will resolve the URI template above to: .../customers/02, GET the customer, and display the initialized form. When the form is submitted, Live Forms will  will automatically PUT the customer document to the same URI thereby updating the customer. The diagram below shows the interactions.

...

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, Live Forms  product name macro will store the generated document set and assign it a unique URI. The document set and the documents therein can be accessed at this URl.

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 URl . When the form is used (instantiated),  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,  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 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 [[V4_Designing_Forms#Name |Control Name]]. Consider the [[#Updating_a_document|Updating a document]] example  example above and the [http://www.frevvo.com/frevvo/web/user/gallery/app/_73zHwep_EduZgK0BUzi1Ug/formtype/__AKE4PgqEdusGKt5_HoCDw?_method=POST&embed=true&customer=02 sample form] therein 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  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  will automatically revert back to the default document with [[V4_Designing_Forms#Setting_a_Default_Value_for_a_Control |default values]] as default values as specified by the designer.

...

For example, if you enter ID 03, Live Forms will  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), Live Forms   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).

Example

This example is a good way to understand Live Formsunderstand ' 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 [http://www.frevvo.com/bucket/restlet/RestletCustomerExample.zip by clicking here].

This example follows the principles of REST and uses the [http://www.restlet.org Restlet framework] but  but you can use any framework or server-side model that you like. As mentioned earlier, Live Forms   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.

...

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.

...

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_Multi page _forms|Multi Page Forms]] section aboveforms section, 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|Updating a document]] section  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|Creating a new document]] section  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. Live Forms   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, Live Forms   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 Live Forms blog. The relevant articles are: [http://www.frevvo.com/blog/?p=26 Part 1] and [http://www.frevvo.com/blog/?p=32 Part 2]. Other articles that may be of interest are [http://www.frevvo.com/blog/?p=23 How do I use my brand new WOA?] and [http://www.frevvo.com/blog/?p=35 Ajax+REST: the next killer app?].