SQL-Ledger allows most documents to be generated according to a template system. This allows financial statements, invoices, orders, and the like to be customized to meet the needs of most businesses. Company logos can be inserted, the format can be radically altered, one can print letters to be included with checks to vendors instead of the checks themselves, and the like. In the end, there is very little that cannot be accomplished regarding modification of these documents with the template system. One can define different templates for different languages, so that a customer in Spain gets a different invoice than a customer in Canada.
The only template that uses a text-only format is the POS receipt. This example provides the simplest way to understand the template system. The first two lines are: <%company align=center width=40%> <%address align=center width=40%> The first line tells SQL-Ledger to print the company name as passed to it via a variable, centered, with a page width of 40 characters. The second line does the same thing with the address. These variables are usually passed to the invoice using form fields (hidden or otherwise) in the submitting web page. The printing script, however, can disable some of these fields or add others via database lookups and the like. In all types of templates, variable substitution occurs between <% and %>. One can optionally specify an alignment or a width but these are really only useful in text templates.
The following templates exist in HTML format:
These templates can be edited by an HTML editor. However, it is generally recommended that one back up templates first. The reason is that some HTML editors will fully re-parse the HTML and save it back without what they see as invalid tags. Most editors, however, will save the variable substitution tags because similar tags are also used by Microsoft's active server pages. Finally, some editors are known to mangle formatting, so many problems can be avoided by ensuring that one has a backup of the templates, especially if they have already been customized.
The following templates, by default, are available in LaTeX :
LaTeX templates allow one to generate PDF and postscript documents and print directly to a postscript-enabled printer or print software (like CUPS). LaTeX templates can be edited using a standard text editor (like vim or emacs), or using a synchronous LaTeX implementation such as LyX.
LaTeX (pronounced LAY-tech) is an extension on the TeX typesetting system. It largely consists of a set of macros that allow one to focus on the structure of the document while letting the TeX engine do the heavy lifting in terms of determining the optimal formatting for the page. LaTeX is used in a large number of academic journals (including those of the American Mathematics Association). It is available at http://www.tug.org. Like HTML, LaTeX uses plain text documents to store the formatting information and then when the document is rendered, attempts to fit it onto a page. LaTeX supports the concept of stylesheets, allowing one to separate content from format, and this feature is used in many higher-end applications, like journal publication. Unlike HTML, LaTeX is a complete though simple programming language that allows one to redefine internals of the system for formatting purposes. This document is written in LaTeX.
LyX is a synchronous LaTeX editor that runs on Windows, UNIX/Linux, and Mac OS X. It requires an installed LaTeX-2e implementation and can be obtained at http://www.lyx.org. Like the most common LaTeX implementations, it is open source. In LaTeX, the % sign is used to begin a comment. Therefore in order to edit the documents effectively, you must convert the % signs into another character combination, such as @. This can be done with a sed script such as:
sed -e "s|°/o|@|ig" template.tex > template-edit.tex
Then when you are done:
sed -e "|@|%|ig" template-edit.tex > template.tex
One can edit the template-edit.tex without worrying about LyX disregarding lines when it encounters a %.
LaTeX requires different formats of logos depending on whether the document is going to be generated as a PDF or as postscript. Postscript requires an embedded postscript graphic, while PDF requires any type of graphic other than embedded postscript. Usually one uses a PNG's for PDF's, though GIF's could be used as well. The logo for a LaTeX document resides in the users directory. HTML documents can have logos in many different formats. PNG's are generally preferred for printing reasons. The image can be stored anywhere and merely referenced in the HTML. Note: Always test the an invoice with an image on it to ensure that the rest of the page format is not thrown off by it.
The template directory (“templates” in the root SQL-Ledger install directory) contains all the root templates used by SQL-Ledger. These follow a naming convention of COAType-templatename.ext where COAType is the type of dataset that was created when the user was created, templatename is the name of the template, and ext is either txt, html, or tex (for text, html, and LaTeX respectively). Inside this directory are one or more subdirectories where the relevant templates have been copied as default language templates for the user. Many users can use the same user directory (which bears the name of the SQL-Ledger username). Within this directory are more subdirectories for translated templates, one for each language created.
When SQL-Ledger is upgraded, the templates are not replaced. This is designed to prevent the upgrade script from overwriting changes made during the course of customizing the templates. Occasionally, however, the data model changes in a way which can cause the templates to stop printing certain information. When information that was showing up before an upgrade stops showing up, one can either upgrade the templates by copying the source template over the existing one, or one can edit the template to make the change.
(First version from: An Introduction to SQL-Ledger by Chris Travers, 2006)