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.
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.
On this page:
Document URIs
For each Document Type that you add to your form, 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 customer |
| 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:
- 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.
- Drag/drop, change labels etc. directly in the browser
- Specify URI template .../customers/{customer}, choose Read Method GET and Write Method PUT
- Specify a Form Action URI if desired (we'll get to this later).
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. will resolve the URI template above to: .../customers/02, GET the customer, and display the initialized form. When the form is submitted,
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:
- 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.
- Modify a value and click Submit. The form will automatically PUT to the correct resource and update the customer information.
- Finally,
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 Control Name. 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, 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, 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, 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), 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
The database connector is a working example of a restful service. You can Download the v2.4 database connector which comes with source code. Refer to the db connector tutorial to see how this restful service is used.