To adjust the layout of your invoice and other printing templates, you'll need basic HTML and CSS knowledge. Furthermore, you'll need a copy of Checkout to test your results.
To get started, first download a copy of the default Checkout templates
After downloading this file, doubleclick the 'templates.zip' file on your Desktop, the resulting file is called 'Default Templates.checkouttemplate'. The templates file is a so called bundle, which is a special type of folder, that is shown by the Finder as a single file. To show it's contents, control-click the file and choose 'Show Package Contents...' from the contextual menu that appears.
You can edit the template files in your text editor of choice. If you use TextMate, you can simply drop the entire templates file on its icon to get a listing of all the individual template files in the bundle.
To preview the result of your work, launch Checkout and open the example store. Then doubleclick your modified 'Default Templates.checkouttemplate' from the Finder. Checkout will then offer to replace your original templates with your own modified version. Whenever you reopen the example store, it is reset and will be loaded with the default templates again, so make sure check your changes before logging out.
To install your modified templates, simply login to your store and doubleclick the templates file from the Finder.
Checkout works with both normal printers and receipt printers. Each of the templates for normal printers is divided over three different template files, the ones ending in 'header.tpl', 'table.tpl' and 'footer.tpl'. The templates for receipt printers are the files whose names end on 'ticket.tpl'.
If you browse through the pre in the default checkout templates, you'll see various pieces of pre used throughout the templates. There are two different types of variables you can use in your templates, the first represent data from your Checkout database, the second return localized strings and formatted dates and currency. Finally you can use some functions in your templates, like 'for' loops and 'if' statements.
The best way to explore which variables are available is to browse through the default templates. Some of the available variables in the invoice template are: $total, $total_with_tax, $invoicedate, $orderdate, $employee_name, $client_name, $client_address
One of the coolest features of Mac OS X is the way it automatically formats international dates and currencies. Here are some functions you can use in Checkout's templates to utilize this functionality.
$localized.money($total)This function returns a formatted string for any monetary amount you supply between the brackets, containing the correct currency symbol, decimal- and thousandsseparators.
$localized.long_date($invoicedate) $localized.short_date($invoicedate) $localized.only_date($invoicedate)These functions return a neatly formatted version of the date you supply within brackets. The first two combine the date and time, the only_date version returns just a medium length version of the given date. To customize the way these dates appear, go to the 'Formats' tab of the 'International' pane in System Preferences.
$convertDate($invoicedate)
If you want full control over the way dates appear on your printed documents, independent from your system settings, use this alternate method. To change the way the returned dates are formatted, edit the #def converDate($date) section at the top of each template. See the table below for a complete list of possible values for use in stead of the default "%d-%m-%Y" that's present in the templates.
| Directive | Meaning |
|---|---|
%a |
Locale's abbreviated weekday name. |
%A |
Locale's full weekday name. |
%b |
Locale's abbreviated month name. |
%B |
Locale's full month name. |
%c |
Locale's appropriate date and time representation. |
%d |
Day of the month as a decimal number [01,31]. |
%H |
Hour (24-hour clock) as a decimal number [00,23]. |
%I |
Hour (12-hour clock) as a decimal number [01,12]. |
%j |
Day of the year as a decimal number [001,366]. |
%m |
Month as a decimal number [01,12]. |
%M |
Minute as a decimal number [00,59]. |
%p |
Locale's equivalent of either AM or PM. |
%S |
Second as a decimal number [00,61]. |
%U |
Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. |
%w |
Weekday as a decimal number [0(Sunday),6]. |
%W |
Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0. |
%x |
Locale's appropriate date representation. |
%X |
Locale's appropriate time representation. |
%y |
Year without century as a decimal number [00,99]. |
%Y |
Year with century as a decimal number. |
%Z |
Time zone name (no characters if no time zone exists). |
%% |
A literal "%" character. |
$localized.string('Invoice')
Almost all of the words that are used in the default templates are wrapped in one of these $localized.string() functions. This way, for example, when Checkout runs in German, it will automatically replace 'Invoice' for 'Rechnung'. Whenever a word is not found, Checkout will display the original word. We recommend utilizing this same function around any label words you use in your own templates, especially when you intend to resell your templates to others. If we receive enough requests for a specific word, we'll add it to Checkouts dictionary of localized words. The dictionary of localized words is case sensitive, so where 'Invoice' is translated, 'invoice' may not.
Sometimes you'll have to determine something, before you know what to print. A good example is this pre snippet from the default 'invoice_header.tpl' file, where we determine how to display the clients name on the invoice:
#if $person_iscompany == True <b>$person_company</b><br /> $person_firstname $person_middlename $person_lastname<br /> #else <b>$person_firstname $person_middlename $person_lastname</b><br /> #end ifAnother thing that's heavily used in the template files is repeating a piece of HTML for each item in a list. A good example is the following pre snippet from the default 'invoice_footer.tpl' file, where we loop through all applicable taxes to print their names, rates and amounts:
#for $taxrate in $taxrates <tr> <td class="title">$taxrate['tax'].name ($taxrate['tax'].rate%):</td> <td class="number">$localized.money($taxrate['total'])</td> </tr> #end forIf you're familiar with programming concepts like these, you can experiment some more with these functions. In any other case, just leave them intact and adjust the formatting of the values within them.
Checkout renders all printouts live whenever you print or create a pdf. The templates are finally rendered by WebKit, the same engine that powers Safari. Since Checkout waits until your templates have completed rendering, it's possible to insert images and other items that are loaded from the web during printing. One thing to keep in mind is that printing will take longer, especially if you have a slow internet connection. And please keep in mind that printing could fail altogether if the server you are trying to reach is not available.