Generate PDF Documents with Artefact

1.1. Concepts, Key Aspects and Limits

After more than a year of development, the concepts used in Artefact are considered stable and it is already used in industry. In this section we list its current features and known limitations.

• Artefact has a simple architecture that facilitates scalability and new features.
• It supports the definition of a PDF document and its contents.
• It can specify meta information such as title or author.
• It manages display options when opening a document in a reader that is compatible with this feature.
• It supports compressed PDF document generation.

Each page of a PDF document can have its own particular format and orientation. By default, Artefact supports a set of common formats, e.g. A3, A4, or ebook. It can easily be extended to fit specific needs. Page location is determined not when the page is created but when it is added to a document. Hence each page is independent, which allows one to generate documents with variable architecture.

On each page, Artefact places simple or complex elements. A complex element is generally defined using simple elements or other complex elements. Each element is independent and is positioned relative to the upper left corner of a page.

Artefact provides greyscale management and colors defined by the RGB model (where each color component is represented by one byte). Character fonts are those imposed by the PDF but Artefact does not support true type fonts (TTF) specification. You can insert images into a PDF document but only the JPEG format is currently supported. Artefact does not support the definition of interactive input fields, integrating JavaScript or safety aspects of PDF such as certificates. Of course, these specifications are subject to change as and when the framework changes.

2.1. Installing Artefact

Artefact is hosted on SmalltalkHub. To install Artefact, execute the following expressions:

Gofer new
   smalltalkhubUser: '' project: 'RMoD/Artefact';
   package: 'ConfigurationOfArtefact';
   load.

ConfigurationOfArtefact load

