# HG changeset patch # User paulb # Date 1131729262 0 # Node ID 6f7ef4363ea96cb08c815ea2634d9edefee24efb # Parent b77cac6d6fce3aee01e9768614214c206cc22bc9 [project @ 2005-11-11 17:14:22 by paulb] Minor documentation improvements. diff -r b77cac6d6fce -r 6f7ef4363ea9 docs/advice.html --- a/docs/advice.html Thu Nov 10 19:49:35 2005 +0000 +++ b/docs/advice.html Fri Nov 11 17:14:22 2005 +0000 @@ -13,7 +13,7 @@

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>

<multi>
  <multi-enum value="1"/>
  <multi-enum value="2"/>
  <multi-enum value="3"/>
  <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 @@ -21,8 +21,8 @@ to begin with, the usage of more advanced features (in-page updates, for example) will probably expose problems due to the way XSLForms reconstructs the XML document data -from the input form data.

Beware of Adding Elements into Mixtures of Elements

+from the input form data.

We can avoid the above mistake by specifying the first parameter in the template:multiple-choice-field and template:multiple-choice-list-field annotations. For example:

<select name="..." template:multiple-choice-field="multi,multi-enum,value">
  <option value="..." template:multiple-choice-value="multi-enum,value,selected"></option>
</select>

This effectively prevents us from inserting the nested element inside the multi element.

Beware of Adding Elements into Mixtures of Elements

Although we ignore this rule with the example in this documentation, it is necessary to be aware of problems with adding and removing elements where other elements may reside. Consider part of our form diff -r b77cac6d6fce -r 6f7ef4363ea9 docs/directory.html --- a/docs/directory.html Thu Nov 10 19:49:35 2005 +0000 +++ b/docs/directory.html Fri Nov 11 17:14:22 2005 +0000 @@ -1,20 +1,16 @@ - - + - Creating Applications: Create a Directory - - - + + Creating Applications: Create a Directory +

Creating Applications: Create a Directory

The recommended directory structure of an XSLForms application is as follows:

- +

@@ -26,10 +22,7 @@ - @@ -37,11 +30,9 @@ - - @@ -52,9 +43,5 @@

mkdir VerySimple
mkdir VerySimple/Resources
touch VerySimple/__init__.py

It is in the Resources subdirectory that we will save -our template files when designing -them as -part of the next activity in the application development process.

- - +our template files. First, however, we must undertake some data definition as the next activity in the application development process.

+ \ No newline at end of file diff -r b77cac6d6fce -r 6f7ef4363ea9 docs/template-design.html --- a/docs/template-design.html Thu Nov 10 19:49:35 2005 +0000 +++ b/docs/template-design.html Fri Nov 11 17:14:22 2005 +0000 @@ -95,14 +95,14 @@ and whilst such attributes typically reside in the form data document carrying a single, currently set value, the representation of the document processed by the template must somehow incorporate the list of -acceptable values; this was covered in the "Creating Applications: Adding Multiple-Choice Fields and Values" document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.

Single Selection Menus

See "template:multiple-choice-field" and "template:multiple-choice-value" in the "Template Attribute Reference" document.

In +acceptable values; this was covered in the "Creating Applications: Adding Multiple-Choice Fields and Values" document, and involved adding new elements, each carrying a single acceptable value for the attribute concerned.

Single Selection Menus

See "template:multiple-choice-field" and "template:multiple-choice-value" in the "Template Attribute Reference" document.
Described in the "Creating Applications: Adding Multiple-Choice Fields and Values" document.

In certain situations, it makes more sense to present acceptable values for an attribute in a menu-like representation in the final output presented to the user. With the element on which the attribute resides now containing a list of sub-elements with each carrying an acceptable value in an attribute, a form control can be defined as follows:

<select template:multiple-choice-field="-,attribute" name="...">
  <option template:multiple-choice-value="element-enum,value,selected" value="..."></option>
</select>

This would produce the following HTML form control:

Note that the element on which the attribute is defined is not declared in the above example, although we could modify the template:multiple-choice-field annotation on -the select element (as described in the "Template Attribute Reference" document) and replace the - with a name such as element.

Multiple Selection Lists

See "template:multiple-choice-list-field" and "template:multiple-choice-list-value" in the "Template Attribute Reference" document.

In +the select element (as described in the "Template Attribute Reference" document) and replace the - with a name such as element.

Multiple Selection Lists

See "template:multiple-choice-list-field" and "template:multiple-choice-list-value" in the "Template Attribute Reference" document.
Described in the "Creating Applications: Adding Multivalued Fields" document.

In other situations, where many values can be chosen, a single attribute on a single element is not sufficient to hold all such values. Consequently, a collection of elements is employed, each with an


A top-level directory corresponding to a Python package	`VerySimple +`	`VerySimple __init__.py`
A subdirectory containing non-code resources for the application	+		`Resources +`	`Resources ...`