Html to PDF

Use the PDF connector to create PDF files in your workflow. The connector uses HyperText Markup Language (HTML) to define the layout of your PDF pages and fully supports using FlowScript.

Html2Pdf Task Editor

Connector Output

The output from the connector is a standard file record.

General Tips & Tricks

• Write as simple HTML as possible by hand and use the preview button frequently. You will run into problems if you use code taken straight from WYSIWYG HTML editors. Gain some basic knowledge of how to code HTML Tables and using CSS style sheets and you will thank yourself later. Also it's great fun 🙂

• In most use cases, you want to take control over the page breaks in your document using the page-break-inside CSS property. Also set the border-collapse property to collapse borders.

• Do not use borders on table elements, instead specify borders on the table cells (<th/>, <td/>). This will prevent unwanted borders from being displayed when a page-break occurs inside a table.

Settings

This chapter describes the available settings in the PDF connector.

Operation / Output

Design

This is the default operation mode. The output PDF will contain the pages generated from your HTML/CSS code.

Design and...

In this operation mode, you can select to prepend and/or append a PDF file record to your designed PDF file. The prepend/append file works exactly as in the merge operation mode.

Merge

Use this operation mode to merge two PDF file records to a single PDF file. Select a file record containing a PDF file on the PDF 1 and PDF 2 tabs.

If you want to use specific pages from a PDF, uncheck the "Use all pages" checkbox and enter the page numbers in the Start-/End Page fields. These also supports Flow Script.

If nothing is entered in the Start-page input field, the first page will be used.

If nothing is entered in the End-page field, the last page will be used and if a page number higher than the total number of pages is entered - the last page will also be used.

Output PDF File Name

This string defines the filename-key value of the target file record and is required to have a value.

Design

HTML/CSS Editor

The connector supports the HTML 4.01 specification.

The document layout is defined using HTML/CSS. It's recommended to keep the code as simple as possible and build the layout using a bottom-up approach. If you are new to HTML, visit WordHtml. However if you use the generated code directly you will get disappointed as there are some important aspects to keep in mind. Most importantly, you need to use percentages instead of absolute values for width. Another great resource is W3Schools.

More information about the HTML/CSS editor features can be found in the Controlling the layout chapter.

Preview Layout

Clicking the Preview Layout button will create a PDF file using designtime data and open it in your default PDF viewer application. On most computers, the default browser will open PDF files. If you do not have any PDF viewer installed you download and install Acrobat Reader for free.

Tip: While editing your layouts it can be really helpful to set up the default pdf viewer application next to the Flow Studio application window.

The default PDF viewer placed next to the Flow Studio window

Page Layout

Page Size

The default setting for page size is A4-format. The page size selector lets you choose from the most common page sizes. The page size can also be defined manually.

Page Orientation

Choose between Portrait (default) and Landscape orientation.

Manual Page Layout

You can define a manual page size in DTP points. If enabled, these settings will override any selections made in the Page Layout selection drop down menus. Note that you will most probably have to adjust your page margins if you are defining a small layout.

Note:

• The total page width in DTP Points = the supplied width + Margin Left + Margin Right

• The total page height in DTP Points (excluding the page contents) = the supplied height + Margin Top + Margin Bottom

Page Margins

The margin sizes in DTP points. Note that you will need to adjust the default values to fit your selected page size. Use the preview feature to find out the correct settings for your specific layout.

Images / Signatures

If you need to insert images or flow signatures in your PDF document which are retrieved from within your workflow - you need to make sure to have them available as file records.

Signatures from the signature capture input provider is by default a file record with some extra fields ("mimeType" and "size") and are supported by the PDF connector as is.

The Images / Signatures field takes either a file record or a table of file records.

Adding a table containing images to the Images/signatures input box.

Combining several file records directly in the Images/signatures input box.

Overriding file names

In order to be able to differentiate between the images/signatures in the HTML code, you might need to override the filename component of the file records and give them unique and identifiable file names prior to passing them to the PDF connector. The image below shows a file name being overridden in an assignment step.

To position your image/signature in the document, the HTML IMG tag is used:

<img src=your_file_name.jpg height=40>

Supported image formats

The following image formats are supported by the connector:

• BMP

• GIF (with optional transparency)

• PNG (with optional transparency)

• JPEG

• TIFF (with optional transparency)

For other ways of adding images to your design you can checkout the Images section under Controlling the layout.

Controlling the layout

CSS / Styling

The CSS Stylesheet Editor

The connector supports the CSS Level 2 Specification, so you can use cascading style sheets to format your PDF documents. Even if you are creating a simple page layout, you will probably still want to use CSS for controlling page breaks inside your HTML elements (such as table rows and/or cells).

In addition, there is also support for gradients on backgrounds and rounded corners:

<!-- Example background gradient -->
<body style="background-color: #333; 
  background-gradient: #707; 
  background-gradient-angle: 60; 
  margin: 0;">

Learning HTML and CSS is out of scope of this documentation. However if you have issues getting your document layout to look as you expect - try to simplify the code and make sure you are not using any syntax feature outside of the supported specifications (CSS Level 2 and HTML 4.01). Keep it simple and try to make use of CSS classes to separate your styling from your content.

Images

Here are some example methods of adding images to your design in addition to using images from flow file records as described in the Images / Signatures setting section.

Image from Base64 encoded data

<img src="data:image/png;base64,iV...CC" height="40" />

Tip: You can easily find tools online which can encode images to Base64 string.

Image from URL

<img src="http://www.myserver.com/images/myimage.jpg" width="100" />

Image from NAS

<img src="\\myserver\myshare\myimage.jpg" width="80" />

Image from Flow Server hard drive

