################################################################

$RCSfile: TUTORIAL.txt,v $

Author: Craeg Strong

$Date: 2003/04/07 20:27:18 $

################################################################


Contents

  1. Getting Started

  2. Conventions

  3. Hello World

  4. Adding More Methods

  5. Creating a Cache Manager

  6. behave_like Page Template

  7. Parameterizing Transformations

  8. XSLT Pipelines

  9. URN Resolvers

  10. XML Catalogs

Getting Started
 
  Before getting started, please make sure you have read and fulfilled
  the Prerequisites section of the README file.  Installation is
  covered in INSTALL.txt.

  You will want to create a scratch folder in your Zope Management
  Interface (ZMI) where you can work.  For the purposes of the
  example, I am assuming you have created a Zope Folder in the Root
  Folder called 'scratch' ::

      Root_Folder/scratch

  Also, make sure that the Zope objects for ZopeXMLMethods appear in
  the 'Add' menu of the Zope Management Interface (ZMI).  If they do
  not, please check your prerequisites and the error log of your Zope
  instance.  The following two new options should appear::

      XSLT Method
      XML Method Cache Manager

Conventions

  I will use the ZMI and ZOPE abbreviations throughout the tutorial to
  mean Zope Management Interface and the directory in which you
  installed your Zope server, respectively.  

  I will use the ZOPEXMLMETHOD abbreviation throughout the tutorial to
  refer to the directory containing the ZopeXMLMethod product within
  your Zope installation.  On windows systems that will be::

    ZOPE\lib\python\Products\ZopeXMLMethods

  and on UNIX/Linux systems that will be::

    ZOPE/lib/python/Products/ZopeXMLMethods

  I will use the TESTFILES abbreviation throughout the tutorial to
  refer to the directory containing the testfiles for the Zopexmlmethod
  product within your Zope installation.  On windows systems that will
  be::

    ZOPE\lib\python\Products\ZopeXMLMethods\tests\testfiles

  and on UNIX/Linux systems that will be::

    ZOPE/lib/python/Products/ZopeXMLMethods/tests/testfiles

  I will assume that your Zope is running on port 8080 and the name of
  your company is acme.com, for example::

    http://www.acme.com:8080/scratch/hello

 Please substitute the real values as appropriate in the examples.

Hello World

  ADD AN XSLT
  
    In your scratch folder, select 'DTML Document' from the ZMI Add
    menu.  Enter 'simplexsl' for the ID and click the 'Browse' button
    next to the File field.  Browse for the file 'simple.xsl' in
    TESTFILES.  Click the 'Add' button.

  ADD AN XML DOCUMENT

    In your scratch folder, select 'DTML Document' from the ZMI Add
    menu.  Enter 'simplexml' for the ID and click the 'Browse' button
    next to the File field.  Browse for the file 'simple.xml' in
    TESTFILES.  Click the 'Add' button.

  ADD AN XSLTMETHOD

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  Notice that the Add form indicates that a Cache Manager
    is currently *NOT* available.  That is OK.  In the "XML Settings"
    panel, type in "simplexsl" in the "XSL Transformer ID" field.  In
    the "Standard Zope Settings" panel, type in "simplexform" for the
    ID.  Both title and description are optional.  Click the "Add"
    button.
       
  CREATE A RESULT DOCUMENT

    In your scratch folder, select 'DTML Document' from the ZMI Add
    menu.  Enter 'result' for the ID.  Click the 'Add And Edit'
    button.  Replace the contents of the edit buffer with::

      <dtml-var expr="simplexml.simplexform(this(), REQUEST)">

    Now click on the "Test" tab.  You should see the following::

        Hello, world

    Congratulations!  If this works, you are in business.

    Now try viewing the content in another browser window.  Open a new
    browser window and type in the following::

      http://www.acme.com:8080/scratch/simplexml/simplexform

      http://www.acme.com:8080/scratch/result

    They should give identical results.
  
