# HG changeset patch # User paulb # Date 1121979960 0 # Node ID 2a3c12b1d737510566019ba665712346424b2a29 # Parent 19d400c3a10127c1b64ec2c24a476ff88c35bdbb [project @ 2005-07-21 21:06:00 by paulb] Added some recommendations and advice. diff -r 19d400c3a101 -r 2a3c12b1d737 docs/advice.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/advice.html Thu Jul 21 21:06:00 2005 +0000 @@ -0,0 +1,52 @@ + + + + + Creating Applications: Recommendations and Advice + + + + +

Creating Applications: Recommendations and Advice

+
    +
+

To avoid hard-to-explain problems when designing and testing +templates, the following advice may be of some use:

+

Beware of Nesting Elements in Multiple-Choice Elements

+

It is not necessarily a good idea to nest elements inside +multiple-choice elements like this:

+
<multi>
<multi-enum value="1"/>
<multi-enum value="1"/>
<multi-enum value="1"/>
<nested value="x"/>
</multi>
+

The reason for this is that the number of multiple-choice values may +vary within your application, and the nested elements will appear +at a different position depending on how many such values have been +inserted. Whilst this might not affect some applications, at least not +to begin with, the usage of more advanced features (selectors, for example) will probably expose +problems due to the way XSLForms reconstructs the XML document data +from the input form data.

+

Make Sure the Output Structure Agrees with the Template

+
    +
+

Since XSLForms templates essentially describe the presentation of an +XML document, it is vital that the output form data structure agrees +with the template - that is, the output structure can be properly +processed by the template and that all parts of the template are +displayed as expected. It is also very important to make sure that +transformations on the input document produce all +the necessary elements for the output document so that the resulting +page gives the user the opportunity to specify data that is missing. +Consider this section of an example template:

+
<p template:element="package">
<p template:element="author">
Name: <input template:attribute="name" name="{template:this-attribute()}" type="text" value="{$this-value}"/>
</p>
</p>
+

Here, if the author element is not found in the +output structure, no field will be produced in the Web page, no +opportunity will be given for an author to be specified, and no author +information will subsequently be editable. One solution is to introduce +the author element into the XML document when +creating the package element - this should then +"bootstrap" the process and ensure that the author details will remain +editable as long as the package element exists.

+
    +
+ + diff -r 19d400c3a101 -r 2a3c12b1d737 docs/multivalue.html --- a/docs/multivalue.html Thu Jul 21 20:13:45 2005 +0000 +++ b/docs/multivalue.html Thu Jul 21 21:06:00 2005 +0000 @@ -161,5 +161,9 @@ Note that it may be necessary to remove the old stylesheet for producing output, structure_output.xsl, so that the multivalue version of the template is taken into use.

+

Further Reading

+

Now that we have designed and implemented a simple application, it +may be worth reading some recommendations +about developing your own applications.

diff -r 19d400c3a101 -r 2a3c12b1d737 docs/overview.html --- a/docs/overview.html Thu Jul 21 20:13:45 2005 +0000 +++ b/docs/overview.html Thu Jul 21 21:06:00 2005 +0000 @@ -21,16 +21,7 @@ form
  • Adding multiple-choice fields and values
  • Adding multivalued fields
  • - -

    Recommendations

    -
      -
    1. Where multiple fields exist and can be added and removed, put -them inside a separate element so that the selectors can successfully -identify them. Otherwise, changing element orders can result in the -wrong element being selected.
    2. -
    3. Make sure that transformations on the input document produce all -the necessary elements for the output document so that the resulting -page gives the user the opportunity to specify data that is missing.
    4. +
    5. Recommendations and advice