<img src="d:\images\myimage.jpg" height="50" />

If the file cannot be accessed during runtime, a red cross will be displayed on the PDF file in place of the image. Therefore Base64 is the most "secure way" of adding images because the image data will be stored within the HTML code.

Flow Variables

To insert a flow variable anywhere in your HTML code, type a starting curly bracket to display a list of available flow variables:

Table Iterator

You can easily iterate flow tables in the HTML code.

With the cursor placed just before the HTML code you want to repeat for each row in the flow table: Press Ctrl+Space to trigger the context-sensitive autocomplete menu and select the <iterate /> tag:

Move the ending tag (</iterate>) after the HTML code block you wish to repeat.

This is how it would look for a HTML table:

The next step is to select the flow table. Place the cursor in between the quotation marks for the table attribute and press Ctrl+Space to display a list of available flow tables. Use the arrow keys on the keyboard to select the table variable and then press enter to insert it into the HTML code.

Selecting the flow table to iterate

Next let's replace our static column values with values from the flow table. Place the cursor where you want the column data to appear and press Ctrl+Space to display the available table columns. And as before use the arrow keys and enter to select the variable.

Selecting the table column variable

Change the "preview" attribute to a suitable number which represents the real world data and use the Preview Layout button to see how your document will be rendered.

Designtime Tag

The Designtime tag can be used during the design process if you quickly want to see how a block of html code would be rendered if you were to add more of it. It is very similar to using the <iterate /> tag - but all contents will be removed during runtime.

The designtime tag is available in the autocomplete menu (Ctrl+Space)

Barcodes

There is built-in support for adding barcodes straight from your HTML code. To use it, add a <barcode /> tag using the autocomplete menu (Ctrl+Space).

Note that the cursor needs to be outside any <iterate /> and <designtime /> tags for the main context menu to work - it's context based.

Selecting the <barcode /> tag

To select barcode type; move the cursor inside the quotation marks on the type="" attribute and press Ctrl+Space.

Selecting barcode type

We'll then set the value of the barcode. To see a valid example value for the selected barcode type, place the cursor inside the barcode tag value and press Ctrl+Space:

Selecting an example value using autocomplete

You can define the size of the generated barcode using the height and width attributes. If you need to change the barcode color, place the cursor after the last attribute in the <barcode /> tag, type a space and then press Ctrl+Space to display attributes which can be added:

Selecting the textcolor attribute

Use the Preview Layout button to preview any changes you make.

Let's insert a flow variable as the barcode value: Remove the example value if you inserted any and then type a starting curly bracket to display a list of available flow variables:

Selecting a flow variable as value for the barcode

If you want to display the barcode inside an iterator this is also possible. Now when it's been created, you can easily cut the whole tag and paste it inside a <td></td> tag for example. Then use the autocomplete menu to insert a table column variable:

Manual Page Break

To insert a page break anywhere in your HTML code, use the autocomplete menu to select the <pagebreak /> tag. Now the HTML code coming after this tag will appear on a new page. Note that any "fixed" elements such as header and footer will be cleared after the page break and therefore you need to redefine any header/footer HTML after the <pagebreak /> tag.

CSS Property: page-break-inside

The CSS property page-break-inside is used by the connector to control how page breaks are rendered for certain html elements.

Two values are supported: auto (default) and avoid.

With the default values there are no rules defined to transfer html-blocks or words to the next page. The page break will simply happen when the page runs out of space (which might result in text being cut through the middle):

Using td { page-break-inside: avoid; } - words located on the bottom of a page will be transferred to the new page without getting split. The same goes for th, p, span and for any text in any other tags:

With table { page-break-inside: avoid; } - if a table row does not fit on the current page, then the whole row will be transferred to the next page. If the row height is larger than the whole page height, it doesn’t make sense to transfer it and the value of page-break-inside will be ignored.

Known cosmetic issues

If page-break-inside: auto; has been set on the table and page-break-inside: avoid; has been set on the cell, then an empty part of table cell can be rendered at the end of page:

If page-break-inside: avoid; has been set on the table and the row is bigger than the rest of page but will fit on the next page - it will be transferred to the next page and a lot of space will be left empty on the previous one:

Tip: To prevent unwanted borders to be displayed on the rest of the page after a page-break - disable borders on the table element and only use borders on the table cells.

Headers, footers and watermarks

An HTML element with the CSS property position: fixed; will be rendered on every page (up until any usage of the special <pagebreak /> tag) and can therefore be used as headers/footers or watermarks.

Important: These elements will ignore the page margins. If you need to fit a 50px high header on your pages and want a 20px high margin to the page contents, you need to update the page top margin to 70px to make room for your page header.

Example header and footer CSS code:

.header {
    position: fixed;
    left: 20px;
    top: 20px;
}

.footer {
    position: fixed;
    left: 20px;
    top: 750px;
}

Note:

Example HTML document using the header and footer:

<body>
    <div class="header">
        logo
    </div>
    <div class="footer">
        disclaimer
    </div>

    <p>
        page content...
...

Adding Fonts

The connector will be able to use fonts installed on the machine hosting the connector.

To install a font in Windows; right-click the .ttf-file and select "Install", then restart the Flow Server.

To specify the font face in HTML, add the font-family style attribute to your HTML element or CSS:

font-family: 'DengXian Light';

Reference

DTP Point

DTP points on Wikipedia

1 DTP Point = 1/72 inches = 25.4/72 mm = 0.3527 mm

File Record

A file record is a flow record with two fields: filename and data.

/* FlowScript for a file record */
let fileRec = [filename: 'mySignature1.png', data: mySignatureRecord.data];
return fileRec;