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@185 | 39 | libxml2 Tested with 2.6.17
|
paulb@185 | 40 | libxslt Tested with 1.1.12
|
paulb@28 | 41 |
|
paulb@104 | 42 | The example Web applications require WebStack (release 0.10 or later).
|
paulb@104 | 43 |
|
paulb@190 | 44 | New in XSLTools 0.2 (Changes since XSLTools 0.1)
|
paulb@190 | 45 | ------------------------------------------------
|
paulb@190 | 46 |
|
paulb@190 | 47 | Added XMLTable.
|
paulb@190 | 48 |
|
paulb@104 | 49 | Notes on In-Page Update Functionality
|
paulb@104 | 50 | -------------------------------------
|
paulb@28 | 51 |
|
paulb@185 | 52 | Special note #1: Konqueror seems in certain cases to remember replaced form
|
paulb@185 | 53 | content (when replaceChild is used to replace regions of the page which
|
paulb@185 | 54 | include form elements). This causes the browser to believe that more form
|
paulb@185 | 55 | fields exist on the page than actually do so, and subsequent form submissions
|
paulb@185 | 56 | thus include the values of such removed fields. A special hack is in place to
|
paulb@185 | 57 | disable form fields by changing their names, thus causing Konqueror to not
|
paulb@185 | 58 | associate such fields with the real, active fields; this hack does not seem to
|
paulb@185 | 59 | cause problems for Mozilla. This needs some investigation to determine in
|
paulb@185 | 60 | exactly which circumstances the problem arises.
|
paulb@185 | 61 |
|
paulb@185 | 62 | Special note #2: Konqueror also seems to crash if asked to find elements using
|
paulb@185 | 63 | an empty 'id' attribute string. This needs some investigation to see if it
|
paulb@185 | 64 | really is the getElementById call that causes the crash.
|
paulb@125 | 65 |
|
paulb@104 | 66 | Various browsers (eg. Mozilla/Firefox, Konqueror) will not allow the
|
paulb@185 | 67 | XMLHttpRequest in-page updates to function unless the URL used in the
|
paulb@185 | 68 | requestUpdate JavaScript function is compatible with the URL at which the
|
paulb@185 | 69 | browser finds the application. Currently, relative URLs are in use to avoid
|
paulb@185 | 70 | this issue of compatibility, but should an absolute URL be deduced using the
|
paulb@185 | 71 | WebStack API and then used, it may be possible that the values returned by
|
paulb@185 | 72 | that API do not match the actual addresses entered into the address bar of the
|
paulb@185 | 73 | browser.
|
paulb@28 | 74 |
|
paulb@104 | 75 | To check the behaviour of the applications, it is possible to view the
|
paulb@104 | 76 | document source of the pages served by applications and to verify that the
|
paulb@185 | 77 | URLs mentioned in the JavaScript function calls (to 'requestUpdate') either be
|
paulb@185 | 78 | a relative link or involve a URL similar to that which appears in the
|
paulb@185 | 79 | browser's address bar. In some environments, the use of 'localhost' addresses
|
paulb@185 | 80 | often confuses the browser and server; one workaround is to use real host
|
paulb@185 | 81 | names or addresses instead of 'localhost'.
|
paulb@155 | 82 |
|
paulb@166 | 83 | Choosing an element-path:
|
paulb@166 | 84 |
|
paulb@166 | 85 | When specifying the "context" of the in-page update, one must imagine which
|
paulb@166 | 86 | element the template fragment should operate within. If the template:id
|
paulb@166 | 87 | attribute marks a particular section, then the element-path should be a path
|
paulb@166 | 88 | to the applicable context element for that section in the complete template
|
paulb@166 | 89 | document. Note that if a template:element attribute appears on the same
|
paulb@166 | 90 | element as the template:id attribute then the element-path should refer to the
|
paulb@166 | 91 | element specified in the template:element attribute.
|
paulb@166 | 92 |
|
paulb@166 | 93 | Choosing where to put template:attribute, template:id and id:
|
paulb@166 | 94 |
|
paulb@166 | 95 | When specifying the extent of a template fragment, one must be sure not to put
|
paulb@166 | 96 | the template:id attribute on the same element as a template:attribute
|
paulb@166 | 97 | annotation; otherwise, the generated code will be improperly extracted as a
|
paulb@166 | 98 | fragment producing two versions of the element - one for when the specified
|
paulb@166 | 99 | attribute is present, and one for when it is not present. Generally,
|
paulb@166 | 100 | template:id and id can be placed on the same node, however.
|
paulb@173 | 101 |
|
paulb@173 | 102 | Stable element ordering and element-path:
|
paulb@173 | 103 |
|
paulb@173 | 104 | Within the element-path, the numbering of the elements will start at 1.
|
paulb@173 | 105 | Therefore it is vital to choose a region of the form data structure with the
|
paulb@173 | 106 | element-path which is isolated from surrounding elements whose positions would
|
paulb@173 | 107 | otherwise be dependent on a stable ordering of elements, and whose processing
|
paulb@173 | 108 | would be disrupted if some new elements suddenly appeared claiming the same
|
paulb@173 | 109 | positions in the document. For example:
|
paulb@173 | 110 |
|
paulb@173 | 111 | <item value=""> .../item$1/value
|
paulb@173 | 112 | <type value=""/> .../item$1/type$1/value
|
paulb@173 | 113 | <comment value=""/> .../item$1/comment$2/value
|
paulb@173 | 114 | </item>
|
paulb@173 | 115 |
|
paulb@173 | 116 | In-page update...
|
paulb@173 | 117 |
|
paulb@173 | 118 | <comment value=""/> .../item$1/comment$1/value
|
paulb@173 | 119 |
|
paulb@173 | 120 | Notes on XSL
|
paulb@173 | 121 | ------------
|
paulb@173 | 122 |
|
paulb@173 | 123 | libxslt seems to be quite liberal on the definition of runtime parameters, in
|
paulb@173 | 124 | that there is no apparent need to explicitly declare the corresponding global
|
paulb@173 | 125 | variables in stylesheets. Whilst this is nice, we may eventually need to
|
paulb@173 | 126 | detect such variables and add them in the preparation process.
|
paulb@184 | 127 |
|
paulb@184 | 128 | Release Procedures
|
paulb@184 | 129 | ------------------
|
paulb@184 | 130 |
|
paulb@184 | 131 | Update the XSLOutput.py and XSLForms/__init__.py __version__ attributes.
|
paulb@184 | 132 | Change the version number and package filename/directory in the documentation.
|
paulb@184 | 133 | Change code examples in the documentation if appropriate.
|
paulb@184 | 134 | Update the release notes (see above).
|
paulb@184 | 135 | Check the setup.py file and ensure that all package directories are mentioned.
|
paulb@184 | 136 | Tag, export.
|
paulb@184 | 137 | Generate the API documentation.
|
paulb@184 | 138 | Remove generated .pyc files: rm `find . -name "*.pyc"`
|
paulb@184 | 139 | Archive, upload.
|
paulb@184 | 140 | Upload the introductory documentation.
|
paulb@184 | 141 | Update PyPI, PythonInfo Wiki, Vaults of Parnassus entries.
|
paulb@184 | 142 |
|
paulb@184 | 143 | Generating the API Documentation
|
paulb@184 | 144 | --------------------------------
|
paulb@184 | 145 |
|
paulb@184 | 146 | In order to prepare the API documentation, it is necessary to generate some
|
paulb@184 | 147 | Web pages from the Python source code. For this, the epydoc application must
|
paulb@184 | 148 | be available on your system. Then, inside the XSLTools directory, run the
|
paulb@184 | 149 | apidocs.sh tool script as follows:
|
paulb@184 | 150 |
|
paulb@184 | 151 | ./tools/apidocs.sh
|
paulb@184 | 152 |
|
paulb@184 | 153 | Some warnings may be generated by the script, but the result should be a new
|
paulb@184 | 154 | apidocs directory within the XSLTools directory.
|