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

$RCSfile: TUTORIAL.txt,v $

Author: Craeg Strong

$Date: 2002/08/26 19:00:00 $

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

Contents

1. Getting Started
2. Conventions
3. Hello World
4. Adding More Transforms
5. Creating a Cache Manager
6. behave_like Page Template
7. Parameterizing Transformations
8. URN Resolvers

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 XMLTransform 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 three new options should appear:

      XML Transform
      XML Transform Cache Manager
      XSL Transformer Registry

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 XMLTRANSFORM abbreviation throughout the tutorial to refer to the directory containing the XMLTransform product within your Zope installation. On windows systems that will be:

    ZOPE\lib\python\Products\XMLTransform

and on UNIX/Linux systems that will be:

    ZOPE/lib/python/Products/XMLTransform

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

    ZOPE\lib\python\Products\XMLTransform\tests\testfiles

and on UNIX/Linux systems that will be:

    ZOPE/lib/python/Products/XMLTransform/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

CREATE A TRANSFORMER REGISTRY

In your scratch folder, select XSL Transformer Registry from the ZMI Add menu. Enter registry for the ID and My Registry for the Title. Click the Add TransformerRegistry button. You should see a happy message.

INSTALL A TRANSFORMER

Back in your scratch folder, click on the registry to navigate into it. Select DTML Document from the ZMI Add menu. Enter simple 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

Back in your scratch folder, select DTML Document from the ZMI Add menu. Enter simple.xml 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 XMLTRANSFORM

Back in your scratch folder, select XML Transform 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 Information" panel, you should see "simple" listed as the one and only choice in the "Transformer Name" drop down menu. Type in "simple.xml" in the "Source ID" field. Enter "hello" for the Zope ID and "Hello, World" in the Title field. Click the "Add XMLTransform" button. You should see a happy message.

MAKE IT HAPPEN

Back in your scratch folder, click on the "hello" XMLTransform object. You should now be looking at the Edit form. You will notice it looks much like the Add form -- you can change nearly everything. Now click on the View 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/hello

Adding More Transforms

ALTERNATE

Back in your scratch folder, click on the registry to navigate into it. Select Page Template from the ZMI Add menu. If you don't have Page Templates installed, DTML Document will work fine. Enter alternate 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, click on the registry to navigate into it. Select DTML Method from the ZMI Add menu. Enter dtmltest 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

Back in your scratch folder, click on the "hello" XMLTransform object. You should now be looking at the Edit form. Check out the Transformer Name pulldown menu in the "XML INFORMATION" panel. You should now see three possibilities:

       simple
       alternate
       dtmltest

TESTING

Select "alternate" from the list and hit the "Save Changes" button. Click on the View tab. You should see:

       Hello, world and goodbye

Select "dtmltest" from the list and hit the "Save Changes" button. Click on the View tab. You should see:

       Hello, worldzippy

DTML Tags

Navigate to scratch/registry/dtmltest. 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 dtmltest transformer transformed simple.xml 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

ANOTHER XML DOCUMENT

Back in your scratch folder, select External File from the ZMI Add menu. Enter the fully qualified pathname of the param.xml file in the TESTFILES directory for the "Target Filepath on Server" field. Don't have ExternalFile installed? No problem -- just use a DTML Document with ID of param.xml and upload the contents just like you did in Hello World above.

ANOTHER XMLTRANSFORM

Back in your scratch folder, select XML Transform 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 Information" panel, you should see all three transformers listed as choices in the drop down menu. Choose "alternate". Type in "param.xml" in the "Source ID" field. Enter "bonjour" for the Zope ID. Click the "Add XMLTransform" button. You should see a happy message.

CHECK OUTPUT

Try changing the transformers used by each XMLTransform instance ("hello" and "bonjour") and going to their View tabs to see the results. Alternatively you could view the results in a browser.

ADD A CACHE MANAGER

Back in your scratch folder, select XML Transform Cache Manager from the ZMI Add menu. Enter cacherInTheRye for the ID. Click on the "Add XMLTransformCacheManager" button. You should see a happy message. 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 the 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\ZopeCache

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 ZopeCache. 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 XMLTransform instances, you will now notice something different. It will now say "Cache Manager IS Available." Informative little buggers, aren't they?

behave_like Page Template

This step can only be done if you have Page Templates installed...

TEMPLATETEST

Back in your scratch folder, click on the registry to navigate into it. Select DTML Method from the ZMI Add menu. Enter templatetest 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.

TEST

Back in your scratch folder, click on the "bonjour" XMLTransform object to navigate to it. Change the "Transformer Name" to "templatetest" and click "Save Changes". Now click on the view tab:

       Hello, junk

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

       Hello, zippy

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

Parameterizing Transformations

PARAM XSLT

Back in your scratch folder, click on the registry to navigate into it. Select DTML Document from the ZMI Add menu. Enter param 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.

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

Back in your scratch folder, click on the "bonjour" XMLTransform object to navigate to it. Change the "Transformer Name" to "param" and click "Save Changes". In this case, it does not matter what behave_like is set to. Now click on the view tab:

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

PROPERTIES FILE XSLT

Back in your scratch folder, click on the registry to navigate into it. 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.

BONJOUR AGAIN

Back in your scratch folder, click on "bonjour" to get to its Edit form. Select props/propertiesfile from the Transformer Name drop down menu.

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 navigate back to the "bonjour" XMLTransform object. Click on the View menu:

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

URN Resolvers

PROPERTIES FILE XSLT

Back in your scratch folder, click on the registry to navigate into it. Select Folder from the ZMI Add menu, and add a subfolder called urntest. Navigate into the urntest subfolder. Select DTML Document from the ZMI Add menu. Enter calldocumentfunc for the ID and click the Browse button next to the File field. Browse for the file calldocumentfunc.xsl in TESTFILES. Click the Add button.

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

BONJOUR AGAIN

Back in your scratch folder, click on "bonjour" to get to its Edit form. Select urntest/calldocumentfunc from the Transformer Name drop down menu and save changes, then click the View tab. You should see:

         Hello, sneezy

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