Loading the configuration automatically load projets such as the Unit framework (which supports the definition of different measurement units. By default the configuration loads the stable version that is production ready.

Once loaded, you can browse the main packages and classes.

• The Artefact-Examples package contains many usage examples.
• The Artefact-Core package contains the main elements such as documents, pages or style sheets but also electronic documentation that is accessible via the Help Browser.
• The PDF objects (text, geometric shapes, images, etc.) offered by the basic framework are in Artefact-Core-Elements-Basic and Artefact-Core-Elements-Composites.
• The fonts are defined in the package Artefact-Core-Fonts and document formats in the package Artefact-Core-Formats.

2.2. Executing the First Demo's

The best way to start with Artefact is to have a look at the Artefact-Examples-Demos package and to run each of PDFDemos class methods.

If you want to run all demos, just execute PDFDemos runAllDemos

By default each generation result is written in the default Pharo directory but you can define your own by modifying the demoPath class method, e.g. as follows:

PDFDemos class>>demoPath
   ^ '/Users/pharo/pdf/'

2.3. Finally "Hello World!"

You will now create your first and simplest PDF document, which is a text on a page. To do this, you must define an instance of a PDF document that contains a page where you will position a text component.

PDFDocument new
   exportTo: 'helloworld.pdf' asFileReference writeStream

Once the instance of PDFDocument is created, it is exported using a stream to a file named helloworld.pdf. By default, the produced PDF document is placed in the directory of Pharo. If you open the file, it is empty. This is normal since you have not yet defined and added any content to the document.

Let us enrich the previous example and add a page to the document.

PDFDocument new
   add: PDFPage new;
   exportTo: 'helloworld.pdf' asFileReference writeStream

Now if you open the file the result is different since the document contains an empty page. Let us add a first text component to our page.

PDFDocument new add:
   (PDFPage new add:
      (PDFTextElement new text: 'Hello World!'; from: 10mm @ 10mm));
   exportTo: 'helloworld.pdf' asFileReference writeStream

To place the text on the page we create a component of type PDFTextElement. We add it to the page and define its position using the message from:. Note that we can specify dimensions using several units such as millimeters (mm), centineters (cm) or inches (inch). These coordinates are defined from the upper left corner of the page.

Artefact uses a set of defaults to get compact code when creating elements that are part of a document. More specifically, style parameters are set to what are considered the most common values. In this example the page format is set to A4, and its orientation to portrait. Also, text is by default written in black using the Helvetica font.

This first example introduced some basic concepts and shows how simple it is to produce a PDF document with Pharo. The following sections go deeper in Artefact and show how to define more complex documents.

3.1. Page Addition

To add pages to a document, the message add: is used. It appends a page after those already present in the document. When generating the PDF file, Artefact traverses the list of pages starting from the earliest added to the last. The following script defines a document with a single blank page.

PDFDocument new
   add: PDFPage new;
   exportTo: 'EmptyPage.pdf' asFileReference writeStream

3.2. Document Properties

A PDFDocument can be configured with a specific format, orientation, compression and display mode, as we show next.

PDFDocument new
   format: PDFA3Format new;
   add: PDFPage new;
   exportTo: 'A3.pdf' asFileReference writeStream

PDFDocument new
   format: PDFA3Format new setLandscape;
   add: PDFPage new;
   exportTo: 'A3landscape.pdf' asFileReference writeStream

PDFDocument new
   uncompressed;
   add: PDFPage new;
   exportTo: 'uncompressed.pdf' asFileReference writeStream

pdfdoc := PDFDocument new fullPage.

pdfdoc := PDFDocument new zoom: 400.

pdfdoc := PDFDocument new continousPages.

pdfdoc := PDFDocument new zoom: 200; continuousPages.

3.3. Setting Meta Information

Each PDF document contains a set of information about its origins. These data are not to be overlooked, especially if your document is intended to contribute to an EDM (Electronic Document Management) system or is part of an editorial workflow. With this information it is possible to search among a set of PDF documents and select, for example, those written by a particular author or those for which certain keywords have been specified.

Artefact implements this information by using an instance of PDFMetaData. To each instance of PDFDocument, an instance of PDFMetaData is associated and is accessible using the message metaData. By default, the producer is set to 'Artefact'. You can specify the document title, subject or a short summary, the name of the author, a list of keywords and the document creator.

The following example generates a new document and its meta data information:

pdfdoc := PDFDocument new.

pdfdoc metaData
   title: 'Document title';
   subject: 'subject of the document';
   author: 'The Pasta Team';
   keywords: 'cool rock best';
   creator: 'Pharo'.

4.1. Page Creation

A page is represented by an instance of the class PDFPage. Creating is a page is simply done by sending the message new to the class.

   page := PDFPage new.

Sending the message add: to a document with a page as argument will append the page to the document.

   pdfdoc := PDFDocument new.
   page := PDFPage new.
   pdfdoc add: page.

By default, a page takes the dimensions and orientation of its document. If your PDF document is A4 landscape, all added pages will use these settings. However, Artefact can assign specific dimensions and orientation to each page, allowing one document to have a mix of pages with different characteristics. To allow this, each instance of PDFPage understands the message format:, which takes an instance of PDFFormat as argument.

The following example creates a two-page document. The first uses the default format of the document, the second is in A4 landscape.

   pdfdoc := PDFDocument new.
   page1 := PDFPage new.
   page2 := PDFPage new format: (PDFA3Format new setLandscape).
   pdfdoc add: page1; add: page2.

4.2. Templates

A template is an instance of class PDFTemplate, which inherits from the class PDFPage. It is a page with predefined contents that will act as the background page on which you will draw or add your components. For example, it can be composed of a header for a letter, a header and a footer for a report, or a delimited surface.

The package Artefact-Examples-Demos-Templates offers two example of template to create CD or DVD sleeve pages. The following code snippet produces a A4 page on which the outlines of a CD sleeve are drawn.

   pdfdoc := PDFDocument new.
   cover := PDFCompactDiscTemplate new.

A template is defined using the message drawTemplate which adds the Artefact elements to the page. This builds the page background. For example, the code of the CD template is below. (As it is relatively straightforward we do not explain the code here.)

PDFCompactDiscTemplate>>drawTemplate
   self add: ((PDFRectElement
      from: 10 mm @ 10 mm
      dimension: 240 mm @ 120 mm)
      dotted: self dotted
   ).
   self add: ((PDFLineElement
      from: 130mm @ 10mm
      to: 130mm @ 130mm)
      dotted: self dotted
   ).

5.1. Composing and Placement

Artefact's elements have a generic behavior that manages their location on a page as well as their dimensions. The Artefact coordinate system is used to place components. Values can be expressed in several units such as mm, cm or inch. The origin of the coordinate system is the top left of a page.

   PDFTextElement from: 15 mm @ 30 mm

   PDFRectElement from: 15 mm @ 30 mm to: 90 mm @ 80 mm

   PDFRectElement from: 15mm @ 30 mm dimension: 50mm @ 40mm

5.2. Simple Elements

The package Artefact-Core-Elements-Basic contains elementary components. There are grouped in three categories: text, images, and geometric forms.

5.3. Text and Images

To write text on a page, use instances of PDFTextElement. The method text: sets the text to be displayed. The class method from:text: supports positioning and text definition.

   PDFTextElement from: 15mm @ 30mm text: 'hello!'

Using the PDFJpegElement class, images in JPEG format can also be inserted in a document, using the fromStream: and from:dimension:fromStream: class messages. The messages width: and height: set the size of the image while respecting its original aspect ratio.

The following example generates a PDF document with one page. This page contains one image placed at two different locations. In the first case, the image is 80mm in width and 30mm in height. In the second case, the width is 80mm and the height is automatically computed keeping the original image ratio.

| pdf page |
pdf := PDFDocument new.
page := PDFPage new.
page add: (
   PDFJpegElement
      from: 10 mm @ 10 mm
      dimension: 80 mm @ 30 mm
      fromStream: (FileStream fileNamed: '/home/enterprise/image.jpg')).
page add: ((
   PDFJpegElement
      fromStream: (FileStream fileNamed: '/home/enterprise/image.jpg'))
      from: 10 mm @ 50 mm; width: 80 mm).
pdf add: page;
pdf exportTo: (FileStream forceNewFileNamed: '/home/enterprise/image.pdf')

PDFLineElement from: 15mm @ 30mm to: 90mm@170mm

PDFLineElement from: 10mm @ 20mm angle: 70 length: 50mm

PDFRectElement from: 10 mm@10mm dimension: 100 mm @ 30 mm.

   PDFRectElement from: 10mm@10mm to: 110mm@40mm

PDFPolygonElement
   from: 10mm@10mm
   points: { 30mm@30mm . 15mm@40mm . 5mm@20mm }

PDFCircleElement center: 100mm@100mm radius: 50mm

PDFBezierCurveElement
   from: 10mm@50mm
   points: { 0mm@0mm. 100mm@20mm. 150mm@0mm. 50mm@50mm }

5.4. Composite Elements

Artefact comes with a rich set of high-level components, grouped in the package Artefact-Core-Elements-Composites. These components are the result of the assembly of single components and other high-level components. They are used to create layouts and complex contents with minimal coding and a high degree of reuse. These components can be used in several different applications and materials. They are divided in three areas: management of text, drawing arrows and reporting.

PDFArrowElement from: 10mm@10mm to: 100mm@30mm

PDFDoubleArrowElement from: 10mm@80mm to: 100mm@150mm

PDFDataTableElement new
   data: #(
      #('Smith' 'Peter' 43)
      #('Jones' 'Mickael' 25)
      #('washington' 'robert' 30) );
   from: 10mm @ 20mm;
   dimension: 150mm @ 60mm

PDFDataTableWithColumnsCaptionElement new
   captions: #('Name' 'Surname' 'Age');
   data: #(
      #('Smith' 'Peter' 43)
      #('Jones' 'Mickael' 25)
      #('washington' 'robert' 30)
   );
   from: 10 mm @ 20 mm;
   dimension: 150 mm @ 60 mm

