Skip to main content

Introduction

This manual describes the functionality and use of the Ibex PDF Creator. Ibex is a PDF creation component which can be used from the command line or, more usually, integrated into a larger application.

It ships as a .Net assembly so it can be used both in stand-alone applications and in server-based applications using ASP and ASP.Net.

This chapter provides an overview of how Ibex works and the process involved in creating PDF files using Ibex.

The PDF creation process​

Ibex creates PDF files which contain data from your application. You provide Ibex with your data in XML format and Ibex creates a PDF file containing that data. The format of the PDF file is specified using an XSL stylesheet which defines the layout of the document using the elements from the XSL Formatting Objects standard . The XML you provide to Ibex can come from any source. Typically, it is extracted from a database or generated dynamically for each document. The formatting objects (FO) standard defines elements such as table, row and cell which can be used to lay out your data on a page. It also defines objects for describing the overall shape and layout of the page, including parameters such as page size, number of columns and regions such as headers and footers where content will be placed on the page. The process of creating a document in FO format is carried out using an XSLT stylesheet. The stylesheet transforms your XML data into standard FO syntax. Ibex then reads that XSL-FO and creates the PDF file.

The actual execution of the XSLT translation can be done either by Ibex, which uses the .Net XSL translation objects, or externally to Ibex using any XSLT engine. This enables you to use the XSTL translator of your choice.

Figure 1-1 shows some XML data for creating a page which says "Hello world". The corresponding formatting objects from which the PDF is created are shown in Figure 1-2.

<?xml version="1.0" encoding="UTF-8"?>
<expression>hello world<expression>

Figure 1-1: Simple XML

<?xml version="1.0" encoding="utf-8"?>
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
		<fo:layout-master-set>
				<fo:simple-page-master master-name="layout" page-width="8.5in" page-height="8in">
						<fo:region-body region-name="body" margin="2.5cm"/>
				</fo:simple-page-master>
		</fo:layout-master-set>
		<fo:page-sequence master-reference="layout">
				<fo:flow flow-name="body">
						<fo:block>Hello world</fo:block>
				</fo:flow>
		</fo:page-sequence>
</fo:root>

Figure 1-2: Example formatting objects for hello world

The process of getting from your data to the formatting objects is carried out using the XSLT stylesheet which you provide.

This approach to PDF creation has a significant advantages:

  • the content and presentation are separated. The format of the PDF file is defined by the XSLT stylesheet which can be created and maintained externally to the application. Changing the stylesheet to alter the report layout does not require rebuilding your application;

  • formatting elements such as report headers and footers can be maintained in a separate stylesheet which is included at runtime into many different reports;

  • the formatting objects standard defines a powerful set of objects for creating page content. It supports single-column and multi-column pages, bookmarks, indexing, page headers and footers, complex page numbering, tables with optionally repeating headers and footers and many other features;

  • formatting objects is a high-level approach which makes changing report layouts simple. For example to change the number of columns on a multi-column page you just need to change the column-count attribute on a single element. To do this using a lower level programmatic API is much more complex.

Terminology​

Ibex uses the FO standard which defines formatting objects such as table and table-cell. FO makes a distinction between two types of objects:

  • block-level objects broadly speaking these are objects which are formatted vertically down the page. Block level objects are fo:block, fo:block-container, fo:table, fo:table-and-caption, and fo:list-block.

  • inline-level objects these are objects whose content is placed on lines within an fo:block object. Commonly used inline level objects are fo:external-graphic, fo:inline, fo:leader, fo:page-number, fo:page-number-citation and fo:basic-link.

About this manual​

This manual is split into two main sections. The first covers an introduction to the use of formatting objects and an overview of various formatting objects such as tables and lists. The second is a reference section listing all the available objects and attributes with many examples of their usage.

About Ibex​

Ibex is developed entirely in C# and requires the Microsoft dotnet runtime to be installed. Ibex is developed using .Net 6 and Visual Studio 2022. Ibex runs on Windows and Linux.