paulb@104 | 1 | Introduction
|
paulb@104 | 2 | ------------
|
paulb@76 | 3 |
|
paulb@104 | 4 | XSLTools is a collection of modules and packages facilitating the development
|
paulb@104 | 5 | of applications based on XML, XSL stylesheets and transformations, notably Web
|
paulb@104 | 6 | applications involving complicated Web forms potentially consisting of
|
paulb@104 | 7 | editable hierarchical structures and potentially involving "live" or "in-page"
|
paulb@104 | 8 | dynamic updates to portions of those Web forms.
|
paulb@28 | 9 |
|
paulb@109 | 10 | Quick Start
|
paulb@109 | 11 | -----------
|
paulb@109 | 12 |
|
paulb@109 | 13 | Try running the demo:
|
paulb@109 | 14 |
|
paulb@109 | 15 | python tools/demo.py
|
paulb@109 | 16 |
|
paulb@109 | 17 | An introductory guide to creating applications can be found in the docs
|
paulb@109 | 18 | directory - see docs/index.html for the start page.
|
paulb@109 | 19 |
|
paulb@109 | 20 | Contact, Copyright and Licence Information
|
paulb@109 | 21 | ------------------------------------------
|
paulb@109 | 22 |
|
paulb@109 | 23 | The current Web page for XSLTools at the time of release is:
|
paulb@109 | 24 |
|
paulb@109 | 25 | http://www.boddie.org.uk/python/XSLTools.html
|
paulb@109 | 26 |
|
paulb@109 | 27 | Copyright and licence information can be found in the docs directory - see
|
paulb@115 | 28 | docs/LICENCE.txt and docs/LICENCE-Sarissa.txt for more information.
|
paulb@109 | 29 |
|
paulb@104 | 30 | Dependencies
|
paulb@104 | 31 | ------------
|
paulb@104 | 32 |
|
paulb@104 | 33 | XSLTools has the following basic dependencies:
|
paulb@28 | 34 |
|
paulb@104 | 35 | Package Release Information
|
paulb@104 | 36 | ------- -------------------
|
paulb@104 | 37 |
|
paulb@104 | 38 | libxml2dom 0.2
|
paulb@104 | 39 | libxml2 2.6.16
|
paulb@104 | 40 | libxslt 1.1.12
|
paulb@28 | 41 |
|
paulb@104 | 42 | The example Web applications require WebStack (release 0.10 or later).
|
paulb@104 | 43 |
|
paulb@104 | 44 | Notes on In-Page Update Functionality
|
paulb@104 | 45 | -------------------------------------
|
paulb@28 | 46 |
|
paulb@125 | 47 | Special note: Konqueror seems to remember replaced form content (when
|
paulb@125 | 48 | replaceChild is used to replace regions of the page which include form
|
paulb@125 | 49 | elements). This causes the browser to believe that more form fields exist on
|
paulb@125 | 50 | the page than actually do so, and subsequent form submissions thus include the
|
paulb@125 | 51 | values of such removed fields. A special hack is in place to disable form
|
paulb@125 | 52 | fields by changing their names, thus causing Konqueror to not associate such
|
paulb@125 | 53 | fields with the real, active fields; this hack does not seem to cause problems
|
paulb@125 | 54 | for Mozilla.
|
paulb@125 | 55 |
|
paulb@104 | 56 | Various browsers (eg. Mozilla/Firefox, Konqueror) will not allow the
|
paulb@104 | 57 | XMLHttpRequest in-page updates to function unless the application URL defined
|
paulb@104 | 58 | within the Configurator application (and other relevant applications) matches
|
paulb@104 | 59 | the URL at which the browser finds the application. This URL is deduced by the
|
paulb@104 | 60 | various applications using the WebStack API, but it is possible that the
|
paulb@104 | 61 | values returned by that API do not match the actual addresses entered into the
|
paulb@104 | 62 | address bar of the browser.
|
paulb@28 | 63 |
|
paulb@104 | 64 | To check the behaviour of the applications, it is possible to view the
|
paulb@104 | 65 | document source of the pages served by applications and to verify that the
|
paulb@104 | 66 | URLs mentioned in the JavaScript function calls (to 'requestUpdate') involve a
|
paulb@104 | 67 | URL similar to that which appears in the browser's address bar. In some
|
paulb@104 | 68 | environments, the use of 'localhost' addresses often confuses the browser and
|
paulb@104 | 69 | server; one workaround is to use real host names or addresses instead of
|
paulb@104 | 70 | 'localhost'.
|
paulb@155 | 71 |
|
paulb@166 | 72 | Choosing an element-path:
|
paulb@166 | 73 |
|
paulb@166 | 74 | When specifying the "context" of the in-page update, one must imagine which
|
paulb@166 | 75 | element the template fragment should operate within. If the template:id
|
paulb@166 | 76 | attribute marks a particular section, then the element-path should be a path
|
paulb@166 | 77 | to the applicable context element for that section in the complete template
|
paulb@166 | 78 | document. Note that if a template:element attribute appears on the same
|
paulb@166 | 79 | element as the template:id attribute then the element-path should refer to the
|
paulb@166 | 80 | element specified in the template:element attribute.
|
paulb@166 | 81 |
|
paulb@166 | 82 | Choosing where to put template:attribute, template:id and id:
|
paulb@166 | 83 |
|
paulb@166 | 84 | When specifying the extent of a template fragment, one must be sure not to put
|
paulb@166 | 85 | the template:id attribute on the same element as a template:attribute
|
paulb@166 | 86 | annotation; otherwise, the generated code will be improperly extracted as a
|
paulb@166 | 87 | fragment producing two versions of the element - one for when the specified
|
paulb@166 | 88 | attribute is present, and one for when it is not present. Generally,
|
paulb@166 | 89 | template:id and id can be placed on the same node, however.
|
paulb@173 | 90 |
|
paulb@173 | 91 | Stable element ordering and element-path:
|
paulb@173 | 92 |
|
paulb@173 | 93 | Within the element-path, the numbering of the elements will start at 1.
|
paulb@173 | 94 | Therefore it is vital to choose a region of the form data structure with the
|
paulb@173 | 95 | element-path which is isolated from surrounding elements whose positions would
|
paulb@173 | 96 | otherwise be dependent on a stable ordering of elements, and whose processing
|
paulb@173 | 97 | would be disrupted if some new elements suddenly appeared claiming the same
|
paulb@173 | 98 | positions in the document. For example:
|
paulb@173 | 99 |
|
paulb@173 | 100 | <item value=""> .../item$1/value
|
paulb@173 | 101 | <type value=""/> .../item$1/type$1/value
|
paulb@173 | 102 | <comment value=""/> .../item$1/comment$2/value
|
paulb@173 | 103 | </item>
|
paulb@173 | 104 |
|
paulb@173 | 105 | In-page update...
|
paulb@173 | 106 |
|
paulb@173 | 107 | <comment value=""/> .../item$1/comment$1/value
|
paulb@173 | 108 |
|
paulb@173 | 109 | Notes on XSL
|
paulb@173 | 110 | ------------
|
paulb@173 | 111 |
|
paulb@173 | 112 | libxslt seems to be quite liberal on the definition of runtime parameters, in
|
paulb@173 | 113 | that there is no apparent need to explicitly declare the corresponding global
|
paulb@173 | 114 | variables in stylesheets. Whilst this is nice, we may eventually need to
|
paulb@173 | 115 | detect such variables and add them in the preparation process.
|