paulb@167 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
paulb@270 | 2 | <html xmlns="http://www.w3.org/1999/xhtml"><head> |
paulb@167 | 3 | <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> |
paulb@270 | 4 | |
paulb@270 | 5 | <title>Creating Applications: Recommendations and Advice</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> |
paulb@270 | 6 | <link href="styles.css" rel="stylesheet" type="text/css" /></head> |
paulb@270 | 7 | |
paulb@167 | 8 | <body> |
paulb@167 | 9 | <h1>Creating Applications: Recommendations and Advice</h1> |
paulb@167 | 10 | <ol> |
paulb@167 | 11 | </ol> |
paulb@167 | 12 | <p>To avoid hard-to-explain problems when designing and testing |
paulb@167 | 13 | templates, the following advice may be of some use:</p> |
paulb@167 | 14 | <h2>Beware of Nesting Elements in Multiple-Choice Elements</h2> |
paulb@167 | 15 | <p>It is not necessarily a good idea to nest elements inside |
paulb@167 | 16 | multiple-choice elements like this:</p> |
paulb@167 | 17 | <pre><multi><br /> <multi-enum value="1"/><br /> <multi-enum value="1"/><br /> <multi-enum value="1"/><br /> <nested value="x"/><br /></multi></pre> |
paulb@167 | 18 | <p>The reason for this is that the number of multiple-choice values may |
paulb@167 | 19 | vary within your application, and the nested elements will appear |
paulb@167 | 20 | at a different position depending on how many such values have been |
paulb@167 | 21 | inserted. Whilst this might not affect some applications, at least not |
paulb@270 | 22 | to begin with, the usage of more advanced features (<a href="in-page-updates.html">in-page updates</a>, for example) will |
paulb@177 | 23 | probably expose |
paulb@167 | 24 | problems due to the way XSLForms reconstructs the XML document data |
paulb@167 | 25 | from the input form data.</p> |
paulb@177 | 26 | <h2>Beware of Adding Elements into Mixtures of Elements</h2> |
paulb@177 | 27 | <p>Although we ignore this rule with the example in this documentation, |
paulb@177 | 28 | it is necessary to be aware of problems with adding and removing |
paulb@177 | 29 | elements where other elements may reside. Consider part of our form |
paulb@177 | 30 | data structure:</p> |
paulb@177 | 31 | <pre><item value="a"><br /> <type><br /> <type-enum value="1"/><br /> </type><br /> <subitem value="x"/><br /></item></pre> |
paulb@177 | 32 | <p>Provided that we control the process of adding and removing the |
paulb@177 | 33 | elements, making sure that they always reside at the end of the element |
paulb@177 | 34 | collection inside the <code>item</code> element, and that they |
paulb@177 | 35 | always follow a known number of elements, we can avoid issues with more |
paulb@177 | 36 | advanced features (<a href="in-page-updates.html">in-page updates</a>, |
paulb@177 | 37 | for example), although using such features on the <code>subitem</code> |
paulb@177 | 38 | elements themselves may cause problems that may only be resolved by |
paulb@177 | 39 | moving the <code>subitem</code> elements into a container element |
paulb@177 | 40 | of their own:</p> |
paulb@177 | 41 | <pre><item value="a"><br /> <type><br /> <type-enum value="1"/><br /> </type><br /> <subitems><br /> <subitem value="x"/><br /> </subitems><br /></item></pre> |
paulb@167 | 42 | <h2>Make Sure the Output Structure Agrees with the Template</h2> |
paulb@167 | 43 | <ol> |
paulb@167 | 44 | </ol> |
paulb@167 | 45 | <p>Since XSLForms templates essentially describe the presentation of an |
paulb@167 | 46 | XML document, it is vital that the output form data structure agrees |
paulb@167 | 47 | with the template - that is, the output structure can be properly |
paulb@167 | 48 | processed by the template and that all parts of the template are |
paulb@167 | 49 | displayed as expected. It is also very important to make sure that |
paulb@167 | 50 | transformations on the input document produce all |
paulb@167 | 51 | the necessary elements for the output document so that the resulting |
paulb@167 | 52 | page gives the user the opportunity to specify data that is missing. |
paulb@167 | 53 | Consider this section of an example template:</p> |
paulb@270 | 54 | <pre><p template:element="package"><br /> <p template:element="author"><br /> Name: <input template:attribute-field="name" name="..." type="text" value="..."/><br /> </p><br /></p></pre> |
paulb@167 | 55 | <p>Here, if the <code>author</code> element is not found in the |
paulb@167 | 56 | output structure, no field will be produced in the Web page, no |
paulb@167 | 57 | opportunity will be given for an author to be specified, and no author |
paulb@167 | 58 | information will subsequently be editable. One solution is to introduce |
paulb@167 | 59 | the <code>author</code> element into the XML document when |
paulb@167 | 60 | creating the <code>package</code> element - this should then |
paulb@167 | 61 | "bootstrap" the process and ensure that the author details will remain |
paulb@270 | 62 | editable as long as the <code>package</code> element exists.</p><h3>Ensuring Element Structure with Document Initialisation</h3><p>Although it is not necessary to use <a href="multiple.html">document initialisation</a> in resources, the above case would be detected by an input/initialiser stylesheet, and the <code>package</code> and <code>author</code> elements would be added if no way of adding them was mentioned in the template. Typically, we would employ <a href="selectors.html">selectors</a> to provide the ability to add elements in templates, and the above example could be extended as follows:</p><pre><p template:element="package"><br /> <p template:element="author"><br /> Name: <input template:attribute-field="name" name="..." type="text" value="..."/><br /> </p><br /> <p><br /> <input name="..." template:selector-field="add-author,author" type="submit" value="Add author" /><br /> </p><br /></p></pre><p>With the newly-added selector, we can see that <code>author</code> elements could at least be added by users of the application, but <code>package</code> |
paulb@270 | 63 | elements would still be impossible to create in the user interface. The |
paulb@270 | 64 | document initialisation mechanism distinguishes between these two cases |
paulb@270 | 65 | by looking for selectors which mention element names; here, the <code>template:selector-field</code> attribute has two parts to its value:</p><ol><li>A name used to identify the selector.</li><li>The name of an element: <code>author</code></li></ol><p>Since the <code>author</code> element is mentioned, the mechanism knows not to create such elements automatically. However, since no such selector exists for <code>package</code> elements, those elements are created automatically.</p> |
paulb@167 | 66 | <ol> |
paulb@167 | 67 | </ol> |
paulb@270 | 68 | </body></html> |