SalesKing Documentation » SalesKing API

h1(title). PDF API

The SalesKing uses the pdfLib for creating PDF documents. You can customize any generated pdf files (f.ex. Invoice) by uploading PDF templates into the system.

Customizing the pdf templates is not really difficult. Despite your will to read the docs and spending some time trying, you need Adobe´s Acrobat Writer and a Acrobat Writer plugin to edit the data placeholders: the "Block plugin":http://www.pdflib.com/de/download/pdflib-familie/block-plugin/

h1. Contents

{{toc}}

h1. Audience

This document is intended for SalesKing users which want to customize the pdf templates. 

It assumes that you understand the basics of Adobe Acrobat and the pdfLib-Block plugin. Further you should have some basic knowledge of how to create a pdf file from various resources as well as some graphic design knowledge.

For more information about those things, see the Additional resources section at the bottom of this document.

If you master the art of pdf customizing you definitely have a sharp knife to cut down on those ugly invoices and official documents ... mostly derived from Word or other non-layout-suited Software.

h1. PDF Templates in General

A pdf template can be any pdf file. but first the normal steps you take in customizing:

# make a layout in photoshop / indesign / gimp / freehand

# generate a pdf

# download one of our default templates (or start from scratch)

# open acrobat writer and export the blocks from the default template to your new pdf. (Check the Block plugin menu to see all options)

# customize the blocks on you new pdf (block size/text/font/position/content/..)

# upload the pdf into SalesKing  

# check the output 

h2. Conventions

There is a small set of conventions you need to follow:

* all fonts used in blocks must be present on the system generating the output pdf (our server)

* Block names must match a special syntax (also see [[Placeholders]]) 

* the template size should not exceed 1mb

h1. Template Blocks

A Block is placeholder which gets substituted with data/text from the system. 

It is not required to have a standard set of blocks in a template. 

h2. Block name

The block name defines the matching data field from the application.

If no matching data field can be found the block is left empty.

Example of blocknames:

<pre>

number

client.address_field

page_number

settings.footer

</pre>

h2. Block position

The data/text is rendered at the position of the block. Depending on the block properties (f.ex. type:textline, textflow, image, align) the actual placement of the text can be influenced. 

h2. Block properties

The block properties carry information about how to output the data. 

The deep details of all block properties can be studied in the pdfLib API and the block manual. 

Therefore here just a list of options you are likely to use frequently:

|_.Property|_.Description|

|font + fontsize|the font must be present on our system!|

|textflow |mutiline text blocks must use this option which reveals more settings for the text flow|

|textflow alignment |text alignment in texflow boxes|

|custom properties| values defined by the SalesKing - depending on template type|

h2. Custom Block properties

Some blocks go beyond simple text rendering, f.ex. the invoice items table or page numbers.

You can influence such output with a set of custom fields. The custom property name and values are described inside the specific template type.

*Custom property detection*

To make sure a template can be handled, we have a multi-stage fallback mechanism for (most) custom properties.

It is important to know the way of property detection, to understand why something comes out like it does.

The option stages in their order of detection/use:

# settings inside the template´s custom block property

# user settings inside the SalesKing

# hardcoded options from the SalesKing core

If any setting is empty we go down the line and use the next available.

h3. show_on_page - Show a Block only on some pages

This custom property is available to all blocks.

|_.Property Name|_.Type|_.Example|_.Description|_.Available Markup|

|show_on_page|String|last|Show a block only on some of the generated pdf pages.|*last* => only on last page, *first* => show only on first page, *any number* => show on page with this number |

!http://pm.salesking.eu/attachments/download/43! 

h1. Template Types & Details

Jump to a template type to read more about the implementation details:

* [[PDFApi Invoice Templates|Invoice Templates]]

h1. Additional Resources

* "pdfLib Block plugin for Acrobat Writer":http://www.pdflib.com/de/download/pdflib-familie/block-plugin/

* "German pdfLib Manual":http://www.pdflib.com/de/developer/technische-dokumente/handbuecher/