First Steps

Installing the tutorial package

This guide briefly covers installation, including slightly different procedures depending on whether you’re using Windows or Mac OS X. All the files you’ll need are present in the installation package:

  1. Java, version 1.5 or higher (supplied for Windows, pre-installed on most Macs)
  2. An XML editor; we recommend Oxygen (demo instance supplied) or for Windows users, the less-powerful but free package XML Marker.
  3. Apache Tomcat, version 6.0.18 (supplied)
  4. XTF version 2.2 (supplied)
  5. Sample document library (supplied)

Note for linux users: Try the Mac package and adapt accordingly. Since you’re a linux user we assume you can work out the details of installing Java yourself. Do be sure to use Sun Java; gcj won’t work.

Here’s how to get this package onto your computer:

Windows: Mac:
1. Download the package .zip file from here. We recommend placing it into your My Documents folder. 1. Download the package .tar.gz file from here. We recommend placing it into your Documents folder.
2. Right-click on the file, and select: Extract all… 2. Double-click on the file to extract its contents.
3. Choose a folder to extract the package to. We recommend: My Documents\ 3. The package will be in a directory, e.g. Documents/xtfWorkshop/
4. Double-click the command prompt file, cmdPrompt.bat 4. Double-click the command prompt file, cmdPrompt.command

If the installation has been successful, you should be greeted with:
“*** Welcome to the XTF Workshop ***”
from the command prompt window you opened in Step 4.

Running the Oxygen XML editor

Unless you currently have an XML editor that you’re fond of, we recommend using Oxygen. If you already have Oxygen or an editor you prefer to use, skip this section.

We’ve tried quite a few different editors, and Oxygen comes out on top in terms of stability, features, and cross-platform compatibility. Though not free, the academic license is around US $50, which we feel is a bargain. Another alternative for Windows users is XML Marker, which is free, but which does not work on Mac or UNIX systems.

For this class, we’ve provided Oxygen inside the installation package. You can get an instant trial license that will allow you test-drive the software. Let’s get to it!

  1. Fill out the form on the Oxygen web site, here.
  2. A trial license key will be emailed to you. Check your email and Copy the license text to your clipboard.
  3. Now start Oxygen by double-clicking on xtfWorkshop\oxygen.bat (Windows) or xtfWorkshop/oxygen.command (Mac).
  4. You’ll be asked for a license key. Paste the text you copied. (If you skip this you can later enter license info by selecting Help -> Register.)

After entering the license info, the Oxygen editor should start up.

Learning about XSLT

All customization in XTF is done using a programming language called XSLT. While it isn’t strictly necessary to know anything about XSLT to complete this tutorial (we supply specific instructions) you will probably learn more about XTF if you pick up some basic XSLT skills now. If you’re already familiar with XSLT, skip this section and go on to Exercise 1.

W3schools offers a great basic online tutorial for XSLT.
There are also a number of basic XSLT books to learn from. Here’s one of them.

We suggest you spend some time learning about XSLT, and when you’re ready come back here and learn about XTF. If you’re just starting out, don’t try to accomplish this all in one day! It’s a lot to absorb, so give yourself time.

Another option if you’re impatient to learn about XTF is just to go through the exercises now, and come back to get a grip on XSLT at a later time.

Next tutorial step: The essentials