Adding More Methods

  ADD AN XML DOCUMENT

    In your scratch folder, select 'DTML Document' from the ZMI Add
    menu.  Enter 'paramxml' for the ID and click the 'Browse' button
    next to the File field.  Browse for the file param.xml' in
    TESTFILES.  Click the 'Add' button.

  ALTERNATE

    Back in your scratch folder, select 'Page Template' from the ZMI
    Add menu. Enter 'alternatexsl' for the ID and click the 'Browse'
    button next to the File field.  Browse for the file
    'alternate.xsl' in TESTFILES.  Click the 'Add' button.

  DTMLTEST

    Back in your scratch folder, select 'DTML Method' from the ZMI Add
    menu.  Enter 'dtmltestxsl' for the ID and click the 'Browse' button
    next to the File field.  Browse for the file 'dtmltest.xsl' in
    TESTFILES.  Click the 'Add' button.

  ZOPE PROPERTY
   
    Back in your scratch folder, click on the properties tab.  You are
    now viewing properties defined on the scratch folder.  Add a new
    property of type 'string' with name 'who' and value 'zippy'


  ADD MORE XSLTMETHODS

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  In the "XML Settings" panel, type in "alternatexsl" in
    the "XSL Transformer ID" field.  In the "Standard Zope Settings"
    panel, type in "alternatexform" for the ID.  Click the "Add"
    button.

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  In the "XML Settings" panel, type in "dtmltestxsl" in
    the "XSL Transformer ID" field.  In the "Standard Zope Settings"
    panel, type in "dtmltestxform" for the ID.  Click the "Add"
    button.

  TESTING

    Now try viewing the content in another browser window.  Open a new
    browser window and type in the following::

      http://www.acme.com:8080/scratch/simplexml/alternatexform 

    You should see::

       Hello, world and goodbye

    Now try::

      http://www.acme.com:8080/scratch/paramxml/dtmltestxform

       Hello, zippy

  DTML Tags

    Navigate to scratch/dtmltestxsl.  You should now be seeing
    the XSL program text in the Edit tab.  Notice that the DTML tag 
    embedded in the code::

       <dtml-var who>
  
    The dtmltestxsl transformer transformed paramxml into a document
    that included a DTML tag which was automatically resolved to find
    the "who" property we added to the scratch folder.  Kewl.
    
Creating a Cache Manager

  ADD A CACHE MANAGER

    Back in your scratch folder, select 'XML Method Cache Manager'
    from the ZMI Add menu.  Enter 'cacherInTheRye' for the ID.  Click
    on the "Add" button.  Now, back in the scratch folder, click on
    'cacherInTheRye'.  You should be in the Cache tab, where there are
    several buttons available.  Don't click on any of them yet.
    First, let's find out where the 'cacher' is going to store his
    files!  Click on the "Properties" tab.  Notice the cachePrefix
    Property::

       c:\tmp\ZopeXMLCache

    The cachePrefix is both a directory and file prefix.  The value
    above indicates that files will be placed in the 'c:\tmp'
    directory and the beginning of every file name will start with
    'ZopeXMLCache'.  Setting the prefix of all cache files the same helps
    a great deal in identifying them -- as all UNIX administrators
    know, 'tmp' directories can get quite full of stuff.

    Ensure that the prefix is pointing to a valid directory, either by
    adding the directory or changing the property, or both.

  USING THE CACHE MANAGER

    Back in the 'Cache' tab for the 'cacherInTheRye', try pressing the
    different buttons.  Don't be shy.  You should find them quite
    intuitive.  If not, now would be a good time to try the help
    system.  Click on the 'Help!' link in the upper right hand corner
    of the 'Cache' tab.

    When you navigate back to the 'Edit' tab of one of the
    XSLTMethod instances, you will now notice something different.
    It will now "Cache Manager: Root Folder/scratch/cacherInTheRye"
    Informative little buggers, aren't they?

    Now try running the results of the transformations using the steps
    above, and go back and list the files in the cache by pressing the
    'List Files In Cache' button.  If you are curious, go ahead and
    load the cache files into a text editor and check 'em out.  You
    can even delete them from the disk -- the cache manager is smart
    enough to notice that and regenerate them again next time!

behave_like Page Template

  ADD AN XML DOCUMENT

    In your scratch folder, select 'DTML Document' from the ZMI Add
    menu.  Enter 'templateparamxml' for the ID and click the 'Browse'
    button next to the File field.  Browse for the file
    templateparam.xml' in TESTFILES.  Click the 'Add' button.

  TEMPLATETEST

    Back in your scratch folder, make a new subfolder called "sub".
    Then make a new 'DTML Method' inside the "sub" subfolder, 
    enter 'templatetestxsl' for the ID and click the 'Browse' button
    next to the File field.  Browse for the file 'templatetest.xsl' in
    TESTFILES.  Click the 'Add' button.  So you now have a DTML method
    scratch/sub/templatetestxsl

  ANOTHER XSLTMETHOD

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  In the "XML Settings" panel, type in "sub/templatetestxsl"
    in the "XSL Transformer ID" field.  In the "Standard Zope
    Settings" panel, type in "templatetestxform" for the ID.  Click
    the "Add" button.

  TEST
  
    Now, type the following into a browser::

      http://www.acme.com:8080/scratch/templateparamxml/templatetestxform

      Hello, junk

    Now, wait a minute!  That's not what we wanted.  Click on the
    Properties tab for templatetestxform and change behave_like to
    "Page Template" and click "Save Changes".  Now try again::

      http://www.acme.com:8080/scratch/templateparamxml/templatetestxform

      Hello, zippy

    Much better!  Check out the source code to templatetest.xsl if you
    are curious.

  CREATE A RESULT DOCUMENT

    Just for completeness, let's create a page template to see the result.
    In your scratch folder, select 'Page Template' from the ZMI add menu.
    enter 'templateresult' for the ID.  Click the 'Add And Edit' button. 
    Replace the contents of the edit buffer with::

      <tal:nothing tal:replace="here/templateparamxml/templatetestxform"/>

    In this case the behave_like setting of the XSLTMethod doesn't
    matter, since the result is captured inside a Zope page template
    anyway.  Also note that the parameters 'this()' and 'RESULT' are
    not required for page templates, they way they are in DTML (in the
    Hello World example above).  Yet another reason to abandon DTML
    :-)
    
