RazorAntMain.Core.Pages.Page RazorAntMain.Core.Pages.Page


Creating an Invoice Template

Do you really need to make a custom invoice template?

While I won't ever take out the ability to make a custom invoice template I do try to enable common edits to be made in the app itself. For example:

  • In the Business Editor you can add a high-res company logo that will show up on the invoices.
  • The Business Editor will also let you translate the labels used on the invoice to match your own company terms or language.
  • You can use Plain Jane (Windowed) to make sure the invoice can be tri-folded and take advantage of a windowed envelope.

If you still need changes, read on. If you are doing something unique or have suggestions about the template system let us know.

Some background on how PDFs are made

Before I get started on making a custom template let's be clear on how ProfitTrain makes PDF invoices.

The invoice comes up with an HTML representation. That HTML is put into an off-screen WebView; which is then handed off to the print system; which generates a PDF; which is then stored in the ProfitTrain database. (deep breath)

PDFs are stored with a cache flag that notes if a PDF representation is out-of-date. If you select an invoice and the representation is out-of-date ProfitTrain will automatically regenerate the PDF. If an invoice's PDF representation becomes out-of-date due to an outside action (such as editing your business contact info in the Business Editor) you may notice a warning above the PDF that encourages you to rebuild.

PDF rep out-of-date

You can manually rebuilt an invoice PDF at anytime by right clicking an invoice in the main table and choosing Rebuild PDF. This is particularly handy as you edit your custom template to see how your edits are coming along.

Rebuild PDF

Getting started

You may want to read this help article in its entirety before following along and building your own custom template.

While you can create a template from scratch you'll probably find it's much easier to start with one of our defaults. To get started let's download a slightly modified copy of the default Plain Jane template:

Download and unzip: Custom Template.PTInvoiceTemplate

ProfitTrain Invoice Templates are bundles. In OS X, bundles are simply folders that appears as a single file or resource in the Finder. To look inside a bundle right click the file and choose Show Package Contents. Inside our bundle you'll see a few files, including:

  • Info.plist -- Stores author info and details for each label used inside the invoice.
  • template.html -- the template file itself.
  • and other various CSS and image files the template uses.

The name of your template as seen in the application is the name of this bundle, so to get started rename the bundle from Custom Template.PTInvoiceTemplate to something more specific. Remember to keep that .PTInvoiceTemplate extension so OS X knows what kind of bundle it is.

If you name a custom template bundle the same name of an internal bundle the internal bundle will be used. To prevent a name collision consider prefixing the name of the template bundle with your company's initials.

Next edit the Info.plist file with some creator info and the minimum version of ProfitTrain this invoice template supports.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
<plist version="1.0">
 <string>Your Name</string>

Note: You will notice a key in this plist file called CBLabels with a large array of dictionary entries. These are used for user translations and will be covered later.

To install your custom template you need to place it the Application Support folder. You can do this manually or by double clicking the bundle in the Finder.

/[HD]/Users/[you]/Library/Application Support/ProfitTrain/InvoiceTemplates/

If you don't have an existing invoice, make one. While viewing an invoice PDF, in the bottom toolbar, you can change the template it uses. Choose the new template. The custom template we downloaded was based on Plain Jane, with one difference, it defines a red font color for most of the text. If you don't see red text or your custom invoice name try restarting ProfitTrain and retrace the installation steps.

Adding some style

Red text isn't very attractive, so let's change it to black. To do so we are going to edit the style.css file inside the bundle.

If you don't typically edit HTML and CSS you probably need an editor. I would recommend against using the built-in TextEdit.app for HTML or CSS but instead recommend the free TextWrangler or it's paid-for cousin BBEdit. Personally I enjoy using TextMate. All three of these editors support dragging bundles down to the their respective dock icons to open up an editor with all the resources of that bundle in a drawer or column. Very handy.

Editing the style.css file we immediately see a declaration for the body and inside the color attribute is set to red.

 font-family: Optima, Verdana, Arial, Helvetica, sans-serif;
 font-size: 11pt;
 margin: 0;
 padding: 0;
 color: red;

If we delete the line that says color: red;, color will use a default value which is black. Delete the line with the color declaration, and only this line, then click save.

To see our changes highlight the invoice in ProfitTrain you setup to use the custom template then right click it's row in the invoice table, then choose Rebuild PDF. You should now see the font using the color black once more.

This is the basic workflow of creating and editing a custom invoice template to meet your needs.

MGTemplateEngine Basics

The template engine we use behind the scenes is MGTemplateEngine and you can go there to read all the delicious details. Here are some of the basics.

You design your invoice as if you were designing a normal web page. Use <h1>, <p>, <table> and all the other standard HTML tags. To access the details of the invoice you will use MGTemplateEngine statements. There are two main types. First are output statements, which are replaced with the value they represent at process time:


