Before designing a template, we must first consider how the form +data to be modelled in our application will be structured. Let us +consider the following hierarchical structure:
+ +Since XSLForms is an XML-based framework, let us define this structure using an informal example XML document:
+<?xml version="1.0"?>+
<structure>
<item value="some value">
<subitem subvalue="some other value"/>
</item>
</structure>
The above example only shows a single item and a single subitem +within it. Our application will provide the ability to add and remove +items and subitems, although this is not directly modelled in the XML +documents that will be used to represent the form data.
+With this basic information defined, we can now proceed to designing a template in the next stage of the process.
+ + + + + + diff -r ab7be4e5ffbe -r fd0a80c7574f docs/design.html --- a/docs/design.html Mon Jul 18 22:31:18 2005 +0000 +++ b/docs/design.html Tue Jul 19 00:19:38 2005 +0000 @@ -1,145 +1,122 @@ - - - - - - - - - -To design a template, create a +
In XSLForms applications, templates are just Web pages with some +additional annotations. Thus, to begin the design of a template you can +create a new Web page using whichever tools or applications you feel most comfortable with. Given that XSLForms applications involve Web forms, you will obviously need to add forms and fields to your -page. In -the beginning, it -is not that important to use the correct names in each of the fields - -these will be added later.
- - -The following sections discuss various techniques used in designing a template.
-Think about your form in terms -of the structure of the data being represented. You may want to have a -list of items where each item can be edited by changing a text field -and removed by pressing a button next to that field, and you may want -to have a button which adds new items to the list. Each item may look -like -this:
- - +page. +With a structure for the Web forms already +defined, we must now concentrate on designing a suitable user interface +for the editable items and subitems, along with some mechanisms for +adding and removing these things.
+In raw HTML - that is, the code which defines how a Web page is made +- we may wish to design the skeleton (or outline) of the page:
+<?xml version="1.0"?>+
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Example</title>
</head>
<body>
<form action="" method="POST">
<!-- Template text between the start and the interesting part. -->
<!-- The interesting part which we will design below. -->
<!-- Template text between the interesting part and the end. -->
</form>
</body>
</html>
Most visual editors for Web pages will add such details +automatically when creating a new page, but there are a few things to +remember to check:
+form element to the outline so that
+the form fields added later actually perform some function when testing
+our application.Each of the items presented using the template may employ a simple +label and a text field. Alongside these things, we may also wish to +have a button which can be pressed to remove that item from its list. +The visual representation of this might resemble the following:
- - -The HTML code which produces this item in a Web page might look like this:
- - -<html xmlns="http://www.w3.org/1999/xhtml">- - -
<head>
<title>Example</title>
</head>
<body>
<!-- Template text between the start and the interesting part. -->
<form action="" method="POST">
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<!-- Template text between the interesting part and the end. -->
</form>
</body>
</html>
Although you will only need to -"paint" one such item in the document, you should imagine that when -many such items are presented they will be produced by copying the form -of the original item; thus, the details of that item should reside in -an HTML element which can be replicated many times at a particular -position in a document, like this:
- - -<p>- - -
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
Making sure that the final form of the list is sensible HTML code is -an activity explored later in the -development process.
- - -Although we need not consider the structure of the template too -deeply, given the above advice about how structure should be -represented in HTML, it is interesting to consider hierarchical or -nested structures. For example, each item in a list may itself contain -a number of other items; for example:
- - +The HTML code which produces this representation might look like +this:
+<div>+
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
</div>
Although we have given names to the different input
+elements, it
+is actually not that important to use the correct names at this stage
+in the development process - the actual names will be added later.
One important thing to note +is that the item is defined within a single top-level HTML element - +the significance of this will become clear later on.
+In the structure of the form data, we decided to have lists of +subitems belonging to each item. To achieve this, we can thus extend +the above design for the items by adding some additional text and a +similar label, field and button arrangement for each of the subitems. +For example:
- - -Given that the whole of the above fragment is a single item in a -list, to ensure that the above advice is heeded about items being -easily replicated, we need to enclose the fragment in a single HTML -element, like this:
- - -<html xmlns="http://www.w3.org/1999/xhtml">- - +
<head>
<title>Example</title>
</head>
<body>
<form action="" method="POST">
<!-- Template text between the start and the interesting part. -->
<div>
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
</div>
<!-- Template text between the interesting part and the end. -->
</form>
</body>
</html>
This representation might be expressed in HTML as follows:
+<div>
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
</div>
In the above example, the div element encloses the
outer list item. Meanwhile, the inner list item is itself enclosed
within a p element in the same way as the original
-example enclosed its simple list item. Consider the above example with
-replicated items:
<div>- - +example enclosed its simple list item. +
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
</div>
<div>
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
</div>
It should be noted that +the item and subitem are each defined within single enclosing +HTML elements - as noted above, the motivation for this will become +clear later on.
+Our chosen user interface for adding items and subitems is through +the use of buttons under each list. +We can thus extend our visual representation to incorporate such +details. For example: +
+ +This representation might be expressed in HTML as follows:
+<div>+
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
<p>
<input name="add2" type="submit" value="Add subitem" />
</p>
</div>
<p>
<input name="add" type="submit" value="Add item" />
</p>
In the above example, the new buttons have been added alongside the
+elements which define the subitem and item regions of the template.
+Thus, the input field called add2
+which adds subitems is alongside, not inside, the p
+element which defines the subitem region of the template. Likewise,
+the input field called add which
+adds items is alongside, not inside, the div element
+which defines the item region of the template.
Adding the above modifications to the outline, we end up with the +following HTML code:
+<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Example</title>
</head>
<body>
<form action="" method="POST">
<!-- Template text between the start and the interesting part. -->
<div>
<p>
Some item: <input name="value" type="text" value="some value" />
<input name="remove" type="submit" value="Remove" />
</p>
<p>
Itself containing more items:
</p>
<p>
Sub-item: <input name="subvalue" type="text" value="some other value" />
<input name="remove2" type="submit" value="Remove" />
</p>
<p>
<input name="add2" type="submit" value="Add subitem" />
</p>
</div>
<p>
<input name="add" type="submit" value="Add item" />
</p>
<!-- Template text between the interesting part and the end. -->
</form>
</body>
</html>
Once you are happy with the design of the page, save it to the directory -created earlier, then proceed to adding structure information in the next stage of the process.
- - +created earlier, then proceed to adding +structure information in the next stage of the process. diff -r ab7be4e5ffbe -r fd0a80c7574f docs/directory.html --- a/docs/directory.html Mon Jul 18 22:31:18 2005 +0000 +++ b/docs/directory.html Tue Jul 19 00:19:38 2005 +0000 @@ -50,7 +50,7 @@For the above example, the directory structure would be created using UNIX-style commands as follows:
-mkdir Configurator+
mkdir Configurator/Resources
touch Configurator/__init__.py
mkdir VerySimple
mkdir VerySimple/Resources
touch VerySimple/__init__.py
It is in the Resources subdirectory that we will save
diff -r ab7be4e5ffbe -r fd0a80c7574f docs/model.html
--- a/docs/model.html Mon Jul 18 22:31:18 2005 +0000
+++ b/docs/model.html Tue Jul 19 00:19:38 2005 +0000
@@ -3,11 +3,16 @@
In applications based on XSLForms, form data is processed as XML documents as shown in the following diagram:
+ +In applications based on XSLForms, form data is modelled and processed as XML documents as shown in the following diagram:
+| + | Application + Starting with an initial XML document... |
+
XSLForms + A template is used together with the XML document to produce a Web page... |
+
Browser + The Web page contains a form which is filled out by users of the application and submitted back to the application... |
+
|---|---|---|---|
| XSLForms + The incoming form data is converted to an XML document... |
+
Application + The incoming XML document is processed, validated, and so on... |
+
XSLFormsA template is used together with the new XML document to produce a Web page... | +BrowserAn updated Web page is shown to the user. The page may contain a form which may be filled out and submitted... | +
The XSLForms framework therefore performs two main functions:
+The following steps briefly describe how to make a new application:
+