Parameterizing Transformations
    
  PARAM XSLT

    Back in your scratch folder, select 'DTML Document' from the ZMI
    Add menu.  Enter 'paramxsl' for the ID and click the 'Browse' button
    next to the File field.  Browse for the file 'param.xsl' in
    TESTFILES.  Click the 'Add' button.
  
  PARAM XSLTMETHOD

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  In the "XML Settings" panel, type in "paramxsl"
    in the "XSL Transformer ID" field.  In the "Standard Zope
    Settings" panel, type in "paramxform" for the ID.  Click
    the "Add" button.

  SCALAR PARAMETERS
   
    Back in your scratch folder, click on the properties tab.  You are
    now viewing properties defined on the scratch folder.  Add a new
    property of type 'lines' with name 'XSLparameters'.  Enter the
    value "who".  Then save changes and add "message" to the list.
    You have just indicated to all XSLTMethod instances located
    underneath the scratch folder that they should use two parameters,
    named "who" and "message".  The parameters are grabbed using
    acquisition, so they can be properties or Zope objects themselves.
    First, let's use (scalar) properties.

    Create another Property on the scratch folder called "message"
    with type "string" and value "Yow! Are we having fun yet?"

  TESTING

    Now, type the following into a browser::

       http://www.acme.com:8080/scratch/paramxml/paramxform

       Hello, zippy and Yow! Are we having fun yet?
    
  PROPERTIES FILE XSLT

    Back in your scratch folder, select 'Folder' from the ZMI Add
    menu, and add a subfolder called 'prop'.  Navigate into the 'prop'
    subfolder.  Select 'DTML Document' from the ZMI Add menu.  Enter
    'propertiesfile' for the ID and click the 'Browse' button next to
    the File field.  Browse for the file 'propertiesfile.xsl' in
    TESTFILES.  Click the 'Add' button.

  ANOTHER XSLTMETHOD

    Also in the prop folder, create an instance of XSLTMethod using
    'propertiesfilexform' as the ID, and 'propertiesfile' as the XSL
    Transformer ID.

  PROPERTIES FILE XML

    Back in your scratch folder, select 'DTML Document' from the ZMI
    Add menu.  Enter 'properties' for the ID and click the 'Browse'
    button next to the File field.  Browse for the file
    'properties.xml' in TESTFILES.  Click the 'Add' button.

  CHANGE XSL PARAMETERS

    Back in your scratch folder, select the Properties tab, and change
    the XSLparameters to only a single line that says "properties".

    Now, type the following into a browser::

       http://www.acme.com:8080/scratch/paramxml/prop/propertiesfilexform
    
       url is http://www.acme.com:8080/scratch/properties

    *NB* If at first you don't see the correct output, try disabling
    the cache by navigating to the 'cacherInTheRye' and pressing the
    'Turn Caching Off' button.

    Did you notice how you can apply an XSLTMethod to an XML source
    even if the XSLTMethod is in an unrelated folder?  We are
    essentally applying 'prop/propertiesfilexform' to 'paramxml' For
    more details on this amazing technology, please read the
    acquisition chapter in the Zope Developer's
    "Guide":http://www.zope.org/Documentation/Books/ZDG/current/Acquisition.stx

