1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/advice.html Thu Jul 21 21:06:00 2005 +0000
1.3 @@ -0,0 +1,52 @@
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 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 + <title>Creating Applications: Recommendations and Advice</title>
1.9 + <meta name="generator"
1.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +<body>
1.14 +<h1>Creating Applications: Recommendations and Advice</h1>
1.15 +<ol>
1.16 +</ol>
1.17 +<p>To avoid hard-to-explain problems when designing and testing
1.18 +templates, the following advice may be of some use:</p>
1.19 +<h2>Beware of Nesting Elements in Multiple-Choice Elements</h2>
1.20 +<p>It is not necessarily a good idea to nest elements inside
1.21 +multiple-choice elements like this:</p>
1.22 +<pre><multi><br /> <multi-enum value="1"/><br /> <multi-enum value="1"/><br /> <multi-enum value="1"/><br /> <nested value="x"/><br /></multi></pre>
1.23 +<p>The reason for this is that the number of multiple-choice values may
1.24 +vary within your application, and the nested elements will appear
1.25 +at a different position depending on how many such values have been
1.26 +inserted. Whilst this might not affect some applications, at least not
1.27 +to begin with, the usage of more advanced features (<a
1.28 + href="selectors.html">selectors</a>, for example) will probably expose
1.29 +problems due to the way XSLForms reconstructs the XML document data
1.30 +from the input form data.</p>
1.31 +<h2>Make Sure the Output Structure Agrees with the Template</h2>
1.32 +<ol>
1.33 +</ol>
1.34 +<p>Since XSLForms templates essentially describe the presentation of an
1.35 +XML document, it is vital that the output form data structure agrees
1.36 +with the template - that is, the output structure can be properly
1.37 +processed by the template and that all parts of the template are
1.38 +displayed as expected. It is also very important to make sure that
1.39 +transformations on the input document produce all
1.40 +the necessary elements for the output document so that the resulting
1.41 +page gives the user the opportunity to specify data that is missing.
1.42 +Consider this section of an example template:</p>
1.43 +<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>
1.44 +<p>Here, if the <code>author</code> element is not found in the
1.45 +output structure, no field will be produced in the Web page, no
1.46 +opportunity will be given for an author to be specified, and no author
1.47 +information will subsequently be editable. One solution is to introduce
1.48 +the <code>author</code> element into the XML document when
1.49 +creating the <code>package</code> element - this should then
1.50 +"bootstrap" the process and ensure that the author details will remain
1.51 +editable as long as the <code>package</code> element exists.</p>
1.52 +<ol>
1.53 +</ol>
1.54 +</body>
1.55 +</html>
2.1 --- a/docs/multivalue.html Thu Jul 21 20:13:45 2005 +0000
2.2 +++ b/docs/multivalue.html Thu Jul 21 21:06:00 2005 +0000
2.3 @@ -161,5 +161,9 @@
2.4 Note that it may be necessary to remove the old stylesheet for
2.5 producing output, <code>structure_output.xsl</code>, so that the
2.6 multivalue version of the template is taken into use.</p>
2.7 +<h2>Further Reading</h2>
2.8 +<p>Now that we have designed and implemented a simple application, it
2.9 +may be worth reading some <a href="advice.html">recommendations</a>
2.10 +about developing your own applications.</p>
2.11 </body>
2.12 </html>
3.1 --- a/docs/overview.html Thu Jul 21 20:13:45 2005 +0000
3.2 +++ b/docs/overview.html Thu Jul 21 21:06:00 2005 +0000
3.3 @@ -21,16 +21,7 @@
3.4 form</a></li>
3.5 <li><a href="multiple.html">Adding multiple-choice fields and values</a></li>
3.6 <li><a href="multivalue.html">Adding multivalued fields</a></li>
3.7 -</ol>
3.8 -<h2>Recommendations</h2>
3.9 -<ol>
3.10 - <li>Where multiple fields exist and can be added and removed, put
3.11 -them inside a separate element so that the selectors can successfully
3.12 -identify them. Otherwise, changing element orders can result in the
3.13 -wrong element being selected.</li>
3.14 - <li>Make sure that transformations on the input document produce all
3.15 -the necessary elements for the output document so that the resulting
3.16 -page gives the user the opportunity to specify data that is missing.</li>
3.17 + <li><a href="advice.html">Recommendations and advice</a></li>
3.18 </ol>
3.19 </body>
3.20 </html>