Paranoid Professor

This third example will extend upon my XSL-FO script to convert the list into more of a table. The result will generate a form and will look like this.

What I find to be really well done in XSL-FO and pretty useful is that it is possible to actually create tables that are formed from cells. What happens is that you create a table out of cells and decide which of these cells should have borders.

The change for this example is to turn the list output into a small table with borders. The additional xslt “code” for a table is pretty low. The following example is all you need to create a tiny table with one row of two cells.

<fo:table table-layout="fixed" width="60%">
  <fo:table-column column-width="proportional-column-width(80)" />
  <fo:table-column column-width="proportional-column-width(20)" />
    <fo:table-body>

    <fo:table-row >
      <fo:table-cell >
        <fo:block> value of cell 1, row 1 </fo:block>
      </fo:table-cell >
      <fo:table-cell  >
        <fo:block> value of cell 2, row 1 </fo:block>
      </fo:table-cell >
    </fo:table-row >
    </fo:table-body>
</fo:table>

When taken on its own this is really easy to take in. Simply define a table and the number of columns are necessary. Once that is done then it is just a matter of adding the actual rows full of data.

The table tag describes just how big (wide) our table will be . The attribute width on the table tag is using a relative width. This is defining the width to be equal to 60% if the width of our region body. This is a really flexible method if it is possible that the layout is likely to change during development.

The table-column tags essentially describes how wide each cell will be. The proportional-column-width attribute is also relative. This is proportioning our table with simple ratios. This may not be good enough when absolute dimensions are mandatory but for most forms this is a convenient trade off.

This example, although simple, would become quite tedious if you had to write the code for each row. The trick is to split up this table and row code into each of our templates so when the form is processed this is done for us automatically.

This is especially easy to do for the data file that we are using. Simply define the table layout somewhere before the person template is called and finish the table layout after all of the “people” are processed. In my case, the table definition is in the region body and the rows is for each person.

Region body

        <fo:flow flow-name="xsl-region-body">

          <fo:block font-size="16pt" font-weight="bold" space-after="5mm">List of <xsl:value-of select="/xmlroottag/listtype"/>
          </fo:block>

          <fo:block font-size="10pt">

              <fo:table table-layout="fixed" width="60%">
                  <fo:table-column column-width="proportional-column-width(80)" />
                  <fo:table-column column-width="proportional-column-width(20)" />
                  <fo:table-body>

                     <xsl:apply-templates />

                  </fo:table-body>
              </fo:table>


          <fo:block space-before="5mm">
                thats all folks!
          </fo:block>

          </fo:block>
        </fo:flow>

Person template

<xsl:template match="person">
    <fo:table-row >
       <fo:table-cell font-weight="bold" border-collapse="collapse" border-style="solid" border-width=".1mm" text-align="left" padding="1mm" >
           <fo:block>
           <xsl:value-of select="first"/>
           <xsl:value-of select="last"/>
           </fo:block>
       </fo:table-cell >
       <fo:table-cell font-weight="bold" border-collapse="collapse" border-style="solid" border-width=".1mm" text-align="left" padding="1mm" >
           <fo:block>
           <xsl:value-of select="party"/>
           </fo:block>
       </fo:table-cell >
    </fo:table-row >
</xsl:template>

This example works well because the of how homogeneous our data is. The data and xslt document was created with this structure in mind. It will perfectly process a list of data and prior to the list it will display a description about the list.

This is basically all the information that is necessary in order to create a simple form. The form itself would not be all that sophisticated as this is really only adding a few lines. The next set of changes provides the changes to create labels with small captions over them.

Download source and pdf for this example

The next set of changes for this can be found in part IV.

In my previous article, I went through the basics of what tools would be necessary to use Apache FOP to create PDF files.

In this second example will extend upon my XSL-FO script to add a header and footer to the output. The final result will generate this header and footer on all pages of the report and will look like this.

The original example has been pretty much the simplest possible case. Every page is just one big rectangle and each time that a person record shows up it will be output. It is actually magically simple. If there were hundreds of names, then they will be displayed and as they approach the defined margin it would automatically break to the next page.

In the previous article, I mentioned that the report definition only contained the report body. I didn’t actually mention other things that it could have included. The two new things that are included in this example contain is both the region-before and the region-after sections. These are used for adding a header and footer to the report.

       +---------------------------------------+
       |              region-before            |
       +---------------------------------------+
       |   |                               |   |
       | r |                               |   |
       | e |                               | r |
       | g |                               | e |
       | i |                               | g |
       | o |                               | i |
       | n |          region-body          | o |
       | - |                               | n |
       | s |                               | - |
       | t |                               | e |
       | a |                               | n |
       | r |                               | d |
       | t |                               |   |
       |   |                               |   |
       +---------------------------------------+
       |              region-after             |
       +---------------------------------------+

It is important to remember that this mock up (above) is excluding the page margins. The 2cm page margins defined by the page would be within the region-body.  It is also possible any or all of these four other regions also have a margin.

