1 Introduction
2 ------------
3
4 XSLTools is a collection of modules and packages facilitating the development
5 of applications based on XML, XSL stylesheets and transformations, notably Web
6 applications involving complicated Web forms potentially consisting of
7 editable hierarchical structures and potentially involving "live" or "in-page"
8 dynamic updates to portions of those Web forms.
9
10 Quick Start
11 -----------
12
13 Try running the demo:
14
15 python tools/demo.py
16
17 An introductory guide to creating applications can be found in the docs
18 directory - see docs/index.html for the start page.
19
20 Contact, Copyright and Licence Information
21 ------------------------------------------
22
23 The current Web page for XSLTools at the time of release is:
24
25 http://www.boddie.org.uk/python/XSLTools.html
26
27 Copyright and licence information can be found in the docs directory - see
28 docs/COPYING.txt, docs/LICENCE.txt and docs/LICENCE-Sarissa.txt for more
29 information.
30
31 Dependencies
32 ------------
33
34 XSLTools has the following basic dependencies:
35
36 Packages Release Information
37 -------- -------------------
38
39 libxml2dom 0.4.3
40 libxml2 and libxslt Some combinations may not be reliable!
41 Tested with libxml2 2.6.17 and libxslt 1.1.12
42 Tested with libxml2 2.6.27 and libxslt 1.1.20
43
44 The example Web applications require WebStack (release 1.2.3 or later).
45 The example PyQt applications have been tested with PyQt 3.15.
46
47 New in XSLTools 0.4.6 (Changes since XSLTools 0.4.5)
48 ----------------------------------------------------
49
50 * Improved the Login module, enabling the VerySimpleWithLogin example for
51 various frameworks.
52 * Relicensed under the LGPL version 3 or later.
53 * Upgraded to Sarissa 0.9.7.8 (compatible with LGPL/GPL version 3), removing
54 a test around DOMParser so that Konqueror 3.4.0 is still supported.
55
56 New in XSLTools 0.4.5 (Changes since XSLTools 0.4.4)
57 ----------------------------------------------------
58
59 * Fixed the result of transformations in XSLOutput: proper document nodes
60 are now produced.
61 * Added an XSLForms.Resources.Login module which provides resources to
62 support login screens and redirects.
63 * Fixed newlines in the attributes created from fields in XSLForms: CR
64 characters are no longer included since this caused the doubling up of
65 newlines in Firefox.
66
67 New in XSLTools 0.4.4 (Changes since XSLTools 0.4.3)
68 ----------------------------------------------------
69
70 * Fixed translation selection for the template:i18n annotation attribute,
71 not just for the template:i18n extension function - more apologies for
72 resulting output changes!
73 * Improved the template fixing stylesheet and added some documentation for
74 the script and the related expr-prefix attribute.
75 * Introduced WebStack 1.2.2 EncodingSelector and encoding changes.
76 * Added docstring and return value for the write_month_to_document function
77 in XSLTools.XMLCalendar.
78
79 New in XSLTools 0.4.3 (Changes since XSLTools 0.4.2)
80 ----------------------------------------------------
81
82 * Fixed translation selection when an unsupported locale is specified,
83 choosing the first locale as the default (rather than exposing the values
84 themselves as translations). Note that this is an unfortunate and subtle
85 change which may affect application output - apologies are hereby offered!
86
87 New in XSLTools 0.4.2 (Changes since XSLTools 0.4.1)
88 ----------------------------------------------------
89
90 * Added a content type check in the XSLFormsResource class, permitting
91 non-form-based resources to access the raw request data, rather than have
92 the data processed unsuccessfully and consequently discarded.
93 * Added a script and a function to fix template namespaces after editing in
94 a careless editor.
95 * Changed libxml2mod and libxsltmod import details to try libxmlmods -
96 suggested by Lucian Wischik for libxml2dom.
97
98 New in XSLTools 0.4.1 (Changes since XSLTools 0.4)
99 --------------------------------------------------
100
101 * Made translations specified using the template:i18n annotation take
102 priority over template:value annotations.
103 * Added expression-based template:i18n annotations, and provided fallback
104 output for such translations based on the value of the evaluated
105 expression.
106
107 New in XSLTools 0.4 (Changes since XSLTools 0.3.1)
108 --------------------------------------------------
109
110 * Changed the preparation of templates to produce rule-based output
111 stylesheets, thus permitting recursive templates. This requires an extra
112 expr-prefix annotation to be used in certain kinds of templates.
113 * Added a recursive template example application.
114 * Changed fragment production to use original template documents instead of
115 output stylesheets.
116 * Changed the in_page_resources attribute to provide the output identifier,
117 thus changing the prepare_fragment method in Web resources so that only
118 the fragment identifier needs to be supplied.
119 * Added the XSLForms.Resources.WebResources.prepare_resources method for the
120 preparation of initialiser and output stylesheets before an application is
121 run.
122 * Changed selectors to not automatically create elements in the form data
123 document unless requested to do so. Introduced a Form.get_selector
124 method in XSLForms.Fields.
125 * Permitted the creation of hierarchies of elements in
126 XSLForms.Utils.add_elements.
127 * Introduced dynamic parameter evaluation for multiple-choice fields in
128 order to support sources of multiple-choice values which reside in the
129 form data document itself.
130 * Added the FixNamespace.xsl stylesheet to correct documents saved by HTML
131 editors which strip namespace prefixes.
132 * Fixed filesystem encoding issues in the Candidate example; fixed language
133 preference access in the Configurator and VerySimple examples.
134 * Changed the BaseHTTPRequestHandler version of the Candidate example to
135 store data in a subdirectory of the current working directory, thus
136 allowing the demonstration application to work after package installation.
137
138 New in XSLTools 0.3.1 (Changes since XSLTools 0.3)
139 --------------------------------------------------
140
141 * Fixed copyright and licensing information.
142
143 New in XSLTools 0.3 (Changes since XSLTools 0.2)
144 ------------------------------------------------
145
146 * Introduced copying of multiple-choice value element contents so that
147 option element labels can differ from the underlying values.
148 * Added internationalisation support, providing the template:i18n annotation
149 and the template:i18n extension function.
150 * Updated the documentation to cover the above new features.
151 * Fixed non-GET/POST request method handling in WebResources.
152 * Added the xslform_preparemacro.py script.
153 * Added an experimental template:range extension function.
154
155 New in XSLTools 0.2 (Changes since XSLTools 0.1)
156 ------------------------------------------------
157
158 * Made a new XSLTools package and moved XSLOutput into it.
159 * Improved serialisation of transformation results so that output options
160 are observed (in some cases, at least).
161 * Fixed stylesheet and reference document paths so that libxslt should not
162 now become confused by ambiguous relative paths.
163 * Added expression parameters to XSLOutput.Processor so that in-document
164 data can be used to, for example, initialise multiple-choice field values.
165 * Added input/initialiser support so that input documents can be tidied or
166 initialised using information from the template.
167 * Added template:init for use with template:element in XSLForms to control
168 element initialisation where necessary.
169 * Added special high-level "macro" attributes (eg. template:attribute-field)
170 which should make templates easier to write and maintain.
171 * Added template:if to XSLForms, providing conditional output of annotated
172 elements.
173 * Added set_document to XSLForms.Fields.Form.
174 * Added prepare_parameters to the XSLFormsResource class in the
175 XSLForms.Resources.WebResources module.
176 * Added element-path, url-encode and choice XSLForms extension functions.
177 * Improved Unicode support in the XSLForms extension functions.
178 * Changed in-page requests to contain proper POST data.
179 * Fixed checkbox and radiobutton value detection in XSLForms.js.
180 * Updated the code to work with WebStack 1.0 changes and adopted the
181 new-style WebStack demonstration mechanism.
182 * Added XMLCalendar and XMLTable (to the XSLTools package).
183 * Added a dictionary (or word lookup) example application.
184 * Added a job candidate profile (or CV editor) example application.
185 * Added a template attribute reference and an XSLFormsResource guide to the
186 documentation.
187 * Added Debian package support (specifically Ubuntu package support).
188 * Added missing COPYING.txt file.
189 * Renamed the scripts to avoid naming issues in system-wide installations.
190 * Added a PyQt example based on the system configurator example, with the
191 form prepared in Qt Designer. This example runs in PyQt and in a Web
192 environment without any changes to the application code. In-page updates
193 are currently not implemented in the Web version, however.
194
195 Notes on In-Page Update Functionality
196 -------------------------------------
197
198 Special note #1: Konqueror seems in certain cases to remember replaced form
199 content (when replaceChild is used to replace regions of the page which
200 include form elements). This causes the browser to believe that more form
201 fields exist on the page than actually do so, and subsequent form submissions
202 thus include the values of such removed fields. A special hack is in place to
203 disable form fields by changing their names, thus causing Konqueror to not
204 associate such fields with the real, active fields; this hack does not seem to
205 cause problems for Mozilla. This needs some investigation to determine in
206 exactly which circumstances the problem arises.
207
208 Special note #2: Konqueror also seems to crash if asked to find elements using
209 an empty 'id' attribute string. This needs some investigation to see if it
210 really is the getElementById call that causes the crash.
211
212 Special note #3: Konqueror's XMLHttpRequest seems to append null characters to
213 the end of field values. Attempting to prune them before the request is sent
214 fails with a function like the following:
215
216 function fixValue(fieldValue) {
217 if (fieldValue.length == 0) {
218 return fieldValue;
219 } else if (fieldValue[fieldValue.length - 1] == '\0') {
220 return fieldValue.substr(0, fieldValue.length - 1);
221 } else {
222 return fieldValue;
223 }
224 }
225
226 This may be because it is the entire message that is terminated with the null
227 character, and that this happens only upon sending the message. Consequently,
228 some frameworks (notably mod_python) do not support in-page functionality when
229 used from Konqueror.
230
231 Various browsers (eg. Mozilla/Firefox, Konqueror) will not allow the
232 XMLHttpRequest in-page updates to function unless the URL used in the
233 requestUpdate JavaScript function is compatible with the URL at which the
234 browser finds the application. Currently, relative URLs are in use to avoid
235 this issue of compatibility, but should an absolute URL be deduced using the
236 WebStack API and then used, it may be possible that the values returned by
237 that API do not match the actual addresses entered into the address bar of the
238 browser.
239
240 To check the behaviour of the applications, it is possible to view the
241 document source of the pages served by applications and to verify that the
242 URLs mentioned in the JavaScript function calls (to 'requestUpdate') either be
243 a relative link or involve a URL similar to that which appears in the
244 browser's address bar. In some environments, the use of 'localhost' addresses
245 often confuses the browser and server; one workaround is to use real host
246 names or addresses instead of 'localhost'.
247
248 Choosing an element-path:
249
250 When specifying the "context" of the in-page update, one must imagine which
251 element the template fragment should operate within. If the template:id
252 attribute marks a particular section, then the element-path should be a path
253 to the applicable context element for that section in the complete template
254 document. Note that if a template:element attribute appears on the same
255 element as the template:id attribute then the element-path should refer to the
256 element specified in the template:element attribute.
257
258 Choosing where to put template:attribute, template:id and id:
259
260 When specifying the extent of a template fragment, one must be sure not to put
261 the template:id attribute on the same element as a template:attribute
262 annotation; otherwise, the generated code will be improperly extracted as a
263 fragment producing two versions of the element - one for when the specified
264 attribute is present, and one for when it is not present. Generally,
265 template:id and id can be placed on the same node, however.
266
267 Stable element ordering and element-path:
268
269 Within the element-path, the numbering of the elements will start at 1.
270 Therefore it is vital to choose a region of the form data structure with the
271 element-path which is isolated from surrounding elements whose positions would
272 otherwise be dependent on a stable ordering of elements, and whose processing
273 would be disrupted if some new elements suddenly appeared claiming the same
274 positions in the document. For example:
275
276 <item value=""> .../item$1/value
277 <type value=""/> .../item$1/type$1/value
278 <comment value=""/> .../item$1/comment$2/value
279 </item>
280
281 In-page update...
282
283 <comment value=""/> .../item$1/comment$1/value
284
285 Notes on XSL
286 ------------
287
288 libxslt seems to be quite liberal on the definition of runtime parameters, in
289 that there is no apparent need to explicitly declare the corresponding global
290 variables in stylesheets. Whilst this is nice, we may eventually need to
291 detect such variables and add them in the preparation process.
292
293 Release Procedures
294 ------------------
295
296 Update the XSLTools/__init__.py and XSLForms/__init__.py __version__
297 attributes.
298 Change the version number and package filename/directory in the documentation.
299 Change code examples in the documentation if appropriate.
300 Update the release notes (see above).
301 Check the setup.py file and ensure that all package directories are mentioned.
302 Check the release information in the PKG-INFO file and in the package
303 changelog (and other files).
304 Tag, export.
305 Generate the example resources.
306 Generate the API documentation.
307 Remove generated .pyc files: rm `find . -name "*.pyc"`
308 Archive, upload.
309 Upload the introductory documentation.
310 Update PyPI, PythonInfo Wiki, Vaults of Parnassus entries.
311
312 Generating the Example Resources
313 --------------------------------
314
315 In order to prepare the example resources, the prepare_demo.py script must be
316 run as follows:
317
318 python tools/prepare_demo.py
319
320 This will ensure that all initialiser and output stylesheets are created and
321 are thus installed by packages.
322
323 Generating the API Documentation
324 --------------------------------
325
326 In order to prepare the API documentation, it is necessary to generate some
327 Web pages from the Python source code. For this, the epydoc application must
328 be available on your system. Then, inside the distribution directory, run the
329 apidocs.sh tool script as follows:
330
331 ./tools/apidocs.sh
332
333 Some warnings may be generated by the script, but the result should be a new
334 apidocs directory within the distribution directory.
335
336 Making Packages
337 ---------------
338
339 To make Debian-based packages:
340
341 1. Create new package directories under packages if necessary.
342 2. Make a symbolic link in the distribution's root directory to keep the
343 Debian tools happy:
344
345 ln -s packages/ubuntu-hoary/python2.4-xsltools/debian/
346
347 3. Run the package builder:
348
349 dpkg-buildpackage -rfakeroot
350
351 4. Locate and tidy up the packages in the parent directory of the
352 distribution's root directory.