Difference between revisions of "Custom Reports Using Eguile"

From GnuCash
Jump to: navigation, search
m
m (What is eguile?)
Line 9: Line 9:
 
For example,  
 
For example,  
 
<pre>
 
<pre>
<source lang="html4strict">
 
 
<h3><?scm:d coyname ?></h3>
 
<h3><?scm:d coyname ?></h3>
 
<h2><?scm:d reportname ?> as at <?scm:d (gnc-print-date opt-date-tp) ?></h2>
 
<h2><?scm:d reportname ?> as at <?scm:d (gnc-print-date opt-date-tp) ?></h2>
</source>
 
 
</pre>
 
</pre>
 
could become
 
could become
 
<pre>
 
<pre>
<source lang="scheme">
 
 
(display "<h3>")(display "Acme Tools Ltd.")(display "</h3>
 
(display "<h3>")(display "Acme Tools Ltd.")(display "</h3>
 
<h2>)(display "Balance Sheet")(display " as at ")
 
<h2>)(display "Balance Sheet")(display " as at ")
 
(display "05/04/2009")(display "<h2">)
 
(display "05/04/2009")(display "<h2">)
</source>
 
 
</pre>
 
</pre>
 
which is then evaluated as guile code to create the text of the report.
 
which is then evaluated as guile code to create the text of the report.

Revision as of 12:05, 2 July 2009

What is eguile?

eguile is a way of processing a template file to create a 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 eguile.scm.

For example,

<h3><?scm:d coyname ?></h3>
<h2><?scm:d reportname ?> as at <?scm:d (gnc-print-date opt-date-tp) ?></h2>

could become

(display "<h3>")(display "Acme Tools Ltd.")(display "</h3>
<h2>)(display "Balance Sheet")(display " as at ")
(display "05/04/2009")(display "<h2">)

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 eguile-gnc.scm and put it into the report folder. On my system -- Ubuntu -- that's /usr/share/gnucash/guile-modules/gnucash/report/eguile-gnc.scm. 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 .gnucash folder, and then add a line to .gnucash/config.user like this:

(load-from-path "/path/to/my/.gnucash/report.scm")  

If .gnucash/config.user 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:

  1. Downloading taxinvoice.scm and taxinvoice.eguile.scm, and putting them into the /home/chris/.gnucash/ folder.
  2. Adding this line to /home/chris/.gnucash/config.user:
(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:

 <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) ?>

the resulting script would look like:

 (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)

and the final result might be this:

 <h1 align="center">Invoice 002345</h1>
   <p>Date: 04/03/2009, description: Widgets
   <p>Date: 05/03/2009, description: Modified widgets

...

...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: taxinvoice.scm
Template file: taxinvoice-eguile.scm
CSS file: none
Sample output: PDF
Author: ChrisDennis
Version: 0.01
Last update: June 2009

Notes:

  • 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 2.3/2.4.

Balance Sheet

Report file: balsheet-eg.scm
Template file: balsheet-eg.eguile.scm
CSS file: balsheet-eg.css
Sample output: PDF
Author: ChrisDennis
Version: 0.01
Last update: June 2009