Because some of these values are strings that may contain invalid HTML you are encouraged to use .escapedForHTML at the end of string attributes. For example:


Some properties will process HTML before hand, such as mailingAddressAsHTML and messageAsHTML. If it ends with AsHTML you don't need to escape it.

Then there are command statements which let you loop through collections or do boolean logic like:

{% for lineItem in invoice.lineItemsOrderedByDateAndDescription %}
{% /for %}

{% if invoice.isPaid %}
<!-- some cool HTML to represent the invoice is paid -->
{% /if %}

For the most part you should be able to use the logic of the default template for most rendering. The line item table code for example goes into a lot of semi-complex if/else structures to attempt to keep the use of columns as simple as possible. IE: If you use line items of all the same cost type we can typically show a column to line up all those cost details, else we will show them inline after the line item description.

Typically, I envision people editing the style.css file to adjust visuals and then adding or tweaking the HTML in template.html to meet their custom invoice needs. If you do have trouble or need assistance let us know.

Random Tips

When editing the template.html file you may notice we import the CSS with a randomNumber appended to the end of the filename. We do this to help avoid WebKit from caching the file and frustrating you as you edit an invoice design.

<link rel="stylesheet"
 type="text/css" />

Similarly, for any images or other resources you decide to include in your template bundle, be sure to prefix them with {{pathToBundle}}. If you leave this out we won't be able to load the resources inside the internal webview.

If you are trying to debug something in your template you may want to see the raw HTML being generated for the WebView itself. While viewing an invoice go to the main menu. Under View choose Visualization of Invoice and then HTML Source or WebView. Using these menus you can toggle the view under the table inside of the invoice view. Very handy for viewing the html generated.


Previously one would build an invoice template and it would be littered with hard coded words like "Invoice" and "Client". ProfitTrain however is built with an international focus and as such we encourage template designers to use our labels system. Doing so enables users to customize and/or translate the language used on invoices without touching the HTML. Here is how it works.

Instead of hard coding the word "Invoice" or "Client" you instead use a output statement like {{business.labels.XX_Invoice}} and {{business.labels.XX_Client}}. "XX" being your company's initials to avoid a name collision. Then in the Info.plist add a key CBLabels with entries for each of your labels like this:


Note: Currently english(en) defaults are the only words we import and use. You must supply a value for "en". Others may be supported in the future.

Each time your template is loaded into ProfitTrain a word pair is created (if not present) for each business in ProfitTrain. These word pairs can be edited using the Business Editor as seen here:

Translation tab in Business Editor

While you are designing you can free form add word pairs using the New button at the bottom of the table, just be sure to add them to the plist before sharing the invoice to make sure those pairs work for others.

Telling invoices to use your new template

If you create a new template and want to make sure all new invoices use this template you need to update the business and client defaults. To edit the business default (which is copied to new clients) go to the Business Editor and the Defaults tab. For templates use the pulldown and choose your new custom invoice template. To copy this default to the current clients use the Update Exsisitng Client... button and push this change down to all the current clients of this business in the system.

That will make sure all future invoices use this new template. To adjust current invoices to use the template you can use the pulldown under the PDF view for each invoice before sending it out to the client.

If you have a large back catalog of invoices and want to update the whole database to use this new invoice template you need to go to the command line (sorry -- hope to make this possible in the app some day).

Make sure you have a backup and ProfitTrain is not running. Then use the terminal to change your current directory:

$ cd /Users/yourname/Library/Application\ Support/ProfitTrain/

Enter the sqlite command line with the ProfitTrain database.

$ sqlite3 ProfitTrain.sqlite

Then issue this command to change the currentTemplate of all invoices in the app to use your new one. Do not include the bundle extension in the name.

sqlite> update invoices set currentTemplate = 'Your Template';

You won't see any count of updated rows like you might expect from other sql tools. So to test exit sqlite with

sqlite> .exit

And open ProfitTrain to see how it went.

Editing the default margins

Starting in 2.0b22 ProfitTrain uses a default margin for invoice printing. For most people these defaults are fine however if you are looking for a full-bleed effect and need to edit them you can use the defaults terminal command.

First make sure ProfitTrain is not running. Then open a terminal and type something like:

defaults write com.clickablebliss.profittrain CBPrinterBottomMargin 27.0
defaults write com.clickablebliss.profittrain CBPrinterTopMargin 27.0
defaults write com.clickablebliss.profittrain CBPrinterLeftMargin 54.0
defaults write com.clickablebliss.profittrain CBPrinterRightMargin 54.0

Those values there are the current defaults. If you ever want to restore a default use

defaults delete com.clickablebliss.profittrain CBPrinterBottomMargin

Need help?

If you have any questions or suggestions, please contact us.