1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/design.html Sun Jul 17 01:07:10 2005 +0000
1.3 @@ -0,0 +1,112 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml">
1.6 +<head>
1.7 +
1.8 +
1.9 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.10 +
1.11 +
1.12 +
1.13 + <title>Creating Applications: Design a Template</title>
1.14 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.15 +
1.16 +
1.17 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.18 +</head>
1.19 +
1.20 +
1.21 +<body>
1.22 +
1.23 +<h1>Creating Applications: Design
1.24 +a Template</h1>
1.25 +
1.26 +<p>To design a template, create a
1.27 +new Web page using whichever tools or applications you feel most
1.28 +comfortable with. Given that XSLForms applications involve Web forms,
1.29 +you will obviously need to add forms and fields to your
1.30 +page. In
1.31 +the beginning, it
1.32 +is not that important to use the correct names in each of the fields -
1.33 +these will be added later.</p>
1.34 +
1.35 +<p>Here are some tips for
1.36 +designing the template:</p>
1.37 +
1.38 +<h2>Page Structure</h2>
1.39 +
1.40 +<p>Think about your form in terms
1.41 +of the structure of the data being represented. You may want to have a
1.42 +list of items where each item can be edited by changing a text field
1.43 +and removed by pressing a button next to that field, and you may want
1.44 +to have a button which adds new items to the list. Each item may look
1.45 +like
1.46 +this:</p>
1.47 +
1.48 +<form method="post" action="none" name="structure">
1.49 +
1.50 + <p>Some
1.51 +item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" />
1.52 + </p>
1.53 +
1.54 +</form>
1.55 +
1.56 +<p>The HTML code which produces this item might look like this:</p>
1.57 +
1.58 +<pre><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p></pre>
1.59 +
1.60 +<p>Although you will only need to
1.61 +"paint" one such item in the document, you should imagine that when
1.62 +many such items are presented they will be produced by copying the form
1.63 +of the original item; thus, the details of that item should reside in
1.64 +an HTML element which can be replicated many times at a particular
1.65 +position in a document, like this:</p>
1.66 +
1.67 +<pre><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p><br /><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p><br /><p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /></p></pre>
1.68 +
1.69 +<p>Making sure that the final form of the list is sensible HTML code is
1.70 +an activity explored <a href="structure.html">later</a> in the
1.71 +development <a href="overview.html">process</a>.</p>
1.72 +
1.73 +<h2>Hierarchical Structures</h2>
1.74 +
1.75 +<p>Although we need not consider the structure of the template too
1.76 +deeply, given the above advice about how structure should be
1.77 +represented in HTML, it is interesting to consider hierarchical or
1.78 +nested structures. For example, each item in a list may itself contain
1.79 +a number of other items; for example:</p>
1.80 +
1.81 +<form method="post" action="none" name="hierarchical">
1.82 +
1.83 + <p>Some item: <input name="value" value="some value" /><input name="remove" value="Remove" type="submit" /></p>
1.84 +
1.85 +
1.86 + <p>Itself containing more items:</p>
1.87 +
1.88 +
1.89 + <p>Sub-item: <input name="subvalue" value="some other value" /><input name="remove2" value="Remove" type="submit" /></p>
1.90 +
1.91 +</form>
1.92 +
1.93 +<p>Given that the whole of the above fragment is a single item in a
1.94 +list, to ensure that the above advice is heeded about items being
1.95 +easily replicated, we need to enclose the fragment in a single HTML
1.96 +element, like this:</p>
1.97 +
1.98 +<pre><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div></pre>
1.99 +
1.100 +<p>In the above example, the <code>div</code> element encloses the
1.101 +outer list item. Meanwhile, the inner list item is itself enclosed
1.102 +within a <code>p</code> element in the same way as the original
1.103 +example enclosed its simple list item. Consider the above example with
1.104 +replicated items:</p>
1.105 +
1.106 +<pre><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /><div><br /> <p><br /> Some item: <input name="value" type="text" value="some value" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p><br /> Sub-item: <input name="subvalue" type="text" value="some other value" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /></pre>
1.107 +
1.108 +<h2>Saving the Template</h2>
1.109 +
1.110 +<p>Once you are happy with the
1.111 +design of the page, save it to the <a href="directory.html">directory</a>
1.112 +created earlier, then proceed to <a href="structure.html">adding structure information</a> in the next stage of the <a href="overview.html">process</a>.</p>
1.113 +
1.114 +</body>
1.115 +</html>
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/directory.html Sun Jul 17 01:07:10 2005 +0000
2.3 @@ -0,0 +1,46 @@
2.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.5 +<html xmlns="http://www.w3.org/1999/xhtml">
2.6 +<head>
2.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
2.8 + <title>Creating Applications: Create a Directory</title>
2.9 + <meta name="generator"
2.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
2.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.12 +</head>
2.13 +<body>
2.14 +<h1>Creating Applications: Create a Directory</h1>
2.15 +<p>The recommended directory structure of an XSLForms application is as
2.16 +follows:</p>
2.17 +<ul>
2.18 + <li>A top-level directory corresponding to a Python package,
2.19 +containing...<br />
2.20 + <ul>
2.21 + <li>An <code>__init__.py</code> file and other source files,
2.22 +containing the <a href="Web-resource.html">Web resources</a> and other
2.23 +application logic.</li>
2.24 + <li>A subdirectory containing non-code resources for the
2.25 +application.</li>
2.26 + <li>Other package directories, if necessary.</li>
2.27 + </ul>
2.28 + </li>
2.29 +</ul>
2.30 +<p>For example, we might create a directory structure like this:</p>
2.31 +<ul>
2.32 + <li>A top-level directory called <code>Configurator</code>,
2.33 +containing...<br />
2.34 + <ul>
2.35 + <li>An <code>__init__.py</code> file containing the Web
2.36 +resources and other application logic.</li>
2.37 + <li>A subdirectory called <code>Resources</code> containing
2.38 +non-code resources.</li>
2.39 + </ul>
2.40 + </li>
2.41 +</ul>
2.42 +<p>In UNIX-style commands, this would be done as follows:</p>
2.43 +<pre>mkdir Configurator<br />mkdir Configurator/Resources<br />touch Configurator/__init__.py</pre>
2.44 +<p>It is in the <code>Resources</code> subdirectory that we will save
2.45 +our template files when <a href="design.html">designing</a> them as
2.46 +part of the next activity in the application development <a
2.47 + href="overview.html">process</a>.</p>
2.48 +</body>
2.49 +</html>
3.1 --- a/docs/index.html Sat Jul 16 20:59:23 2005 +0000
3.2 +++ b/docs/index.html Sun Jul 17 01:07:10 2005 +0000
3.3 @@ -38,5 +38,9 @@
3.4 within Python by importing modules (such as <a
3.5 href="../apidocs/public/XSLOutput-module.html"><code>XSLOutput</code></a>)
3.6 and using Python's built-in <code>help</code> function.</p>
3.7 +<h2>About XSLForms Applications</h2>
3.8 +<ul>
3.9 + <li><a href="overview.html">Creating Applications: An Overview</a></li>
3.10 +</ul>
3.11 </body>
3.12 </html>
4.1 --- a/docs/overview.html Sat Jul 16 20:59:23 2005 +0000
4.2 +++ b/docs/overview.html Sun Jul 17 01:07:10 2005 +0000
4.3 @@ -12,25 +12,13 @@
4.4 <p>The following steps briefly describe how to make a new application:<br />
4.5 </p>
4.6 <ol>
4.7 - <li>Design a template, adding forms and fields. In the beginning, it
4.8 -is not that important to use the correct names in each of the fields -
4.9 -these will be added later.</li>
4.10 - <li>Add structural template attributes such as template:element,
4.11 -template:attribute and template:value so that the fields sit in
4.12 -different parts of the input document format being modelled. Replace
4.13 -the field names with special functions such as template:field-name().
4.14 -For buttons which add and remove parts of the input document, employ
4.15 -selector notation and the template:this-position() function.</li>
4.16 - <li>Where multiple choice fields are employed, input documents must
4.17 -be transformed so that the multiple choice options are included in the
4.18 -output. This can be achieved using documents containing the different
4.19 -option values and transformations which insert those values into the
4.20 -input document.</li>
4.21 - <li>To produce the output document, the template needs preparing
4.22 -first so that an output stylesheet is produced; then, the output
4.23 -stylesheet is applied to the processed input document utilising various
4.24 -extension functions which produce the computed field names in the final
4.25 -output document.</li>
4.26 + <li><a href="directory.html">Create a directory to hold your files</a></li>
4.27 + <li><a href="design.html">Design a template</a></li>
4.28 + <li><a href="structure.html">Add structure to the template</a></li>
4.29 + <li><a href="catalogues.html">Prepare catalogues of multiple-choice
4.30 +values</a></li>
4.31 + <li><a href="Web-resource.html">Write a Web resource to display the
4.32 +form</a></li>
4.33 </ol>
4.34 <h2>Recommendations</h2>
4.35 <ol>
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/structure.html Sun Jul 17 01:07:10 2005 +0000
5.3 @@ -0,0 +1,122 @@
5.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5.5 +<html xmlns="http://www.w3.org/1999/xhtml">
5.6 +<head>
5.7 +
5.8 +
5.9 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
5.10 +
5.11 +
5.12 +
5.13 + <title>Creating Applications: Add Structure</title>
5.14 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
5.15 +
5.16 +
5.17 + <link href="styles.css" rel="stylesheet" type="text/css" />
5.18 +</head>
5.19 +
5.20 +
5.21 +<body>
5.22 +
5.23 +<h1>Creating Applications: Add Structure</h1>
5.24 +
5.25 +<p>During the <a href="design.html">design</a> activity, it was
5.26 +necessary to consider the structure of the information being presented.
5.27 +In proper XSLForms templates, we make such structural information
5.28 +explicit by adding special attributes to the HTML code. Consider the
5.29 +hierarchy example presented in the previous activity:</p>
5.30 +<ul>
5.31 + <li>A list of editable items, each containing...<br />
5.32 + <ul>
5.33 + <li>A list of editable items.</li>
5.34 + </ul>
5.35 + </li>
5.36 +</ul>
5.37 +<h2>The XSLForms Conceptual Model</h2>
5.38 +<p>In XSLForms applications form data is processed as XML documents.</p>
5.39 +<ul>
5.40 + <li>We start with an initial XML document which is then used together
5.41 +with a template to produce a Web page that can be understood by a Web
5.42 +browser, and inside this Web page is a form which is used to collect
5.43 +information from users of our application.</li>
5.44 + <li>Upon submission of the form, the form data is processed and appears within our application as an XML document once again.</li>
5.45 + <li>This newly-received document can be processed, validated, and so
5.46 +on, and then used to produce another Web page for the users to interact
5.47 +with.</li>
5.48 + <li>And so the process repeats itself many times.</li>
5.49 +</ul>
5.50 +<p>Therefore, it becomes important to imagine how we would represent
5.51 +the data described above as an XML document; something like this might
5.52 +be appropriate:</p>
5.53 +<pre><?xml version="1.0"?><br /><item value="some value"><br /> <subitem subvalue="some other value"/><br /></item></pre>
5.54 +<p>Therefore, we must seek to add the following structural information to our HTML code:</p>
5.55 +<ul>
5.56 + <li>Each list item is represented by an XML element called "item".</li>
5.57 + <li>The value of each list item is represented by an XML attribute called "value".</li>
5.58 + <li>Items within items are represented by XML elements called "subitem".</li>
5.59 + <li>Each value of these subitems is represented by an XML attribute called "subvalue".</li>
5.60 +</ul>
5.61 +<p>What we must do is to find a way to describe how our template will
5.62 +map onto the form data and present it as a Web page for the purpose of
5.63 +user interaction.<br />
5.64 +</p>
5.65 +<h2>Annotating the Template</h2>
5.66 +<p>Taking the HTML example from before, we add special annotations to the template to produce something like this:</p>
5.67 +<pre><html xmlns="http://www.w3.org/1999/xhtml"<br /> xmlns:template="http://www.boddie.org.uk/ns/xmltools/template"><br /><br /><!-- Template text between the start and the interesting part. --><br /><br /><div template:element="item"><br /> <p><br /> Some item: <input template:attribute="value" name="{template:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove" type="submit" value="Remove" /><br /> </p><br /> <p><br /> Itself containing more items:<br /> </p><br /> <p template:element="subitem"><br /> Sub-item: <input template:attribute="subvalue" name="{template:field-name()}" type="text" value="{$this-value}" /><br /> <input name="remove2" type="submit" value="Remove" /><br /> </p><br /></div><br /><br /><!-- Template text between the interesting part and the end. --><br /><br /></html></pre>
5.68 +<p>The following annotations have been added:</p>
5.69 +<ul>
5.70 + <li>For elements, the <code>template:element</code> attributes were added to the HTML elements which will be replicated when presenting the final output.</li>
5.71 + <li>For attributes, the <code>template:attribute</code> attributes were added to the form <code>input</code> elements.</li>
5.72 +</ul>
5.73 +<p>In addition, some of the attributes in the original HTML code have been changed:</p>
5.74 +<ul>
5.75 + <li>The <code>input</code> elements' <code>name</code> attributes have been redefined to use the special <code>{template:field-name()}</code> value.</li>
5.76 + <li>The <code>input</code> elements' <code>value</code> attributes have been redefined to use the special <code>{$this-value}</code> value.</li>
5.77 +</ul>
5.78 +<p>Whereas the first set of annotations reproduce the desired
5.79 +structure, the latter modifications are really housekeeping measures to
5.80 +make sure that the final output contains the correct names and values
5.81 +for each of the form fields shown to the user.</p>
5.82 +<div class="WebStack">
5.83 +<h3>Basic Template Annotation</h3>
5.84 +<p>The following special annotations can be used to describe XML document structures in templates:</p>
5.85 +<dl>
5.86 + <dt><code>template:element</code></dt>
5.87 + <dd>This attribute should be added to an element in the template in
5.88 +order to mark that element and its contents as mapping onto or
5.89 +representing an element in the XML document version of the
5.90 +form. In the example, the <code>div</code> element is annotated with this attribute to indicate that it maps onto the <code>item</code> element in the XML document version of the form. It is possible to specify more than one name as the value for a <code>template:element</code> attribute by separating each name with a comma; for example:<br />
5.91 + <pre><div template:element="parent,child"><br /> <p>This is a child element in the XML document version of the form.</p><br /></div></pre>
5.92 + </dd>
5.93 + <dd>The meaning of this is that the annotated element maps onto all <code>child</code> elements within all <code>parent</code>
5.94 +elements in the XML document version of the form. In other words,
5.95 +instead of having to create separate HTML elements in the template for
5.96 +each XML document element being represented, we can collapse the
5.97 +annotations into a single <code>template:element</code> attribute on a single HTML element.</dd>
5.98 + <dt><code>template:attribute</code></dt>
5.99 + <dd>This attribute should be added to an element in the template in
5.100 +order to mark that element and its contents as mapping onto or
5.101 +representing an attribute in the XML document version of the form.
5.102 +The <code>template:attribute</code> annotation exposes various
5.103 +special values which are described below - such value insert dynamic
5.104 +content from the XML document version of the form into the final output
5.105 +generated from the template.</dd>
5.106 + <dt><code>{$this-value}</code></dt>
5.107 + <dd>This special value should be used in HTML attributes where the
5.108 +value of an attribute from the XML document version of the form is
5.109 +to be included or presented in the final output. In the example,
5.110 +the <code>value</code> and <code>subvalue</code> attributes are presented in the <code>value</code> attributes of the HTML <code>input</code> elements in this way.</dd>
5.111 + <dt><code>{template:field-name()}</code></dt>
5.112 + <dd>This special value should be used in HTML attributes where the
5.113 +name of an attribute from the XML document version of the form is to be
5.114 +included or presented in the final output.</dd>
5.115 +</dl>
5.116 +<p>The <a href="reference.html">reference guide</a> provides a complete list of special values for use in template annotations.</p>
5.117 +</div>
5.118 +<h2>Adding Selectors</h2>
5.119 +<p>Whilst the above annotations permit the template to display the data
5.120 +in XML documents containing form data, the other aspects of the user
5.121 +interface - the addition and removal of items and subitems - are not
5.122 +yet modelled in the template.</p>
5.123 +
5.124 +</body>
5.125 +</html>
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/styles.css Sun Jul 17 01:07:10 2005 +0000
6.3 @@ -0,0 +1,66 @@
6.4 +/* Generated by CaScadeS, a stylesheet editor for Mozilla Composer */
6.5 +
6.6 + body { background-color: white;
6.7 + }
6.8 +
6.9 + h1 { color: navy;
6.10 + font-family: sans-serif;
6.11 + font-size: 2.0em;
6.12 + }
6.13 +
6.14 + h2 { color: navy;
6.15 + font-family: sans-serif;
6.16 + font-size: 1.8em;
6.17 + }
6.18 +
6.19 + h3 { color: navy;
6.20 + font-family: sans-serif;
6.21 + font-size: 1.6em;
6.22 + }
6.23 +
6.24 + h4 { color: navy;
6.25 + font-family: sans-serif;
6.26 + font-size: 1.4em;
6.27 + }
6.28 +
6.29 + ul { list-style-type: disc;
6.30 + }
6.31 +
6.32 + pre { border: 1pt solid black;
6.33 + padding: 0.5em;
6.34 + background-color: silver;
6.35 + color: black;
6.36 + }
6.37 +
6.38 + .WebStack { border: 1pt solid black;
6.39 + background-color: rgb(224, 224, 224);
6.40 + padding-left: 0.5em;
6.41 + padding-right: 0.5em;
6.42 + }
6.43 +
6.44 + .explanation { border-style: dotted;
6.45 + border-width: 1px;
6.46 + padding: 0.25em;
6.47 + display: block;
6.48 + position: relative;
6.49 + background-color: rgb(255, 255, 153);
6.50 + font-weight: normal;
6.51 + top: 0.5em;
6.52 + left: -1em;
6.53 + }
6.54 +
6.55 + .layers { width: 60%;
6.56 + text-align: center;
6.57 + }
6.58 +
6.59 + .method { border-style: dotted;
6.60 + border-width: 1px;
6.61 + padding: 0.25em;
6.62 + font-weight: normal;
6.63 + display: block;
6.64 + position: relative;
6.65 + background-color: rgb(238, 238, 238);
6.66 + left: 1em;
6.67 + top: 1em;
6.68 + }
6.69 +