(PDFDataTableWithColumnsCaptionElement new
   captions: #('Name' 'Surname' 'Age');
   data: #(
      #('Smith' 'Peter' 43)
      #('Jones' 'Mickael' 25)
      #('washington' 'robert' 30)
   );
   from: 10 mm @ 20 mm;
   dimension: 150 mm @ 60 mm;
   customizationBlock: [ :cell :x :y :data |
      (x = 3 and: [ y > 1 ]) ifTrue: [
         (data > 30) ifTrue: [ cell text: 'Older than 30' ]
      ]
   ])

6.1. Stylesheet Elements

Defining a stylesheet allows one to specify specific presentation attributes for a set of elements. These attributes can also be set directly for an element. We show here the different attributes and how to set them for an element.

PDFTextElement
   from: 10mm@15mm
   text: 'My title'
   font: ((PDFTimesFont size: 24 pt) bold).

   (PDFCourierFont size: 20 pt) getStringWidth: 'hello'

(PDFCourierFont new)
   getIdealFontSizeForTheString: 'hello' width: 15 cm

((PDFArrowElement from: 125 mm @ 40 mm to:  100 mm @ 80 mm)
   dotted: (PDFDotted new length: 2 mm; space: 3 mm)).

PDFRectElement new
   from: 10 mm @ 10 mm;
   dimension: 100 mm @ 30 mm;
   fillColor: (PDFColor r: 255 g: 0 b: 0);
   drawColor: (PDFColor r: 0 g: 0 b: 255).

