61
IbexPDFCreator
DevelopersGuide
IntroductiontoXSL-FO
25
This listwas created with the FO shown in Figure 4-35:
Figure 4-35:
FOforthe list-block
<list-block
margin-left='3cm' margin-right='3cm' padding='3pt'
border='.1pt solid blue'
provisional-distance-between-starts='0.5cm'
provisional-label-separation='0.1cm'>
<list-item>
<list-item-label end-indent='label-end()'>
<block>•</block>
</list-item-label>
<list-item-body start-indent='body-start()'>
<block>this is item one</block>
</list-item-body>
</list-item>
<list-item>
<list-item-label end-indent='label-end()'>
<block>•</block>
</list-item-label>
<list-item-body start-indent='body-start()'>
<block>this is item two</block>
</list-item-body>
</list-item>
</list-block>
Alist sets the two columns to widths specified using the attributes of the e list-block
elements. The provisional-distance-between-starts attribute specifies the distance
between the start of the label column and the start of the body column. The
provisional-label-separation attribute sets how much of the label column should be left
empty to provide a blank spacebetween thecolumns.
If we expand the aboveexample and add more contentto the first body we can see that
the content is constrained to the column. If we add content to the firstlist-item-body as
shown in Figure 4-36 we get the list shown in Figure 4-37.
Figure 4-36:
FOforthe list-block
<list-item-body start-indent='body-start()'>
<block>
If your Network Administrator has enabled it,
Microsoft Windows can examine your network and
automatically discover network connection settings.
</block>
</list-item-body>
Figure4-37:
Outputforthe
list-block
•
If your Network Administrator has enabled it,
Microsoft Windows can examine your network
and automatically discover network connection
settings.
•
this is item two
For more information on lists seepage77.
4.10 Creating tables
Atable is created using thetable element. Within thetable element there can be one
table-headerelement,anynumberoftable-bodyelements(whichcontaintherows)and
one table-footer element. Each of the table-header, table-body and d table-footer
50
Ibex PDF Creator
Developers Guide
26
Introduction to XSL-FO
elements contains one or more e table-row elements, each containing one or more
table-cellelementswhichinturncontainblock-levelelementssuchas block, tableand
list-block.
Since atable-cellcan contain any block-level element you can easily create tables which
contain text, nested tables or lists. Table headers and footers defined with the
table-headerand table-footerelementsareautomaticallyrepeatedateachpagebreak,
although this can besuppressed if required.
Figure 4-38 shows the FO for a simple table and Figure 4-39 shows the table created
from the FO.
Figure 4-38:
FOfora table
<table>
<table-body>
<table-row>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 1</block>
</table-cell>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 2</block>
</table-cell>
</table-row>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 1</block>
</table-cell>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 2</block>
</table-cell>
</table-row>
</table-body>
</table>
This FO produces thetable shown in Figure 4-39.
Figure 4-39:
Simpletable fromthe
above FO
row 1 column 1
row 1 column 2
row 2 column 1
row 2 column 2
The padding and border attributes are not inherited from containing elements so must
be defined on thetable-cellelements.
4.10.1 Setting table column widths
The width of a table column is set using the e table-column element. Atable element
contains zero or moretable-column elements each of which defines properties such as
width and background-color for a column in the table.
To make the first column 30%of the table width we would addtable-column elements as
shown in Figure 4-40, which creates the output shown in Figure4-41.
38
Ibex PDF Creator
Developers Guide
Introduction to XSL-FO
27
Figure 4-40:
Table with
table-column
elements
<table>
<table-column column-width='30%' column-number='1'/>
<table-column column-width='70%' column-number='2'/>
<table-body>
<table-row>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 1</block>
</table-cell>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 2</block>
</table-cell>
</table-row>
<table-row>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 1</block>
</table-cell>
<table-cell border='1pt solid blue' padding='2pt'>
<block>row 1 column 2</block>
</table-cell>
</table-row>
</table-body>
</table>
Figure 4-41:
Renderedtablewith
specifiedwidths
row 1 column 1
row 1 column 2
row 2 column 1
row 2 column 2
For more information on tables see page81.
2
28
Introduction to XSL-FO
30
Using Ibex
29
Chapter 5
Using Ibex
This chapter describes how to call the Ibex API and how to use the accompanying
command line program.
5.1 Ibex command line program
Although primarily intended to be used as a partof a larger application, Ibex ships with a
command line program which can beused to create PDF files from FO files.
The command line programs shipped with Ibex are ibex10.exe (which uses .NET 1.0),
ibex11.exe (which uses .NET 1.1) and ibex20.exe (which uses .NET 2.0).
The command line syntax is the same for all programs. In these examples we use
ibex20.exe.
To create a PDF file from an FO file specify the file names on the command line. For
instance to create hello.pdf from hello.fo, you do this:
ibex20 hello.fo hello.pdf
5.1.1 XSLT translation
The command line program will accept XML data and an XSLT stylesheet as inputs. The
XML will be translated to FO by the stylesheet and the results then formatted to PDF.
Thecommand line syntaxis:
ibex20 -xsl xsl-file xml-file pdf-file
So to create a PDF file from the files book.xml and book.xsl, the command is:
ibex20 -xsl book.xsl book.xml book.pdf
XSLT parameters can be passed to the stylesheet by adding them as name-value pairs to
the command line. For instance, if we want to define the parameter called "age" to the
value"30" we use a command likethis:
ibex20 -xsl book.xsl book.xml hello.pdf "age=30"
The use of the double quotes around the name-value pair is necessary on some
operating systems to force them to come through as a single parameter to the Ibex
program.
33
Ibex PDF Creator
Developers Guide
30
Using Ibex
5.1.2 Logging from the command line
Any informational or error messages will be logged to the console. To send error
messages to a file as well, use the -logfile option. For example to log errors to the file
ibex.log,you would do this:
ibex20 -logfile ibex.log hello.fo hello.pdf
5.1.3 Listing available fonts
You can also list the fonts which are available (based on what fonts are installed on your
system) byusing the -fonts option likethis:
ibex20 -fonts
Thelist of fonts is produced as a FO file to the standard output. This can be redirected to
afile and then used as input to Ibex to create a PDF file containing a table which looks
like this:
The list of fonts can be limited to fonts whose name contains a specified string by
passing the string on the command line. For instance if we wanted to see what versions
of "arial" are installed, we can use thecommand:
ibex20 -fonts arial
5.2 The Ibex API
A PDF document is generated using the FODocument object which is in the ibex4
namespace.
First you create a new FODocument object and then calling the generate() method on
that object. The generate() method has various versions which take different
parameters depending on whether the input is from files or streams and whether XSLT
translation should occur.
The FODocument object is not thread safe. A new FODcoument should be created for
each PDF file to be created. Ibex does support creating multiple PDF files concurrently
on multiple threads, as long as each PDF file is associated with a unique FODocument
instance.
Example C# code to convert the file "manual.fo" to "manual.pdf" the code is shown in
Figure 5-1, the equivalentVB.NET code is in Figure 5-2.
41
Ibex PDF Creator
Developers Guide
Using Ibex
31
Figure 5-1:
C# code to createa
PDF fromanFOfile
using System;
using ibex4;
public class Simple {
static void Main( string[] args ) {
FODocument doc = new FODocument();
gen.generate( "manual.fo", "manual.pdf" );
}
}
Figure 5-2:
VB.NET code tocreate
aPDF fromanFOfile
Imports System
Imports ibex4
Module Module1
Sub Main()
Dim doc As New FODocument
doc.generate("manual.fo", "manual.pdf")
End Sub
End Module
Projects need to havea reference to theibex DLL.
5.2.1 Generating to File
public void generate( string fo_file_name, string pdf_file_name )
This will read the FO contained in the filenamed in pdf_file_name and create the PDF file
named in pdf_file_name.
5.2.2 Generating using streams
public void generate( Stream fo_stream, Stream pdf_stream )
public void generate( Stream fo_stream, Stream pdf_stream, bool close_stream )
This will read the FO from the System.IO.Stream called fo_stream and create the PDF file
into the System.IO.Stream pdf_stream. These streams can be anything derived from
System.IO.Stream,such as System.IO.FileStream or System.IO.MemoryStream.
If close_stream is true the PDF stream will be closed after the PDF file is generated, if
false itwill not. By defaultthe stream is closed. Not closing the stream is useful if you are
generating to a MemoryStream object as the bytes cannot be read from the
MemoryStream if ithas been closed.
20
Ibex PDF Creator
Developers Guide
32
Using Ibex
5.2.3 Generating a PDF from XML and XSL
These methods take XML, an XSLT stylesheet, and a stream to write the resulting PDF
fileto.
public void generate( Stream xml_stream, Stream xsl_stream, Stream pdf_stream )
public void generate( Stream xml_stream, Stream xsl_stream, Stream pdf_stream, bool
closeStream )
Ibex uses the .NET XSLT processor to transform the XML using the specified stylesheet
and passes the resulting FO to the PDF creation routines. XSLT transformation is faster
or more efficient in .NET 2.0 and later and we recommend using this version or later if
possible.
5.2.4 Generate a PDF from XML and XSL with parameters
These methods are similar to the ones in the previous section but take an additional
hashtable which (if not null) should contain name-value pairs which are then passed as
arguments to the XSLT translation process.
public void generate( Stream xml_stream, Stream xsl_stream, Stream pdf_stream,
bool close_stream, Hashtable params )
41
Using Ibex with ASP.NET
33
Chapter 6
Using Ibex with ASP.NET
This chapter shows how to use Ibexwith ASP.NET, including how to create a PDF fileand
stream itback to a client browser withoutneeding to saveit to disk.
Ibex creates a PDF file into a Stream object (from the System.IO namespace). In this
example we use a MemoryStream object which derives from Stream and is basically an
expandable array of bytes held in memory. Creating the PDF file in a MemoryStream
means the fileis notsaved to disk and the wholeprocess occurs in memory.
We create the file into a MemoryStream because many versions of InternetExplorer will
display a PDF file correctly only if they know how long the file is. We need to create the
PDF file into a MemoryStream to determine its length and set this length in an HTTP
header. This need to know the length of the PDF file prevents us from streaming directly
to the Responseobject.
6.1 The ASP page
This example uses a page calledpdfasp.aspx, which has codebehind itinpdfasp.aspx.cs.
To use these pages you will need to create a new ASP.NETC#project, add a reference to
the ibex20.dll wherever you have installed it, and then add the pdfgen.aspx page. You
will need to remove the '_' characters from the names of the pdfasp.aspx and
pdfasp.aspx.cs files.
Thecontentof theASP pagepdfasp.aspx is shown in Figure 6-1.
Figure 6-1:
The ASPpage
<%@ Page language="c#" validateRequest="false" Codebehind="pdfasp.aspx.cs"
AutoEventWireup="false" Inherits="WebApplication1.pdfasp" %>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
<HTML>
<HEAD>
<title>pdfgen</title>
<meta name="GENERATOR" Content="Microsoft Visual Studio .NET 7.1">
<meta name="CODE_LANGUAGE" Content="C#">
<meta name="vs_defaultClientScript" content="JavaScript">
<meta name="vs_targetSchema"
content="http://schemas.microsoft.com/intellisense/ie5">
</HEAD>
<body MS_POSITIONING="GridLayout">
<form id="Form1" method="post" runat="server">
</form>
</body>
</HTML>
61
Ibex PDF Creator
Developers Guide
34
Using Ibex with ASP.NET
6.2 The ASP code-behind page
Thepdfasp.aspx.cs file contains the code shown in Figure 6-2 (plus some error handling
thatis notshown for clarity).
Figure 6-2:
Thecode-behindpage
using System;
using System.Collections;
using System.ComponentModel;
using System.Data;
using System.IO;
using System.Text;
using System.Drawing;
using System.Web;
using System.Web.SessionState;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.HtmlControls;
using System.Xml;
using System.Xml.Xsl;
using System.Security.Policy;
using ibex4;
using ibex4.logging;
namespace WebApplication1 {
public class pdfasp : System.Web.UI.Page {
private void Page_Load(object sender, System.EventArgs e) {
Logger.getLogger()
.setLevel( Level.FINEST )
.clearHandlers();
try {
Stream stream = new FileStream(
Server.MapPath( @"logs\log.txt"), FileMode.Append,
FileAccess.Write ) ;
Logger.getLogger().addHandler( new StreamHandler( stream ) ) ;
}
catch( Exception ) {
}
FODocument doc = new FODocument();
string dataFilePath = Server.MapPath("") + "\\hello.fo";
// stream for output in memory before sending to browser
MemoryStream pdfStream = new MemoryStream();
FileStream dataStream = new FileStream( dataFilePath,
FileMode.Open, FileAccess.Read );
Logger.getLogger().info( "data file path is " + dataFilePath );
using( dataStream ) {
doc.generate( dataStream, pdfStream, false );
}
Response.Clear();
Response.ContentType = "application/pdf";
Response.AddHeader( "content-length",
System.Convert.ToString( pdfStream.Length ) );
Response.BinaryWrite( pdfStream.ToArray() );
Response.End();
}
override protected void OnInit(EventArgs e)
{
InitializeComponent();
base.OnInit(e);
Documents you may be interested
Documents you may be interested