XSLT Pipelines

    XSLT stylesheets can be combined into pipelines, where the output
    of one stylesheet is passed on to the next.  XSLTMethod makes this
    a piece of cake.  Let's try an example:

  ADD XSLTS

    Back in your scratch folder, select 'DTML Method' from the ZMI Add
    menu.  Enter 'pipeline1xsl' for the ID and click the 'Browse'
    button next to the File field.  Browse for the file
    'pipeline1.xsl' in TESTFILES.  Click the 'Add' button.

    Back in your scratch folder, select 'DTML Method' from the ZMI Add
    menu.  Enter 'pipeline2xsl' for the ID and click the 'Browse'
    button next to the File field.  Browse for the file
    'pipeline2.xsl' in TESTFILES.  Click the 'Add' button.

    Back in your scratch folder, select 'DTML Method' from the ZMI Add
    menu.  Enter 'pipeline3xsl' for the ID and click the 'Browse'
    button next to the File field.  Browse for the file
    'pipeline3.xsl' in TESTFILES.  Click the 'Add' button.

  ADD XSLTMETHODS

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  Enter 'xslt1' for the ID and 'pipeline1xsl' for the
    "XSL Transformer ID" field.  Click the "Add" button.

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  Enter 'xslt2' for the ID and 'pipeline2xsl' for the
    "XSL Transformer ID" field.  Click the "Add" button.

    Back in your scratch folder, select 'XSLT Method' from the ZMI
    Add menu.  Enter 'xslt3' for the ID and 'pipeline3xsl' for the
    "XSL Transformer ID" field.  Click the "Add" button.

  TEST

    Now, type the following into a browser::

       http://www.acme.com:8080/scratch/simplexml/xslt1/xslt2/xslt3
    
       Hello, world

    Now just for fun, try inspecting each step in the pipeline.  After
    each one, you may have to select 'View Page Source' in your
    browser in order to see the native XML.  *Note that you may have to
    turn caching off for this to work correctly; see Known Limitations
    in the README file.* ::

       http://www.acme.com:8080/scratch/simplexml/xslt1

       http://www.acme.com:8080/scratch/simplexml/xslt1/xslt2

       http://www.acme.com:8080/scratch/simplexml/xslt1/xslt2/xslt3

URN Resolvers

      *This capability is currently only supported using 4Suite*

    PROPERTIES FILE XSLT

      Back in your scratch folder, select 'DTML Document' from the ZMI
      Add menu.  Enter 'calldocumentfuncURN' for the ID and click the
      'Browse' button next to the File field.  Browse for the file
      'calldocumentfuncURN.xsl' in TESTFILES.  Click the 'Add' button.

    PROPERTIES FILE XSLTMETHOD

      Back in your scratch folder, select 'Folder' from the ZMI Add
      menu, and add a subfolder called 'urntest'.  Navigate into the
      'urntest' subfolder.  Create an XSLTMethod instance inside the
      'urntest' subfolder with ID 'calldocumentfuncxform' and XSL
      Transform ID 'calldocumentfuncURN'  

    CREATE PROPERTY FILE

      Back in the scratch folder, create a subfolder with the ID
      "arielpartners".  Then create a subfolder within arielpartners
      called "propfolder".  Finally, create a subfolder within
      propfolder called "foo".  Within the 'foo' folder, create a
      DTMLDocument with ID "properties" by uploading the
      "properties.xml" file from TESTFILES.  You now have a Zope
      object::
         
           Root_Folder/scratch/arielpartners/propfolder/foo/properties

    URN NAMESPACE REGISTRATION

      Back in your scratch folder, click on the properties tab.  You
      are now viewing properties defined on the scratch folder.  Add a
      new property of type 'lines' with name 'URNnamespaces'.  Enter
      the value "arielpartners".  Then save changes.  You have just
      indicated to all XSLTMethod instances located underneath the
      scratch folder that the "arielpartners" folder is now available
      as a URN namespace.  That is, it can be used as the "NID" piece
      of a URN (see README.txt for more details).  The "NSS" portion
      of a URN will be interpreted as a Zope path relative to the NID.
      We will see how this works below.

    TEST

      Now, type the following into a browser::

        http://www.acme.com:8080/scratch/urntest/paramxml/calldocumentfuncxform
    
        Hello, sneezy

      URN resolution works the same way in xsl:include and xsl:import
      statements.  Have fun!

XML Catalog files

      *This capability is currently only supported using 4Suite*

      Use the very same setup as in the previous section.  However,
      move the 'properties' object from the
      'scratch/arielpartners/propfolder/foo' folder to a new
      'scratch/bar' folder.  Make sure that there are *no* other
      copies of the properties object anywhere else (you may have to
      remove the version in the 'scratch' folder from the
      'Parameterizing Transformations' lesson).

    XML CATALOG FILE

      Back in your scratch folder, select 'DTML Document' from the ZMI
      Add menu.  Enter 'catalog' for the ID and click the
      'Browse' button next to the File field.  Browse for the file
      'catalog.xml' in TESTFILES.  Click the 'Add' button.

    XML CATALOG REGISTRATION

      Back in your scratch folder, click on the properties tab.  You
      are now viewing properties defined on the scratch folder.  Add a
      new property of type 'string' with name 'XMLcatalog'.  Enter the
      value "catalog".  Then save changes.  You have just indicated to
      all XSLTMethod instances located underneath the scratch folder
      that the "catalog" object contains an XML Catalog to be used for
      URI resolution.  You can do many complex and wonderful things
      with catalogs.  For more details, please see README.txt

    TEST

      Now, type the following into a browser::

        http://www.acme.com:8080/scratch/urntest/paramxml/calldocumentfuncxform
    
        Hello, sneezy