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