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 Professional and a Acrobat Professional Plugin to edit the data placeholders: the "Block plugin":http://www.pdflib.com/download/pdflib-family/block-plugin-35/

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)

* The fontnames are case sensitive

* 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. Fonts available

We have a couple of Free fonts available. If you have a commercial font(and a license for it), we are glad to make it available for you. 

Aller Bold.ttf

Aller Light.ttf

Aller.ttf

Anivers-Regular.otf

Arial.ttf

Ariblk.ttf

BergamoStd-Bold.otf

BergamoStd-Regular.otf

Calibri Bold Italic.ttf

Calibri Bold.ttf

Calibri Italic.ttf

Calibri.ttf

Cambria Bold Italic.ttf

Cambria Bold.ttf

Cambria Italic.ttf

Cambria.ttf

Candara Bold Italic.ttf

Candara Bold.ttf

Candara Italic.ttf

Candara.ttf

Candela-Bold.otf

Candela-Book.otf

Caviar Dreams Bold.ttf

Caviar Dreams.ttf

Cicle_Gordita.ttf

Cicle_Semi.ttf

Consolas Bold Italic.ttf

Consolas Bold.ttf

Consolas Italic.ttf

Consolas.ttf

Constantia Bold Italic.ttf

Constantia Bold.ttf

Constantia Italic.ttf

Constantia.ttf

contra.ttf

Corbel Bold Italic.ttf

Corbel Bold.ttf

Corbel Italic.ttf

Corbel.ttf

DejaVu Fonts License.txt

DejaVu Sans Bold.ttf

DejaVu Sans Condensed Bold.ttf

DejaVu Sans Condensed.ttf

DejaVu Sans.ttf

DejaVu Serif Bold.ttf

DejaVu Serif Condensed Bold.ttf

DejaVu Serif Condensed.ttf

DejaVu Serif.ttf

Delicious-Bold.otf

Delicious-Roman.otf

Droid Sans Bold.ttf

Droid Sans.ttf

Dustismo  Bold.ttf

dustismo.ttf

FontinSans-Bold.otf

FontinSans-Regular.otf

Gentium Basic Bold.ttf

Gentium Basic.ttf

Gentium Book Basic Bold.ttf

Gentium Book Basic.ttf

Georgiab.ttf

Georgia.ttf

lmsans10-bold.otf

lmsans10-regular.otf

lmsansdemicond10-regular.otf

New Cicle Fina.ttf

New Cicle Gordita.ttf

New Cicle Semi.ttf

Perspective Sans Bold.ttf

Perspective Sans.ttf

Pigiarniq Regular.ttf

Sansation Bold.ttf

Sansation Light.ttf

Sansation Regular.ttf

VeraBd.ttf

VeraMoBd.ttf

VeraMono.ttf

VeraSeBd.ttf

VeraSe.ttf

Verdanab.ttf

Verdana.ttf

vollkorn.otf

YanoneKaffeesatz-Bold.otf

YanoneKaffeesatz-Light.otf

YanoneKaffeesatz-Regular.otf

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 Professional":http://www.pdflib.com/download/pdflib-family/block-plugin-35/

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