View source for Custom Reports Using Eguile

== What is eguile? ==

eguile is a way of processing a template file to create a [http://www.gnu.org/software/guile/guile.html guile] script.

More specifically, within GnuCash, guile is used to combine HTML and guile code to create a report, such as an invoice or balance sheet.

The GnuCash version of eguile is eguile-gnc.scm, written in early 2009 by Chris Dennis, and based on Neale Pickett's [http://woozle.org/~neale/src/eguile/ eguile.scm].

For example, 
<pre>
<h3><?scm:d coyname ?></h3>
<h2><?scm:d reportname ?> as at <?scm:d (gnc-print-date opt-date-tp) ?></h2>
</pre>
would become
<pre>
(display "<h3>")(display "Acme Tools Ltd.")(display "</h3>
<h2>)(display "Balance Sheet")(display " as at ")
(display "05/04/2009")(display "<h2">)
</pre>
which is then evaluated as guile code to create the text of the report.

== How to install an eguile report ==

To try out eguile-based reports, you first need to download [http://www.fb-cs.co.uk/files/gnucash/eguile-gnc.scm eguile-gnc.scm] and put it into the report folder.  On my system -- Ubuntu -- that's
<tt>/usr/share/gnucash/guile-modules/gnucash/report/eguile-gnc.scm</tt>.  In general, it should go into the same folder as files such as fancy-invoice.scm.

Note: GnuCash 2.3/2.4 already includes eguile-gnc.scm.

Install the report and its associated files in the usual way (see the "From a user account" section of the
[[Custom Reports]] page).  The easiest way is to put all the files for a report into your <tt>.gnucash</tt> folder, and then add a line to <tt>.gnucash/config.user</tt> like this:
 (load-from-path "/path/to/my/.gnucash/report.scm")  
If <tt>.gnucash/config.user</tt> does not already exist, just create it and add the new line.

For example, on a Linux system, for a user called 'chris', the Tax Invoice report can be installed by:
# Downloading taxinvoice.scm and taxinvoice.eguile.scm, and putting them into the <tt>/home/chris/.gnucash/</tt> folder.
# Adding this line to <tt>/home/chris/.gnucash/config.user</tt>:
 (load-from-path "/home/chris/.gnucash/taxinvoice.scm")

Restart GnuCash, and the report should then show up somewhere in the reports menu, depending on the menu-path option in the report.  The Tax Invoice and Balance Sheet reports (see below) put themselves into the Reports/Business sub-menu.

== How to create an eguile report ==

...

=== eguile syntax ===

Within what is otherwise an HTML source file, Guile/Scheme code is wrapped in  '<?scm ... ?>'
(whitespace is required after '<?scm' and before '?>')

'<?scm ... ?>' pairs can NOT be nested.

The optional :d modifier (i.e. '<?scm:d' ) is just a shortcut for '(display ... )',
so '<?scm:d x ?>' is the same as '<?scm (display x) ?>'

Note that s-expressions can be spread across more than one '<?scm ... ?>', 
for example:
 <?scm (if (> x 3) (begin ?>Bigger<?scm ) (begin ?>Smaller<?scm )) ?>

Each chunk of text outside a '<?scm ... ?>' pair ends up wrapped
in a (display ... ), after having had double quotes etc. escaped.

The processing happens in two passes.  Initially the input file is converted
to a Guile script, and then that script is evaluated to produce the final
result (as a string which is passed back to the report-displaying part of GnuCash).

For example, if the input file contained these lines:
<pre>
 <h1 align="center">Invoice <?scm:d invoiceid ?></h1>
 <?scm (for-each (lambda (entry) ?>
   <p>Date: <?scm:d (entry date) ?>, description: <?scm:d (entry desc) ?>
 <?scm ) entries) ?>
</pre>
the resulting script would look like:
<pre>
 (display "<h1 align=\"center\">Invoice ")(display invoiceid)(display "</h1>")
 (for-each (lambda (entry)
   (display "<p>Date: ")(display (entry date))
   (display ", description: ")(display (entry desc))
 ) entries)
</pre>
and the final result might be this:
<pre>
 <h1 align="center">Invoice 002345</h1>
   <p>Date: 04/03/2009, description: Widgets
   <p>Date: 05/03/2009, description: Modified widgets
</pre>
...

=== ...the rest of this page will be here very soon ===


=== Internationalisation ===
Always use _ rather than N_ in the template file.  N_ can be used for report option names, help text, and default values.

== Available Reports ==

The following eguile-based reports are available.  More will be contributed soon (hopefully).

==== Tax Invoice ====
{|
| Report file: || [http://www.fb-cs.co.uk/files/gnucash/taxinvoice.scm taxinvoice.scm] 
|-
| Template file: || [http://www.fb-cs.co.uk/files/gnucash/taxinvoice.eguile.scm taxinvoice-eguile.scm] 
|-
| CSS file: || none 
|-
| Sample output: || [http://www.fb-cs.co.uk/files/gnucash/taxinvoice.pdf PDF]
|-
| Author: || [[User:ChrisDennis|ChrisDennis]]
|-
| Version: || 0.01 
|-
| Last update: || June 2009 
|}
===== Features =====
* Includes full company and customer details, including a company logo if required.
* Automatically includes only relevant columns.  For example, if none of the items on the invoice have discounts applied, then the discount columns will be omitted.

===== Issues ===== 
* taxinvoice.scm includes code to display individual taxes on a per-entry basis, i.e. on each line of the invoice. This relies on a fix to the Swig encoding that is currently in the pipeline as bug #573645, but it includes a work-around so that it simply misses out the extra columns if that fix hasn't been applied.  This bug has been fixed in [[Announcement 2.3.0|2.3/2.4]].
* Doesn't have a separate CSS file (yet).

==== Balance Sheet ====
{|
| Report file: || [http://www.fb-cs.co.uk/files/gnucash/balsheet-eg.scm balsheet-eg.scm]
|-
| Template file: || [http://www.fb-cs.co.uk/files/gnucash/balsheet-eg.eguile.scm balsheet-eg.eguile.scm]
|-
| CSS file: || [http://www.fb-cs.co.uk/files/gnucash/balsheet-eg.css balsheet-eg.css]
|-
| Sample output: || [http://www.fb-cs.co.uk/files/gnucash/balsheet-eg-1.pdf PDF]
|-
| Author: || [[User:ChrisDennis|ChrisDennis]]
|-
| Version: || 0.01 
|-
| Last update: || June 2009
|}
===== Features =====
* Displays the balance sheet in a 'text book' style with rules under columns etc.
* Uses the 'Assets = Equity + Liabilities' model.  If there is demand for an 'Assets - Liabilities = Equity' version, then that could be done as a separate report, or by adding an option and some extra code to this one.
* One- or two-column layout.
* Negative values can be shown as, for example, '-£100.00' or '(£100.00)'.
* Deliberately has fewer options than the standard balance sheet.  It makes 'intelligent' decisions about what to display.  For example, parent accounts that are marked as placeholders and have a zero balance do not have their balance shown at all.
* Handles commodities/currencies in a basic way -- exchange rates are calculated as at the date of the balance sheet.
* A balancing entry (labelled 'Retained Earnings' by default) is calculated so that the sheet always balances.
* Only display Imbalance and Orphan accounts if non-zero.

===== Issues =====
* Needs people to test it and comment on it.
* To do: option to put the currency symbol at the top of each column, rather than on every value.