# HG changeset patch
# User paulb
# Date 1121541913 0
# Node ID debf541a8a13d8081f611b4f76d2dba26a791b51
# Parent cc2a24baff916fc58e1fed2ec4179d689f26a558
[project @ 2005-07-16 19:25:13 by paulb]
Added introductory documentation, moving the overview into its own HTML
document.
diff -r cc2a24baff91 -r debf541a8a13 docs/index.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/index.html Sat Jul 16 19:25:13 2005 +0000
@@ -0,0 +1,42 @@
+
+
+
+
+ Developing Web Applications with XSLTools
+
+
+
+
+
Developing Web Applications with XSLTools
+
This documentation introduces the XSLTools package and the XSLForms
+framework for developing forms-based Web applications using Python, libxml2dom,
+libxml2, libxslt and (optionally) WebStack.
+
Setting Up
+
First of all, let us assume that the XSLTools distribution has been
+unpacked and now sits in the XSLTools-0.1 directory.
+
Before we begin, we must make sure that the XSLTools package is
+available
+to Python. The easiest way to do this is to change into the XSLTools-0.1
+directory and to run the setup.py
+script provided with the version of Python you are going to be using
+(possibly as a privileged user like root):
+
cd XSLTools-0.1 python setup.py install
+
If you don't want to install XSLTools in this way, or if you can't
+do so
+because you don't have root privileges, you can just make
+sure
+that the XSLTools-0.1 directory sits on your
+PYTHONPATH.
+
Viewing the API Documentation
+
The API documentation for use in conjunction with this
+guide can be found inside the apidocs
+directory within the XSLTools-0.1 directory. Of course,
+it is always possible to view the API documentation
+within Python by importing modules (such as XSLOutput)
+and using Python's built-in help function.
The following steps briefly describe how to make a new application:
+
+
+
Design a template, adding forms and fields. In the beginning, it
+is not that important to use the correct names in each of the fields -
+these will be added later.
+
Add structural template attributes such as template:element,
+template:attribute and template:value so that the fields sit in
+different parts of the input document format being modelled. Replace
+the field names with special functions such as template:field-name().
+For buttons which add and remove parts of the input document, employ
+selector notation and the template:this-position() function.
+
Where multiple choice fields are employed, input documents must
+be transformed so that the multiple choice options are included in the
+output. This can be achieved using documents containing the different
+option values and transformations which insert those values into the
+input document.
+
To produce the output document, the template needs preparing
+first so that an output stylesheet is produced; then, the output
+stylesheet is applied to the processed input document utilising various
+extension functions which produce the computed field names in the final
+output document.
+
+
Recommendations
+
+
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.
+
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.