XSLTools

docs/advice.html

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