Bug 34472 - Template Toolkit reference guide needed
Summary: Template Toolkit reference guide needed
Status: ASSIGNED
Alias: None
Product: Koha
Classification: Unclassified
Component: Notices (show other bugs)
Version: Main
Hardware: All All
: P1 - high enhancement with 21 votes (vote)
Assignee: David Nind
QA Contact: Testopia
URL:
Keywords: roadmap_24_05
: 15276 (view as bug list)
Depends on: 14757
Blocks: 15279
  Show dependency treegraph
 
Reported: 2023-08-03 16:30 UTC by Christopher Brannon
Modified: 2024-04-27 09:59 UTC (History)
20 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
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.