ProfitTrain HelpOther Topics
Website Links |
Creating an Invoice TemplateDo 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:
If you still need changes, read on. If you are doing something unique or have suggestions about the template system let us know.4 Some background on how PDFs are madeBefore I get started on making a custom template let’s be clear on how ProfitTrain makes PDF invoices. The invoice (with the help of MGTemplateEngine) 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. You can manually rebuilt an invoice PDF at anytime by right clicking an invoice in the main table and choosing Getting startedYou 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
The name of your template as seen in the application is the name of this bundle, so to get started rename the bundle from
Next edit the Info.plist file with some creator info and the minimum version of ProfitTrain this invoice template supports.
Note: You will notice a key in this plist file called 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.
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 styleRed text isn’t very attractive, so let’s change it to black. To do so we are going to edit the
Editing the
If we delete the line that says 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 This is the basic workflow of creating and editing a custom invoice template to meet your needs. MGTemplateEngine BasicsThe 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
Because some of these values are strings that may contain invalid HTML you are encouraged to use
Some properties will process HTML before hand, such as Then there are command statements which let you loop through collections or do boolean logic like:
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 Random TipsWhen editing the
Similarly, for any images or other resources you decide to include in your template bundle, be sure to prefix them with If you are trying to debug something in your template you may want to see the raw HTML being generated or the WebView itself. While viewing an invoice go to the main menu. Under LabelsPreviously 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
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: 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 templateIf 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 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 we 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:
Enter the sqlite command line with the ProfitTrain database.
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.
You won’t see any count of updated rows like you might expect from other sql tools. So to test exit sqlite with
And open ProfitTrain to see how it went. Editing the default marginsStarting 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 First make sure ProfitTrain is not running. Then open a terminal and type something like:
Those values there are the current defaults. If you ever want to restore a default use
Need help?If you have any questions or suggestions, please contact us. |