The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

All information submitted is secure.

My developerWorks:

My notifications:

Sign out

Select a language:

XSL Formatting Objects (XSL-FO), Part 1: Get the basics of XSL-FO techniques

Convert HTML documents into formatting objects and then into PDF files

Doug Tidwell (dtidwell@us.ibm.com), developerWorks Cyber Evangelist, EMC

Doug Tidwell is the developerWorks Cyber Evangelist, helping people use new technologies to solve problems. He has spoken about Web Services and XML to tens of thousands of developers around the world, a number of whom actually stayed awake. He is also the author of O'Reilly's XSLT and a coauthor of O'Reilly's Programming Web Services with SOAP, both of which make excellent gifts for your friends and loved ones.

In a rare brush with greatness, he and his daughter Lily were once trounced by Olympic gold medalist Marion Jones in a game of Whack-a-Mole at the North Carolina State Fair:

Dad: How can the game be over already?
Lily: No way! Nobody could be that fast! [Dad looks over, sees winning contestant]
Dad: Come on, Lily, let's go....

Summary: Through examples and illustrations this tutorial for developers teaches the basics of working with XSL Formatting Objects (XSL-FO), a powerful, flexible XML vocabulary for formatting data, often used with XSLT to convert XML and HTML documents to PDF (portable document format). This tutorial, Part one of a two-part series, introduces how to use XSLT to convert XML documents into formatting objects and then the Apache XML Project's FOP (Formatting Object to PDF) tool to convert those formatting objects into PDF files. Examples include many XSL-FO sample code, XSLT templates, and some Java commands for the processing.

View more content in this series

Date: 04 Feb 2003
Level: Introductory
PDF: A4 and Letter (181 KB | 22 pages)Get Adobe® Reader®

Activity: 35611 views
Comments:

Tutorial introduction and preparation

What this tutorial covers

The XSL Formatting Objects specification, an official recommendation of the W3C that is commonly known as XSL-FO, defines a number of XML tags that describe how something should be rendered. Although XSL-FO contains elements that describe how to render text in nonprint formats such as spoken text, this tutorial introduces how to create portable document format (PDF) files -- the most common use of XSL-FO.

The tutorial provides a brief overview of the XSL-FO document structure, as well as the elements that define page sizes, fonts, and margins. It also explains the basics of text and graphic formatting and demonstrates the fundamentals of converting a formatting object file to PDF. Downloadable code samples make it easy to adapt samples to experiment on your own.

When you've completed this introductory tutorial, you'll understand what XSL-FO is and how it works. You'll be able to adapt the basic samples provided to create simple FO documents of your own. You'll be ready move on to the second tutorial in this series to find out how to control text formatting in detail and how to convert HTML elements to formatting objects. Then you will be able to create your own XML applications that use formatting objects to generate high-quality printable documents.

What you need to know to benefit from this tutorial

This tutorial assumes that you already comprehend the Extensible Markup Language (XML) and how to work with it and its related technologies, such as XML Stylesheet Language-Transformation (XSLT). You don't need to know anything about XSL-FO yet, but to work with formatting objects, you need a little experience working with XSLT.

The tools used for the examples are written in the Java code, but you don't have to understand the Java language to use them.

What you need to know about the software and standards

Figure 1. FOP project logo

Although you can use other XSL-FO rendering engines, this tutorial is written for the Apache XML Project's FOP (Formatting Objects to PDF) translator. The examples in this tutorial work with FOP Version 0.20.4, which was released on July 5, 2002. If you try them with other versions of FOP, they may or may not work. The XSL-FO spec became an official recommendation of the W3C on 15 October 2001; the FOP tool supports most of the final spec.

We use the FOP tool at developerWorks for two reasons:

It's written in the Java language, and so it runs on all the platforms that we care about.
It's a no-cost, open-source product, and so anyone can afford it.

If you want to immerse yourself in XSL-FO, you can go directly to the source for the the spec at the W3C's site (see Resources). Be aware that this is one of the longest documents at the W3C (roughly 400 pages), although most of it is reference information for the many elements and attributes in the XSL-FO tag set. The reference sections -- particularly appendixes B, C, and D -- are very useful for looking up property names and values. Remember, as of this writing, FOP does not completely support the XSL-FO spec. Certain property names and values defined by the spec might not be supported by the tool, or they might be supported with slightly different names and values.

What tools you'll need for the tutorial and how to configure them

To go through the exercises in this tutorial, you'll need to have a Java Developer's Kit (JDK) Version 1.3 or later, as well as the FOP package from the Apache XML Project. You can get the FOP package. Download the latest version and unzip it.

Once you have the JDK and FOP installed, you need to set the classpath.

If you want to follow the examples in the tutorial without remembering to adapt them, put the FOP package at c:\fop-0.20.4rc and then set the classpath like this (except all on one line, of course; I've broken the line only to fit within the text column here):

set classpath=.;c:\fop-0.20.4rc\build\fop.jar;c:\fop-0.20.4rc\
lib\avalon-framework-cvs-20020315.jar;c:\fop-0.20.4rc\lib\bati
k.jar;c:\fop-0.20.4rc\lib\xalan-2.3.1.jar;c:\fop-0.20.4rc\lib\
xercesImpl-2.0.1.jar;c:\fop-0.20.4rc\lib\xml-apis.jar;

If you unzip the FOP package somewhere else, you'll need to change the command accordingly. If you're running Linux, use the command export classpath=/usr/bin/fop-0.20.4rc/build/fop.jar:/usr/bin/fop-... and so on.

Comments