History

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
h1. Contents

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.

PDF Templates in General

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

  1. make a layout in photoshop / indesign / gimp / freehand
  2. generate a pdf
  3. download one of our default templates (or start from scratch)
  4. open acrobat writer and export the blocks from the default template to your new pdf. (Check the Block plugin menu to see all options)
  5. customize the blocks on you new pdf (block size/text/font/position/content/..)
  6. upload the pdf into SalesKing
  7. check the output

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

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.

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:

number
client.address_field
page_number
settings.footer

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.

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

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:

  1. settings inside the template´s custom block property
  2. user settings inside the SalesKing
  3. hardcoded options from the SalesKing core

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

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

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

Template Types & Details

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

Additional Resources

pdf-api-show_on_page.png (5.2 kB) Ole Wiemeler, 26.05.2008 02:41 pm