PDFTextElement new
   textColor: (PDFColor greyLevel: 128);
   from: 10 mm @ 50 mm;
   text: 'A text in blue';

   (PDFRectElement from: 10 mm @ 10 mm dimension: 50 mm @ 50 mm)
      thickness:  2 mm

(PDFFormattedTextElement from: 0 mm @ 0 mm dimension: 100 mm @ 10 mm)
   alignment: (PDFAlignment right);
   text: 'At right!'

6.2. Abstracting a Style

A document is associated to a default stylesheet whose properties are applied to any element that does not specify its own properties. For example, if you create a PDFTextElement without setting a font and text color, the color of text and the fonts set in the document will be used.

The default stylesheet is always filled up by Artefact with sensible defaults. That's why you did not have to specify values of style in the previous examples. You can access the stylesheet using the message styleSheet. To change the values of the default style, you simply change the properties of the stylesheet, for example as follows:

myDocument := PDFDocument new.
myDocument styleSheet
   textColor: (PDFColor r: 0 g: 100 b: 200);
   font: (PDFHelveticaFont size: 32pt) italic.

Artefact styles form a tree. Each sub style points to its parent and the root of styles is the default style attached to the document. This way properties can be customized and default behavior can be reused when needed.

myDocument := PDFDocument new.
myDocument styleSheet > #quote
   textColor: (PDFColor r: 0 g: 50 b: 200);
   font: (PDFCourierFont size: 8pt) italic.

(PDFTextElement from: 5cm @ 5cm)
   text: 'my Quote with the quote style'; style: #quote

(PDFDataTableWithColumnsCaptionElement
   from: 10 mm @ 20 mm dimension: 190 mm @ 60 mm)
      captions: #('Name' 'Surname' 'email');
      data: #(
         #('Smith' 'Peter' '[email protected]')
         #('Jones' 'Mickael' '[email protected]')
         #('washington' 'robert' '[email protected]'));
      style: #dataTableWithColoredCaption;
      yourself).

pdfdoc := PDFDocument new.
pdfdoc styleSheet > #dataTableWithColoredCaption > #caption
   fillColor: (PDFColor r: 158 g: 158 b: 79);
   drawColor: (PDFColor r: 158 g: 158 b: 79).
pdfdoc styleSheet > #dataTableWithColoredCaption margin: 4 pt.
pdfdoc styleSheet > #dataTableWithColoredCaption > #cell
      alignment: PDFAlignment right.

7.1. Clock Creation

First create the class of your element and generate accessors for its variable time that will contain the time to display.

PDFComposite subclass: #PDFClockElement
   instanceVariableNames: 'time'
   classVariableNames: ''
   category: 'Artefact-Tutorial'

The two relevant methods for Artefact are defaultStyle and getSubElementsWith:styleSheet:. The first one must return a collection of PDFElements (basic or composites). The second one must return a symbol that associates the elements with a style definition. However it's not necessary to define this style in your document, Artefact will use the default style instead.

Define the default style:

PDFClockElement>>defaultStyle
   ^ #clock

Then define the method that will draw the clock. As a first approximation, this method just returns a circle:

PDFClockElement>>getSubElementsWith: aGenerator styleSheet: aStyleSheet
   ^ { PDFCircleElement from: self from to: self to }

The circle will be drawn depending on this composite position and size. We are using from: to: for the circle instead of center:radius: because it's easier for us to create a clock using the boundary box of the circle.

To complete the clock, we add the hands using two PDFArrowElements and a filled little circle in the middle:

PDFClockElement>>getSubElementsWith: aGenerator styleSheet: aStyleSheet
   | hourAngle minuteAngle |
   hourAngle := Float pi / 2 - (time hour12 * 2 * Float pi / 12).
   minuteAngle := Float pi / 2 - (time minute * 2 * Float pi / 60).
   ^ {
      (PDFCircleElement from: self from to: self to).
      (PDFCircleElement
             center: self center radius: self dimension x * 0.05).
      (PDFArrowElement
             from: self center angle: hourAngle length: dimension x * 0.25).
      (PDFArrowElement
             from: self center angle: minuteAngle length: dimension x * 0.45)
   }

