====== Customization Guide ======
This section is meant to provide a programmer with an understanding of the technologies enough information to get up to speed quickly and minimize the time spent familiarizing themselves with the software. Topics in this section are listed in order of complexity. As it appeals to a narrower audience than previous discussions of this topic, it is listed separately.

=====General Information =====

The main framework scripts (the ar.pl, ap.pl, etc. scripts found in the root of the installation directory) handle such basic features as instantiating the form object, ensuring that the user is logged in, and the like. They then pass the execution off to the user interface script (usually in the bin/mozilla directory).
SQL-Ledger in many ways may look sort of object oriented in its design, but in reality, it is far more data-driven than object oriented. The Form object is used largely as a global symbol table and also as a collection of fundamental routines for things like database access. It also breaks down the query string into sets of variables which are stored in its attribute hash table.
In essence one can and often will store all sorts of data structures in the primary Form object. These can include almost anything. It is not uncommon to see lists of hashes stored as attributes to a Form object.

=====Customizing Templates =====

Templates are used to generate printed checks, invoices, receipts, and more in SQL-Ledger. Often the format of these items does not fit a specific set of requirements and needs to be changed. This document will not include LaTeX or HTML instruction, but will include a general introduction to editing templates. Also, this is not intended to function as a complete reference.
Template instructions are contained in tags <% and %>. The actual parsing is done by the parse_template function in SL/Form.pm.

====Page Breaks in LaTeX ====

The first tag one will see with LaTeX templates is

  <%pagebreak num1 num2 num3%>
  * num1 represents characters per line
  * num2 represents lines on first page
  * num3 represents lines on second page
The pagebreak block is terminated by

   <%end pagebreak%>
Any text within the pagebreak block is ignored by the template.

==== Conditionals ====

   <%if not varname%>
tells the parser to ignore include the next block only if varname was posted by the submitting form (or set via the form hash elsewhere in the scripts). The block ends with
   <%end varname%>
   <%if varname%>
tells the parser to ignore the block if varname was not posted in the submitting form (or set via the form hash elsewhere in the scripts). The block ends with
   <%end varname%>
Lines conditionals are otherwise ignored by the parser.
Conditionals cannot be nested, but IF's can be nested inside loops as of 2.6.4
==== Loops ====

<%foreach varname%>
is used to iterate through a list of vars set by the user interface system (usually one of the files under bin/mozilla (or otherwise). The block is repeated for each varname in a list. Block ends with

  <%end varname%>
==== File Inclusion ====

  * Files may be included with the syntax
   <%include templatename%>
where templatename is the name of the template within the current template directory (usually templates/$username/)
  * Cannot be used with conditionals
  * Filenames cannot use slashes (/) or .. due to directory transversal considerations.
  * Files can force other files to be included, but the same file cannot be included more than once

==== Cross-referencing and multiple passes of LaTeX ====

In LaTeX cross-references require two passes with latex to resolve. This is because the type is set page by page and the program really doesn't know on which page a given reference will fall. This becomes an even larger issue where floats are concerned as they can move between pages for formatting reasons.
In rare cases, cross-references may point at incorrect pages even with two passes (if the inclusion of the cross-reference data moves the object to another page). In this case you will need to use three passes of LaTeX in order to have accurate references.
SQL-Ledger as of the time of this writing (2.6.8) only makes one pass at the LaTeX file. To force it to make more than one pass, open Form.pm with your favorite text editor. Look for the line:

   system("latex -interaction=nonstopmode $self->{ tmpfile} > $ self->{ tmpfile} .err");
Duplicate this line for two passes, or add two copies if you need three passes.

==== Variable Substitution ====

The following format is used for variable substitution:

   <%varname options%>
Options are one or more (whitespace separated) of:
  * align=left/right/center
  * width=chars where chars is the width in characters before wrapping
  * offset=chars where chars is the number of spaces to (depending on alignment).

===== Customizing Forms =====

Data entry forms and other user interface pieces are in the bin directory. In SQL-Ledger 2.4 and below, most files were symlinked to the equivalent file in the bin/mozilla directory. In 2.6 and later, symlinks are not generally used.
Each module is identified with a two letter combination: ar, ap, cp, etc. These combinations are generally explained in the comment headers on each file.
Execution in these files begins with the function designated by the form-faction} variable. This variable is usually derived from configuration parameters in the menu.ini or the name of the button that was clicked on to submit the previous page. Due to localization requirements, the following process is used to determine the appropriate action taken:
The $locale->getsub routine is called. This routine checks the locale package to determine if the value needs to be translated back into an appropriate SL function. If not, the variable is lower-cased, and all spaces are converted into underscores.
In general there is no substitute for reading the code to understand how this can be customized and how one might go about doing this.

===== Customizing Modules =====

The Perl Modules (.pm files) in the SL directory contain the main business logic of the application including all database access. Most of these modules are fairly easy to follow.
Many of these modules have a fair bit of dormant code in them which was written for forthcoming features, such as payroll and bills of materials.
One can add a new module through the normal means and connect it to other existing modules.

==== Database Access ====

The $form object provides two methods for accessing the database. The $form->dbconnect(%myconfig) method commits each individual statement as its own transaction. The $form->dbconnect_noauto(%myconfig) method requires a manual commit. Both these functions are thin wrappers around the standard Perl DBI operations.

=====Examples =====