What’s on our mind: Deep diving into Koha notice templates with Template Toolkit

• Search query: GetPreparedLetter (or your notice code like 'ODUE').
• Where to look:
  • For circulation notices: C4/Circulation.pm or circulation.pl.
  • For overdues: misc/cronjobs/overdue_notices.pl.
  • For holds: C4/Reserves.pm.

  

  Step 3: Analyse the tables and substitute

  Once you find the relevant call to GetPreparedLetter, look at the arguments passed to it. It usually looks something like this:

  my $letter = C4::Letters::GetPreparedLetter(
      module      => 'reserves',
      letter_code => 'HOLDPLACED',
      branchcode  => $branch,
      lang        => $patron->lang,
      tables      => {
          'branches'    => $library->unblessed,
          'borrowers'   => $patron->unblessed,
          'biblio'      => $biblionumber,
          'biblioitems' => $biblionumber,
          'items'       => $checkitem,
          'reserves'    => $hold->unblessed,
      },
      substitute    => {
          today => output_pref(dt_from_string) 
      }
  )

  Here is your treasure map:

  1. 1. tables: These are database tables. If you see 'borrowers' => $borrower, it means the system is fetching a row from the borrowers table.
        • Translation: You can usually access any column in that table using [% borrower.column_name %].

   

  1. substitute: These are custom variables or arrays.
     • Translation: If you see 'today', you can use [% today %].

   

  Step 4: The C4::Letter variable mapping

  How does the Perl object $borrower become [% borrower.firstname %]?

  If you look at C4::Letter.pm, specifically the _get_tt_params function, you will see how Koha maps these. It iterates over the keys in the tables hash.

  • It takes the table name (e.g., borrowers) and uses it as a prefix.
  • It takes the column name (e.g., surname) and appends it.
  • Result: [% borrowers.surname %] (Note: notice syntax sometimes aliases this to the singular borrower depending on context, which is why testing is key).

Part 3: Looping through relations

The most powerful part of TT is looping through related data, like a list of overdue books.

If you saw an array reference in the code (like \@items in the example above), you can loop over it.

<h3>You have the following items checked out:</h3>
<ul>
[% FOREACH item IN items %]
    <li>
        <b>[% item.title %]</b>
        (Due: [% item.date_due | $KohaDates %])
        <br/>
        Barcode: [% item.barcode %]
    </li>
[% END %]
</ul>

The “object” advantage

In newer Koha versions, developers are passing Koha::Objects rather than simple hashrefs. This is a game changer.

If the code passes a Koha::Patron object as borrower, you aren’t limited to just the columns in the borrowers table. You can potentially chain relation method calls if the template context allows it.

• Example: [% borrower.category.description %]
• Here, we are jumping from the Patron object to the related Category object to get the description, all without writing a complex SQL join.

Part 4: Why is this so hard? (And a proposal)

You might be thinking, “Why do I have to read Perl code just to write an email?”

It is a fair question. The difficulty lies in Context. A generic “list of variables” is impossible because the CHECKOUT notice has access to items, but the PASSWORD_RESET notice does not. The data is prepared dynamically at the moment the event happens.

The dream: No more code diving

Imagine a system where developers explicitly declare the “Data Contract” for every notice.

• Developer side: When writing the Perl code, they define: “This notice provides a Patron Object and a list of Item Objects.”
• User side: The Notice Editor reads this contract and gives you a sidebar with a tree-view of available variables. You click “Patron > First Name” and it inserts [% borrower.firstname %].

Call to action

This level of transparency requires refactoring how Koha handles data passing in notices. It’s not as simple as a UI update; it requires backend plumbing to standardise how data is exposed to templates.

However, the payoff would be massive: simpler customisation, fewer bugs, and no more reading C4::Letters.pm on a Friday afternoon.

Is this something that would save your library time? Features like this often come to life through community sponsorship. If you want to make notice writing easier for everyone, consider raising this on the mailing list or sponsoring a developer to tackle the “Notice Data Contract” project!