Don't be afraid about the two angle calculus, it's just to convert hours and minutes to radian angles.

At this time, your PDFClockElement is already usable and fully integrated into Artefact. We can insert it into a PDF document and export it:

PDFDocument new
   add: (PDFPage new add: ((
      PDFClockElement
         from: 2 cm @ 2 cm
         to: 10 cm @ 10 cm) time: Time current));
   exportTo: 'clockTutorialStep1.pdf' asFileReference writeStream

7.2. Make the Clock Personalizable

Your clock is already personnalizable independently of other elements because you previously defined its style as #clock. This is shown below:

| doc |
doc := PDFDocument new.
doc add: (PDFPage new add:
   ((PDFClockElement from: 2 cm @ 2 cm to: 10 cm @ 10 cm)
      time: Time current)).
doc styleSheet > #clock
   drawColor: (PDFColor r:180 g: 24 b:24);
   fillColor: (PDFColor r:230 g: 230 b:10).
doc exportTo: 'clockTutorialStep2.pdf' asFileReference writeStream

At this time, you don't have defined specific styles for sub elements of your clock. Consequently, you will not be able to personalize each element with different styles (so you cannot have hands of differents colors for example). To increase personalization possibilities, you should define specific styles for sub elements you reuse, as follows:

PDFClockElement>>getSubElementsWith: aGenerator styleSheet: aStyleSheet
   | hourAngle minuteAngle |
   hourAngle := Float pi / 2 - (time hour12 * 2 * Float pi / 12).
   minuteAngle := Float pi / 2 - (time minute * 2 * Float pi / 60).
   ^ {
      (PDFCircleElement from: self from to: self to).
      (PDFCircleElement
         center: self center radius: self dimension min * 0.05).
      ((PDFArrowElement
         from: self center angle: hourAngle
         length: dimension min * 0.25) style: #hourHand).
      ((PDFArrowElement
         from: self center angle: minuteAngle
         length: dimension min * 0.45) style: #minuteHand)
   }

As you can see, we just send the message style: to each subelement that we want to define a specific style.

Now, we can personalize each hand as follows:

| doc |
doc := PDFDocument new.
doc add: (PDFPage new add: ((PDFClockElement
   from: 2 cm @ 2 cm to: 10 cm @ 10 cm) time: Time current)).
doc styleSheet > #clock
   drawColor: (PDFColor r:180 g: 24 b:24);
   fillColor: (PDFColor r:230 g: 230 b:10).
doc styleSheet > #clock > #hourHand
   drawColor: (PDFColor r:0 g: 45 b:200).
doc styleSheet > #clock > #minuteHand
   drawColor: (PDFColor r:0 g: 200 b:45).
doc exportTo: 'clockTutorialStep4.pdf' asFileReference writeStream

This gives the clock hands have different colors. Moreover, like for any element in Artefact, you can specify a style for a given instance of a PDFClockElement, allowing you to reuse and adapt each clock:

| doc |
doc := PDFDocument new.
doc add: (
   PDFPage new
      add: (
         (PDFClockElement from: 2 cm @ 2 cm to: 10 cm @ 10 cm)
            time: Time current);
      add: (
         (PDFClockElement from: 12 cm @ 2 cm to: 20 cm @ 10 cm)
            time: Time current;
            style: #apocalypseClock)).
doc styleSheet > #clock
   drawColor: (PDFColor r: 180 g: 24 b: 24);
   fillColor: (PDFColor r: 230 g: 230 b: 10).
doc styleSheet > #clock > #hourHand
   drawColor: (PDFColor r: 0 g: 45 b: 200).
doc styleSheet > #clock > #minuteHand
   drawColor: (PDFColor r: 0 g: 200 b: 45).
doc styleSheet > #apocalypseClock
   fillColor: (PDFColor r: 244 g: 221 b: 25);
   thickness: 2 mm;
   roundCap: true.
doc styleSheet > #apocalypseClock > #minuteHand
   drawColor: (PDFColor r: 240 g: 6 b: 7);
   thickness: 1 mm.
doc exportTo: 'clockTutorialStep5.pdf' asFileReference writeStream