| 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@167 | 7 | <body> |
| paulb@167 | 8 | <h1>Creating Applications: Recommendations and Advice</h1> |
| paulb@167 | 9 | <ol> |
| paulb@167 | 10 | </ol> |
| paulb@167 | 11 | <p>To avoid hard-to-explain problems when designing and testing |
| paulb@167 | 12 | templates, the following advice may be of some use:</p> |
| paulb@167 | 13 | <h2>Beware of Nesting Elements in Multiple-Choice Elements</h2> |
| paulb@167 | 14 | <p>It is not necessarily a good idea to nest elements inside |
| paulb@167 | 15 | multiple-choice elements like this:</p> |
| paulb@396 | 16 | <pre><multi><br /> <multi-enum value="1"/><br /> <multi-enum value="2"/><br /> <multi-enum value="3"/><br /> <nested value="x"/><br /></multi></pre> |
| paulb@167 | 17 | <p>The reason for this is that the number of multiple-choice values may |
| paulb@167 | 18 | vary within your application, and the nested elements will appear |
| paulb@167 | 19 | at a different position depending on how many such values have been |
| paulb@167 | 20 | inserted. Whilst this might not affect some applications, at least not |
| paulb@270 | 21 | to begin with, the usage of more advanced features (<a href="in-page-updates.html">in-page updates</a>, for example) will |
| paulb@177 | 22 | probably expose |
| paulb@167 | 23 | problems due to the way XSLForms reconstructs the XML document data |
| paulb@396 | 24 | from the input form data.</p><p>We can avoid the above mistake by specifying the first parameter in the <code>template:multiple-choice-field</code> and <code>template:multiple-choice-list-field</code> annotations. For example:</p><pre><select name="..." template:multiple-choice-field="multi,multi-enum,value"><br /> <option value="..." template:multiple-choice-value="multi-enum,value,selected"></option><br /></select></pre> |
| paulb@396 | 25 | <p>This effectively prevents us from inserting the <code>nested</code> element inside the <code>multi</code> element.<br /></p><h2>Beware of Adding Elements into Mixtures of Elements</h2> |
| paulb@177 | 26 | <p>Although we ignore this rule with the example in this documentation, |
| paulb@177 | 27 | it is necessary to be aware of problems with adding and removing |
| paulb@177 | 28 | elements where other elements may reside. Consider part of our form |
| paulb@177 | 29 | data structure:</p> |
| paulb@177 | 30 | <pre><item value="a"><br /> <type><br /> <type-enum value="1"/><br /> </type><br /> <subitem value="x"/><br /></item></pre> |
| paulb@177 | 31 | <p>Provided that we control the process of adding and removing the |
| paulb@177 | 32 | elements, making sure that they always reside at the end of the element |
| paulb@177 | 33 | collection inside the <code>item</code> element, and that they |
| paulb@177 | 34 | always follow a known number of elements, we can avoid issues with more |
| paulb@177 | 35 | advanced features (<a href="in-page-updates.html">in-page updates</a>, |
| paulb@177 | 36 | for example), although using such features on the <code>subitem</code> |
| paulb@177 | 37 | elements themselves may cause problems that may only be resolved by |
| paulb@177 | 38 | moving the <code>subitem</code> elements into a container element |
| paulb@177 | 39 | of their own:</p> |
| paulb@177 | 40 | <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 | 41 | <h2>Make Sure the Output Structure Agrees with the Template</h2> |
| paulb@167 | 42 | <ol> |
| paulb@167 | 43 | </ol> |
| paulb@167 | 44 | <p>Since XSLForms templates essentially describe the presentation of an |
| paulb@167 | 45 | XML document, it is vital that the output form data structure agrees |
| paulb@167 | 46 | with the template - that is, the output structure can be properly |
| paulb@167 | 47 | processed by the template and that all parts of the template are |
| paulb@167 | 48 | displayed as expected. It is also very important to make sure that |
| paulb@167 | 49 | transformations on the input document produce all |
| paulb@167 | 50 | the necessary elements for the output document so that the resulting |
| paulb@167 | 51 | page gives the user the opportunity to specify data that is missing. |
| paulb@167 | 52 | Consider this section of an example template:</p> |
| paulb@270 | 53 | <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 | 54 | <p>Here, if the <code>author</code> element is not found in the |
| paulb@167 | 55 | output structure, no field will be produced in the Web page, no |
| paulb@167 | 56 | opportunity will be given for an author to be specified, and no author |
| paulb@167 | 57 | information will subsequently be editable. One solution is to introduce |
| paulb@167 | 58 | the <code>author</code> element into the XML document when |
| paulb@167 | 59 | creating the <code>package</code> element - this should then |
| paulb@167 | 60 | "bootstrap" the process and ensure that the author details will remain |
| paulb@415 | 61 | 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#DocumentInitialisation">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 | 62 | elements would still be impossible to create in the user interface. The |
| paulb@270 | 63 | document initialisation mechanism distinguishes between these two cases |
| paulb@289 | 64 | 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> |
| paulb@289 | 65 | element is mentioned, the mechanism knows not to create such elements |
| paulb@289 | 66 | automatically. However, since no such selector exists for <code>package</code> elements, those elements are created automatically.</p><h2>Selecting from the Correct Document</h2><p>After |
| paulb@289 | 67 | document initialisation or any other transformation, it is necessary to |
| paulb@289 | 68 | re-evaluate selector information in the context of the updated document |
| paulb@289 | 69 | if such information is to be used with such updated data, noting that |
| paulb@289 | 70 | any changes in the structure of the such data will cause the selectors |
| paulb@289 | 71 | to refer to the wrong parts of documents. To make updated documents |
| paulb@289 | 72 | available to XSLForms, the following call can be made on the <code>form</code> object (the third parameter in the <code>respond_to_form</code> method):</p><pre>form.set_document(document_name, updated_document)</pre><p>The updated selectors can then be obtained as usual:</p><pre>selectors = form.get_selectors()</pre><p>Typically, |
| paulb@289 | 73 | selectors should be accessed and used before initialisation since they |
| paulb@289 | 74 | refer to information that must already exist and can therefore be |
| paulb@289 | 75 | manipulated without preparatory work being done on the documents |
| paulb@289 | 76 | involved.</p> |
| paulb@167 | 77 | <ol> |
| paulb@167 | 78 | </ol> |
| paulb@270 | 79 | </body></html> |
