Bug 34472

Summary: Template Toolkit reference guide needed
Product: Koha Reporter: Christopher Brannon <cbrannon>
Component: NoticesAssignee: David Nind <david>
Status: ASSIGNED --- QA Contact: Testopia <testopia>
Severity: enhancement    
Priority: P1 - high CC: andrewfh, barbara.johnson, bugzilla, caroline.cyr-la-rose, david, dcook, e.betemps, emily.lamancusa, horganl, jrobb, kebliss, kkrueger, kyle, lisette.scheer, lucas, martin.renvoize, mbarrette, michaela.sieber, rcoert, sally.healey, thibault.keromnes, wdeschamps
Version: MainKeywords: roadmap_24_05
Hardware: All   
OS: All   
See Also: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=15278
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=15276
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=21858
Change sponsored?: --- Patch complexity: ---
Documentation contact: Documentation submission:
Text to go in the release notes:
Version(s) released in:
Bug Depends on: 14757    
Bug Blocks: 15279    

Description Christopher Brannon 2023-08-03 16:30:38 UTC
There are no resources that I've been able to find that clearly layout what we can use from Template Toolkit in our notices and slips.

We have

https://wiki.koha-community.org/wiki/Customising_Notices_and_Slips#Notice_Markup

and

https://wiki.koha-community.org/wiki/Notices_with_Template_Toolkit

but neither clearly layout what we can use, and in which slips.  These are more generalized guidelines, but if I am referencing some specific elements, it's a guessing game.  And I keep coming across things to use I never heard of before, not mentioned anywhere.  It would really be helpful if a wiki guide were put together to make this much clearer than it is right now.
Comment 1 Sally 2023-08-04 08:18:34 UTC
+1 strong agree.

Template Toolkit is so powerful and the work that's been done to introduce it is amazing.  

However, as a librarian, reading the standard Template Toolkit docs only takes you so far when you're not quite sure what is accessible in Koha and how to reach it - and you waste a lot of time experimenting.

It's also causing developers to reinvent the wheel, as seen in Bug 28556 - see Martin's comments at 8/9/10:  https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28556#c9
Comment 2 Katrin Fischer 2023-08-28 19:54:44 UTC
*** Bug 15276 has been marked as a duplicate of this bug. ***
Comment 3 Rebecca Coert 2023-09-21 14:41:10 UTC
+1 We need this!
Comment 4 Laura Horgan 2023-09-21 14:43:03 UTC
+1 documentation needed
Comment 5 Jason Robb 2023-09-21 14:43:51 UTC
+1 yes, please!
Comment 6 Kristi 2023-09-22 14:14:32 UTC
Agreed that TT documentation tailored for Koha users is needed. A glossary of fields from Koha that can be included in notices and how data from those fields can be formatted would be helpful as part of the documentation.
Comment 7 David Nind 2023-12-11 23:05:04 UTC
Andrew Fuerste-Henry has created some documentation, "I learned some things about Template Toolkit and how to tell what's available in given notice and how to refer to it. I wrote it down before I forgot it all."

https://docs.google.com/document/d/e/2PACX-1vTM4X93uwDKk2KeGF3_rJQNyug2M4JUo1HvHgr8UocZk5Q4jNZNEKrScSDpQWBJkiySKzdLN6F0wzm-/pub

Also, just realising I assigned this to myself some time ago! 8-)
Comment 8 Emily Lamancusa 2024-03-08 20:03:34 UTC
Some thoughts / useful information I've come across while digging into the code to figure out what bug 15278 will entail:
(This is mostly answering the questions of "what information do we need to provide to users?" and "where can we find this information in the code if it isn't well documented?")

- To get a list of what TT objects are available to notices in general, possible places to look are two subs in C4::Letters: _get_tt_params and _parseletter_sth.
    ~ Near the beginning of _get_tt_params, a $config variable is defined that maps 
      database table names to Template Toolkit variable names.
    ~ _parseletter_sth actually prepares (and caches?) database queries for notices
    ~ These two subs aren't 100% in sync with each other, though (I haven't dug quite
      deep enough to be sure if that's a bug in and of itself)

- To know which specific tables a specific notice has access to, I believe one way to do that would be to find the GetPreparedLetter call for that notice. A list of tables is passed as a parameter. (git grep is your friend here)

- Due, Predue, and Overdue notices might be weird - they have some custom handling in advance_notices.pl and overdue_notices.pl. There are also a few other notices that have weird custom things that aren't handled yet in Template Toolkit syntax. (See https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=15278#c11)