Adding the header/footer is as simple as adding these two “regions” to the definition at the same location as the definition of the region-body.

          <fo:region-body margin-top="1cm" margin-bottom="1cm"/>
          <fo:region-before region-name="myHeader" extent="2.0cm"/>
          <fo:region-after region-name="myFooter" extent="1.5cm"/>

The actual definition of what we would expect to see in in our header and footer regions is defined in the page-sequence along with the region body.

        <fo:static-content flow-name="myFooter">
          <fo:block font-family="Helvetica" text-align="left" font-size="7pt" color="black">
          __________________________________________________________________________________________________________________________________
          </fo:block>
          <fo:block font-family="Helvetica" text-align="left" font-size="7pt" color="gray">
		We deliver the most interesting data which can be considered almost factual.
          </fo:block>
        </fo:static-content>

This example shows what the footer should look like and it will be used in the region after portion of the page as was described in with the rest of the simple-page-master.

This could actually be simpler, it is not necessary to define every attribute on every block. It would have been sufficient to define the font-family on the block for the entire footer and within that have one or more blocks with varying attributes for the lines that are displayed.

One additional change to the xslt form in general was how the listtype value was retrieved from the data. This time rather than specifying the entire hard coded path, I simply pluck the value when I am processing that particular field.

This only works because when designing the xslt I knew that the listtype field would exist once in my input and it would be located just prior to my list data. If this field happened to be in my datafile after my person data my list header would incorrectly show up after my list.

Download source and pdf for this example

The next set of changes for this can be found in part III.

The tools

In order to reproduce this work you will need to download Apache FOP and have a recent version of Java on your computer.

https://xmlgraphics.apache.org/fop/download.html

Page layout

There are a number of books that spend hundreds of pages to describe how to create the XSL-FO formatting files. I can only give a brief overview and try to describe a few examples to help bend XSL-FO to your will.

The first example will be taking a few names and creating a PDF file that is a list of these names. This is a snapshot from the actual output from step #1.There is no point in display the entire page here as it is only partially filled. It can be downloaded at the bottom of this post for the truly curious.

The actual layout for generating a single page PDF file using A4 as the page size and 2cm margins. In addition to the physical page definition, there are a lot of tags that appear to deal with formatting.

ie.

<fo:block font_size="16pt" font-weight="bold">
(other stuff here)

</fo:block>

The formatting

The formatting in the xslt file in a lot of cases is pretty obvious. Virtually every tag contains one more attributes. One of the nice things about the xslt is that the names chosen by the W3C are actually quite meaningful as are most of the attributes.

It may or may not seem obvious but not every attribute can be used on every tag.  An obvious example of this is margins. Page layout is anything that relates to the physical size. It is the definition of how part of the document will look on with respect to the output page (body, heading or footer) The block could be considered a scope or style that lets you define the basic format for everything within that paragraph or block.

As not every tag has the same sets of attributes so it can be difficult to know which tags have which attributes. I suggest that you find either a good reference book. A book is nicer as you can slide printouts of specific code in between the pages to clarify any points or show examples of special functionality.

I was surprised that really none of the xslt books that cover XSL-FO received good reviews. I think this is because this is a really dense material and it is difficult to easily convey. I happened to purchase a book from O’Reilly which I used to help supplement other examples and information received from the internet.

Making XML Look Good in Print

The actual xslt layout that creates my PDF is listed below.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" exclude-result-prefixes="fo">
<xsl:template match="xmlroottag">
    <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
      <fo:layout-master-set>
        <fo:simple-page-master master-name="simpleA4" page-height="29.7cm" page-width="21cm" margin-top="2cm" margin-bottom="2cm" margin-left="2cm" margin-right="2cm">
          <fo:region-body/>
        </fo:simple-page-master>
      </fo:layout-master-set>

      <fo:page-sequence master-reference="simpleA4">
        <fo:flow flow-name="xsl-region-body">

          <fo:block font-size="16pt" font-weight="bold" space-after="5mm">
              List of <xsl:value-of select="/xmlroottag/listtype"/>
          </fo:block>

          <fo:block font-size="10pt">

              <xsl:apply-templates />

          <fo:block space-before="5mm">
                thats all folks!
          </fo:block>

          </fo:block>
        </fo:flow>
      </fo:page-sequence>
     </fo:root>
</xsl:template>

<xsl:template match="person">
     <fo:block font-size="12pt" >
         <xsl:value-of select="first"/>
         <xsl:value-of select="last"/>
         <xsl:value-of select="party"/>
     </fo:block>
</xsl:template>

<xsl:template match="listtype">
</xsl:template>

</xsl:stylesheet>

The data file is listed here so you can see the structure of the xml.

<xmlroottag>                                                                                                            
   <listtype>presidents </listtype>                                                                                     
   <person>                                                                                                             
      <first> Robert </first>                                                                                           
      <last> Kennedy </last>                                                                                            
      <party> Dem </party>                                                                                              
   </person>                                                                                                            
   <person>                                                                                                             
      <first> George </first>                                                                                           
      <last> Bush </last>                                                                                               
      <party> Rep </party>                                                                                              
   </person>                                                                                                            
   <person>                                                                                                             
      <first> Jimmy </first>                                                                                            
      <last> Carter </last>                                                                                             
      <party> Dem </party>                                                                                              
   </person>                                                                                                            
