| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
| <chapter> |
| <?dbhtml filename="editor/xsleditor.html" ?> |
| <title>XSL Editing</title> |
| <para> |
| The XSL Tools plugins extend the ability of the Web Standard |
| Tools XML |
| editor. This extension adds specific |
| support and |
| functionality for |
| working with and debugging XSL files. |
| </para> |
| <section id="Validation"> |
| <?dbhtml filename="editor/xsleditor_validation.html" ?> |
| <title>Validation</title> |
| <para> |
| The XSL extensions for the eclipse XML editor include as you |
| type |
| validation for XSL specific features. This |
| includes not |
| only the |
| ability to syntax check the grammar, but to also to validate |
| specific |
| XSL specification |
| rules. Grammar validation will |
| be triggered based on |
| the version attribute for the style sheet that is |
| being |
| edited. Valid |
| version numbers are 1.0, and 2.0. |
| </para> |
| </section> |
| <section id="ContentAssist"> |
| <?dbhtml filename="editor/xsleditor_contentassist.html" ?> |
| <title>Content Assist</title> |
| <para> |
| XSL Tools extends the existing content assistance support of the |
| XML Editor to provide content assistance for |
| several XSL namespace |
| attributes. The content assistance provided covers the available XPath |
| statements as |
| defined in the |
| <emphasis>XPath Templates</emphasis> |
| preference page. |
| </para> |
| <important> |
| <title>XPath 2.0 Support</title> |
| <para> |
| Currently XPath 2.0 is not supported directly. However, a user |
| can add this support if they need it by |
| adding the missing XPath |
| functions to the XPath Templates. |
| </para> |
| </important> |
| <para> |
| To initiate content assistance press CTRL + SPACE or CMD + SPACE. This will bring up |
| a dialog that will |
| contain any proposals that are available. If no proposals are available |
| an message will be displayed in the |
| status bar. |
| </para> |
| <section id="ed_XSLProposals"> |
| <title>XSLT Element Proposals</title> |
| <para> |
| Since XSLT is a templating language, it's elements must be able to be added |
| to the various markup it |
| includes. The XSLT Editor will provide content assistance |
| and proposals for XSLT elements that are available |
| to be used within non-XSLT namespaced |
| elements. This is depicted in |
| <xref linkend="fig_XSLProposals" /> |
| . |
| </para> |
| <figure id="fig_XSLProposals"> |
| <title>XSLT Proposals within Non-XSLT elements</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata align="center" fileref="../images/editor/xslproposals.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| </section> |
| <section id="SelectTest"> |
| <title>Select, Test, and Match Attributes </title> |
| <para> |
| Where ever an xsl element supports a |
| <emphasis>select</emphasis> |
| , |
| <emphasis>test</emphasis> |
| , or |
| <emphasis>match</emphasis> |
| attribute, content assistance is available. This includes support for |
| the following: |
| </para> |
| <itemizedlist> |
| <title>Select, Match and Test Assistance</title> |
| <listitem> |
| <para> |
| <emphasis>Variables</emphasis> |
| - both local and global variables are supported within the current |
| stylesheet. Any local or global |
| variable will be added to the list |
| and the name is prefixed with a dollar sign $ symbol. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <emphasis>XPath 1.0</emphasis> |
| - XPath 1.0 is supported through the use of templates. All of the |
| XPath 1.0 and XSLT xpath extension |
| functions are available, as well |
| as |
| <emphasis>axis</emphasis> |
| operations. Currently XPath 2.0 is not supported directly, but will |
| be added in the future. |
| </para> |
| </listitem> |
| </itemizedlist> |
| <para> |
| Content assistance for the select and test attributes is |
| intelligent enough to know that it is within an |
| XPath expression, and will try to determine and provide content assistance based on the |
| current cursor |
| position. If a word has been partially typed it will |
| filter the available assistance. |
| </para> |
| </section> |
| <section id="ExcludeResultPrefixesContentAssist"> |
| <title>Exclude-Result-Prefixes</title> |
| <para> |
| The |
| <emphasis>exclude-result-prefixes</emphasis> |
| attribute in both XSLT 1.0 and XSLT 2.0 allows for the exclusion of |
| certain namespace |
| declarations in the |
| output document. The content |
| assistance populates a list of available namespaces that have been |
| defined in |
| the |
| stylseheet and provides them as proposals as shown in |
| <xref linkend="fig_ExcludeResultPrefixesContentAssist1" /> |
| . |
| </para> |
| <figure id="fig_ExcludeResultPrefixesContentAssist1"> |
| <title>Exclude-result-prefixes Content |
| Assistance</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata align="center" fileref="../images/editor/ExcludeContentAssist1.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| <para> |
| If the attribute has no values defined, then the |
| <emphasis>#all</emphasis> |
| value will be available in the list. If #all |
| is already in the |
| attributes value, then no content assistance |
| will be available. |
| </para> |
| <figure id="fig_ExcludeResultPrefixesContentAssist2"> |
| <title>Filtered exclude-result-prefixes proposals</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata align="center" fileref="../images/editor/ExcludeContentAssist2.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| <para> |
| Content assistance is intelligent enough to know when a |
| namespace prefix is already in the list of |
| excluded namespaces. In |
| this |
| case it will not show the namespace in the proposal list. |
| </para> |
| <note> |
| <title>Why isn't the XSL Namespace prefix in the proposals? |
| </title> |
| <para> |
| Currently the xsl prefix or any prefix that uses the XSL |
| namespace is excluded from the list. This may |
| be changed at |
| a future |
| date. This will depend on user feedback. |
| </para> |
| </note> |
| </section> |
| <section id="ed_ModeAssist"> |
| <title>Mode attribute assistance</title> |
| <para> |
| Content assistance is available for those xsl elements that support the mode attribute. For XSLT 1.0 |
| these |
| elements are |
| <emphasis>template</emphasis> |
| , |
| <emphasis>apply-templates</emphasis> |
| , and |
| <emphasis>apply-imports</emphasis> |
| . |
| </para> |
| <figure id="fig_ModeAssistance"> |
| <title>Mode attribute assistance</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata format="PNG" align="center" fileref="../images/editor/modeAssistance.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| <para> |
| The proposal list is populated by those modes defined on templates in the current stylesheet, and any |
| of the |
| templates that are |
| <emphasis>included</emphasis> |
| or |
| <emphasis>imported</emphasis> |
| . |
| </para> |
| </section> |
| <section id="ed_CallTemplateAssist"> |
| <title>Call-Template Assistance</title> |
| <para> |
| Any |
| <emphasis>call-template</emphasis> |
| xslt element has content assistance available for |
| it's name attribute. This will provide a list of possible |
| XSLT named templates that can |
| be called from the current stylesheet. This takes into effect all included and |
| imported |
| stylesheets as well as those defined in the current stylesheet. |
| </para> |
| <figure id="fig_CallTemplateAssist"> |
| <title>Call-Template Assistance</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata align="center" fileref="../images/editor/calltemplate.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| |
| </section> |
| <section id="ed_href"> |
| <title> |
| Include and Import |
| <emphasis>href</emphasis> |
| Assistance |
| </title> |
| <para> |
| XSLT stylesheets have the ability to import and include other stylesheets. This allows for |
| a modular |
| structure for the templates to be created. It also allows for easier maintenance. |
| However, if one is working |
| with a large project like the DocBook Projects stylesheets it can |
| be difficult to remember the names and |
| locations of all the stylesheets. |
| </para> |
| <para> |
| To this end, the XSLT editor provides content assistance for the |
| <emphasis>href</emphasis> |
| attribute. The scope of the assistance is restricted to the project that the current |
| stylesheet that is being |
| editted resides. |
| </para> |
| <figure id="fig_HREFAssistance"> |
| <title>Include/Import href Assistance</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata align="center" fileref="../images/editor/hrefAssistance.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| </section> |
| </section> |
| <section id="XSLEditorTemplates"> |
| <?dbhtml filename="editor/xsleditor_templates.html" ?> |
| <title>Templates</title> |
| <para> |
| Specific XSL code completion templates can be added to the XML |
| editor's Templates. This allows a user to |
| define specific markup |
| completion templates that are commonly used. In addition, the XPath |
| Templates page can be |
| enhanced to allow commonly used XPath templates |
| to be included, in addition to those installed by default. |
| This |
| allows a user the ability to add custom extension functions for XSLT that |
| may be processor specific. Adopters |
| may also use the standard template |
| extension point to add additional functionality. |
| </para> |
| <section> |
| <?dbhtml filename="editor/xsleditor_xpathtemplates.html" ?> |
| <title>XPath Templates</title> |
| <para> |
| The XSL XPath Templates preference page allows for a user or |
| adopter to add specific xpath extensions so |
| that |
| they show up in the |
| content assistance. See the XPath Templates documentation for more |
| information. |
| </para> |
| </section> |
| </section> |
| <section id="xsltMarkers"> |
| <?dbhtml filename="editor/xsleditor_markers.html" ?> |
| <title>XSLT Markers and Annotations</title> |
| <para> |
| The XSL editor supports the ability to annotate or provide markers. These annotations provide additional |
| information about the templates and XSLT elements in the stylesheet. |
| </para> |
| <section id="xsltOverRide"> |
| <title>Template Over Ride</title> |
| <para> |
| The XSLT editor will mark templates that have overriden an imported template of the same name. |
| </para> |
| <figure id="fig_OverRide1"> |
| <title>Overriden Template</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata align="center" fileref="../images/editor/override1.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| <para> |
| In |
| <xref linkend="fig_OverRide1" /> |
| , the template "TempB" overrides an imported template. By |
| moving the mouse pointer over the triangle icon in |
| the rule bar, information about which file |
| the original template resides. |
| </para> |
| <figure id="fig_OverRide2"> |
| <title>Overriden Template Information</title> |
| <mediaobject> |
| <imageobject> |
| <imagedata align="center" fileref="../images/editor/override2.png" /> |
| </imageobject> |
| </mediaobject> |
| </figure> |
| </section> |
| </section> |
| <section id="XSLEditorDebugging"> |
| <?dbhtml filename="editor/xsleditor_debugging.html" ?> |
| <title>XSL Debugging</title> |
| <para> |
| The XSL Editor supports the ability to specify break points within an XSL File. If the file is included or |
| imported and the break point is encountered during a transformation scenario it will be respected. A break |
| point may be set at any valid XSL element or other xml element within the XSLT stylesheet. See the Launching |
| and Debugging section for more information on debugging XSLT stylesheets. |
| </para> |
| </section> |
| </chapter> |