- Some Koha-specific TT things that aren't tied to a particular table that we should include:
    ~ accessing today's date
    ~ formatting a date
    ~ I feel like I've seen some environment context / syspref configuration things 
      getting used in notices before? 

- We should include an explanation of how a TT variable can be singular or plural, and when and how to use each. (Is there any situation where we'd use the plural, other than a FOREACH loop or a count?)

- We definitely need to make sure the '----' syntax for digest notices is documented, and probably include an explanation of when to use '----' and when to use a FOREACH.

- I believe any database field in a given table is accessible as a variable in notices that have access to that table? If I'm correct in that, it would be really useful for the Template Toolkit documentation to link to the schema page for the relevant tables.

- Ideally, it would be a nice idea to include some very basic, layman-friendly TT info as a starting point for users who may not have a programming background or experience reading technical documentation.
Comment 9 Caroline Cyr La Rose 2024-05-07 13:51:57 UTC
If I understand correctly, this 
https://wiki.koha-community.org/wiki/Notices_with_Template_Toolkit#Variables_available_in_each_notice is too vague? It's the one I use most often to know what is available in which notice.


I also made a list of variables to copy-paste for my clients (in French, but the variables are in English, so it should be pretty easy to understand) https://inlibro.com/knowledge-base/definition-des-champs-pour-les-lettres-et-avis/ It might be obvious to English speakers that borrower.firstname is the borrower's first name, but if you don't speak English, it's a bit harder to figure out :)
Comment 10 Christopher Brannon 2024-05-07 16:17:53 UTC
(In reply to Caroline Cyr La Rose from comment #9)
> If I understand correctly, this 
> https://wiki.koha-community.org/wiki/
> Notices_with_Template_Toolkit#Variables_available_in_each_notice is too
> vague? It's the one I use most often to know what is available in which
> notice.
> 

This is helpful.  I'm not seeing newer templates (like for reports).  Do you have that information?

Also, this lists availability by notice code, which seems a bit arbitrary.  Would this be a more efficient list by listing what is available to each module, rather than specific notice?
Comment 11 Katrin Fischer 2024-05-07 17:08:51 UTC
(In reply to Christopher Brannon from comment #10)
> (In reply to Caroline Cyr La Rose from comment #9)
> > If I understand correctly, this 
> > https://wiki.koha-community.org/wiki/
> > Notices_with_Template_Toolkit#Variables_available_in_each_notice is too
> > vague? It's the one I use most often to know what is available in which
> > notice.
> > 
> 
> This is helpful.  I'm not seeing newer templates (like for reports).  Do you
> have that information?
> 
> Also, this lists availability by notice code, which seems a bit arbitrary. 
> Would this be a more efficient list by listing what is available to each
> module, rather than specific notice?

I believe it is in part actually different between notices, not tied to modules.
Comment 12 Christopher Brannon 2024-05-07 17:34:56 UTC
Hmmm....that makes no sense to me.  So if I were to create a new Overdue Notice with a completely different code, I wouldn't be able to use the template toolkit objects associate with it because I didn't use a specific code?

This seems ripe with potential issues down the road.  It seems like the TT objects should be associate with the module, not a code.  Otherwise, that would be a nightmare for custom notices down the road.

Does that make any sense, or am I just out of my mind?
Comment 13 Katrin Fischer 2024-05-07 18:12:29 UTC
(In reply to Christopher Brannon from comment #12)
> Hmmm....that makes no sense to me.  So if I were to create a new Overdue
> Notice with a completely different code, I wouldn't be able to use the
> template toolkit objects associate with it because I didn't use a specific
> code?

It works for overdue, but it's not the code or the module, but because you configure it in the notice triggers. The system knows it's an overdue and pulls the data accordingly.

> This seems ripe with potential issues down the road.  It seems like the TT
> objects should be associate with the module, not a code.  Otherwise, that
> would be a nightmare for custom notices down the road.
> Does that make any sense, or am I just out of my mind?

I'd say they are more tied to the function that generates the notice/slip. Some features allow you to configure the code to use like overdues, some are tied to a specific code and some to a specific module. I expect us to not be overall consistent right now as the code doesn't use the module to determine the objects available in general.

For an examples:
Bug 29100 - Add checkouts data loop to predue/due notices script (advance_notices.pl)
Changed the advance_notices script to make the checkouts object available to TT, but only for the notices sent by this script, not for all in circulation module.