</xmlroottag>                               

The xslt document does contain a single stylesheet which is essentially a collection of templates that you need or want to generate specific output. The person template (lines 33-40) when executed will extract the first, last and party fields from the xml data, yet I am getting a bit ahead of myself.

The form matches up with the starting at the template for the xmlroottag which starts matching with the data at element xmlroottag of our xml data file. This xsl template (lines 3-31) defines how the pages will be formatted (lines 5 – 9). All pages will just be a collection of simple A4 sized pages with border of 2cm on each side.

It is on line 7 that the defines the body of the document. This body is actually described in lines 11 – 26. The region body is where the xslt starts to actually process the data file and as the data is matched it is then output into the body of our document.

The first thing that is done in our document body is to retrieve the “listtype” tag. I am pulling in the value form the listtype field from the data file into the document. You can see that it is possible to pull in a value from the data by giving the exact location of the data. This obviously only works due to the nature of this field existing in that particular location. If the structure of the file changes or the root tag name changes, then this data won’t be found nor will the form actually create any meaningful output. The way that this is done is neither elegant nor flexible and it will be corrected in the future examples.

One of the most innocuous lines is the apply-templates at line 21 . This is essentially asking FOP to simply perform any of the templates that are defined if they happen to match that same structure in the data file. Fop will encounter the tag listtype and execute that template, which in this case doesn’t do anything. The next tags in the data file are the three different person blocks.

This person template will be executed three times, once for each of the tag in the data file. When it is executed it will extract that data and output it into our document body.

After the last person tag is processed there is no more of the data file left, and thus control resumes in the region body on line 22. This just changes the formatting and outputs a bit of constant text.

Most of the xslt file is taken up with some of the more boilerplate parts of the code (ie page layout) with only a few lines being used to process the xml data. In the rest of my examples I will be using this single page layout using the simple-page-master. However, it is possible to create different layouts for even pages, odd pages, blank pages, first page, or last page. If you want to do anything really creative using XSL-FO you will have to investigate specifically for that point.

Making the PDF

It is possible to include the merging of the xml data and xslt inside of a Java program but for right now, I will simply run the command line program “fop” with its parameters to generate the form. This will allow us to produce the output that we desire.

fop -xml data1.xml -xsl data1.xsl -pdf data1.pdf

This command simply creates the data1.pdf file from the data1.xml and data1.xsl source files.

Note: This assumes that fop exists in your path, otherwise you will need to give the fully qualified name to the fop executable.

The next set of changes for this can be found in part II.

Download source and pdf for this example

In the beginning, personal computers were not quite so friendly and not all users really enjoyed working with them in that pre-windowed state. In that sense, windows from Microsoft was really an advancement as it provided a easy to use interface to utilize the power of the computer.

The power of the computer allowed more than just text. It also allowed for the formatting and beautifying of documents. With word processing, you could see almost exactly what the final result would look like. The fonts and other markup was immediately visible and that gave a real advantage to the average user. No longer did you need a professional who could do desktop publishing to create a nice looking lost pet flyer.

Yet, pretty early on everyone noticed that what you see is what you get is only guaranteed if you happen to look at the document on the exact same computer, when you looked at the same document using the same program on an almost identical second computer sometimes the layouts were not quite the same as the source machine.

Adobe cracked this nut with their portable document format, PDF, and rather than trying to keep it a proprietary standard they released it as an open standard in 1993. To help with the acceptance, they also offer for free their own PDF file viewer.

This format provided the ability to generate a file on one machine or platform and have it accurately reproduced everywhere it was opened. For casual uses, it is perfect. It is possible to create documents that anyone can look at and nobody can modify. The document can be printed on any other machines with perfect reproduction.

This is pretty neat, but after a few decades this is old hat. It is possible to download dozens of tools for free that can create or modify PDF’s.

There are toolkits that can be used to generate PDF files but one of the neatest in my opinion is the one provided by Apache.

Apache Formatting objects processor (FOP)

This is just one implementation of the world wide web consortium’s Extensible Stylesheet Language Formatting Objects or XSL-FO. Apache FOP is simply a print formatter driven by XSL-FO and an independent output formatter.

I use this technology in a lot of cases where either I need to produce PDF files or want to provide nice to look at output. The supported output formats for Apache FOP are PDF, Postscript, PCL, and AFP.

The XSL-FO solution is a well thought out decomposition where the format is stored in an XSLT file while the actual data to be formatted is stored in an XML file. The two are processed together to generate the final output.

I will be producing a number of different posts showing how to take a very small data file and how to create a PDF file showing off that list of data. I will then expand the solution to show how XSL-FO can be expanded to create really professional looking documents.

The final PDF report file will look like this.

It all begins with the page layout.