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.
|