Template language changes

[chaley]

10 May 2023 (in calibre 6.18)

Changed template function

• identifier_in_list()
  

  identifier_in_list(val, id_name [, found_val, not_found_val])

  treat val as a list of identifiers separated by commas. An identifier has the format id_name:value. The id_name parameter is the id_name text to search for, either id_name or id_name:regexp. The first case matches if there is any identifier matching that id_name. The second case matches if id_name matches an identifier and the regexp matches the identifier's value. If found_val and not_found_val are provided then if there is a match then return found_val, otherwise return not_found_val. If found_val and not_found_val are not provided then if there is a match then return the indentfier:value pair, otherwise the empty string ('').

[ownedbycats]

Will need to change existing ones?

[chaley]

Originally Posted by ownedbycats

Will need to change existing ones?

No.

If found_val and not_found_val are provided then if there is a match then return found_val, otherwise return not_found_val.

This is the previous behavior.

You use the new behavior if you want "id:value" when you test for an identifier's existence.

[chaley]

17 Sep 2023 (in calibre 6.27)

New template function

• format_date_field()
  

  format_date_field(field_name, format_string)

  format the value in the field field_name, which must be the lookup name of date field, either standard or custom. See format_date() for the formatting codes. This function is much faster than format_date and should be used when you are formatting the value in a field (column). It can't be used for computed dates or dates in string variables. Examples::
  

     format_date_field('pubdate', 'yyyy.MM.dd')
     format_date_field('#date_read', 'MMM dd, yyyy')

[chaley]

26 Oct 2023 (in calibre beta 6.99)

New template functions for notes:

• get_note()
  

  get_note(field_name, field_value, plain_text)

  Fetch the note for field 'field_name' with value 'field_value'. If 'plain_text' is empty, return the note's HTML. If 'plain_text' is non-empty, return the note's plain text. If the note doesn't exist, return '' in both cases.
  Example: get_note('tags', 'Fiction', '') returns the HTML of the note attached to the tag 'Fiction'.
• has_note()
  

  has_note(field_name, field_value)

  Return '1' if the value 'field_value' in the field 'field_name' has an attached note, otherwise return ''.
  Example: has_note('tags', 'Fiction') returns '1' if the tag 'fiction' has an attached note, otherwise return ''.

[chaley]

13 Nov 2023: (in calibre 7.0)

New template function for links

• get_link(field_name, field_value) -- fetch the link for field field_name with value field_value. If there is no attached link, return the empty string.
  
  Examples:
  The following returns the link attached to the tag Fiction:
  

  get_link('tags', 'Fiction')

  This template makes a list of the links for all the tags associated with a book in the form value:link, ...:
  

  program:
   ans = '';
   for t in $tags:
       l = get_link('tags', t);
       if l then
           ans = list_join(', ', ans, ',', t & ':' & get_link('tags', t), ',')
       fi
   rof;
   ans

[ownedbycats]

Thank you!

[dunhill]

Originally Posted by chaley

13 Nov 2023: (in calibre source)

New template function for links

• get_link(field_name, field_value) -- fetch the link for field field_name with value field_value. If there is no attached link, return the empty string.
  
  Examples:
  The following returns the link attached to the tag Fiction:
  

  get_link('tags', 'Fiction')

  This template makes a list of the links for all the tags associated with a book in the form value:link, ...:
  

  program:
   ans = '';
   for t in $tags:
       l = get_link('tags', t);
       if l then
           ans = list_join(', ', ans, ',', t & ':' & get_link('tags', t), ',')
       fi
   rof;
   ans

Thank you for all your templates and your work with Calibre

[chaley]

3 March 2024: (in calibre 7.7)

• Change to get_notes() template function
  
  I changed the get_notes() function to return HTML with all image URLs fully expanded to use src="data". This lets the result be used in contexts other than the current calibre library, for example book jackets and book details from a different library. They also now work in tooltips, showing the images, but that is less important because a composite column containing notes probably shouldn't be showing on the book list

[BetterRed]

Originally Posted by chaley

…because a composite column containing notes probably shouldn't be showing on the book list

If the composite column is represented in the Book list by an icon without text will the template result (i.e. the image) show as a tooltip… assuming one hasn't turned book list tooltips off?

BR

[chaley]

Originally Posted by BetterRed

If the composite column is represented in the Book list by an icon without text will the template result (i.e. the image) show as a tooltip… assuming one hasn't turned book list tooltips off?

BR

The tooltip will display the contents of the column that has the icon. Whether that is a note depends on the composite's template.

Example: a composite with the template

program: get_note('authors', $authors, '')

and this icon rule


produces this


NB: get_note() is rather slow, which is why I said you probably shouldn't show the column in the booklist. Showing it icon-only is still showing it, as the template will be evaluated.

[BetterRed]

Originally Posted by chaley

. . .

NB: get_note() is rather slow, which is why I said you probably shouldn't show the column in the booklist. Showing it icon-only is still showing it, as the template will be evaluated.

Is get_note() inherently rather slow, or only when it contains uuencoded images?

BR

[chaley]

Originally Posted by BetterRed

Is get_note() inherently rather slow, or only when it contains uuencoded images?

BR

get_note() and has_note() must query the notes database to find if a note is associated with the field (column) and field value. How fast this is depends on how much caching sqlite does with the database, and to a minor extent how many notes exist.

If there are images in a note then they also must be fetched from the notes database and converted to base64. This of course adds to the running time.

If you sort or search on the note composite then the above will happen for every book in the library. I have no idea whether some plugins will evaluate the column for all books.

I haven't noticed any particular problem with get_notes() speed on my test library, but then I don't do anything that would require evaluating that column for every book.

[chaley]

31 July 2024 (in calibre source)

I added a button to the template evaluation results list to open the Edit metadata (single) dialog on a given book. You can view or modify the book's metadata. Changes will be shown when you close the edit metadata dialog to return to the template tester.

[chaley]

15 Sept 2024 (in calibre source)

The performance of the template functions get_note(), has_note(), and get_link() have been improved. The improvement is especially visible when using these functions in composite columns and template searches. The amount of improvement depends on the number of items in a column. For example, when using a library with more than 10,000 authors, performance of a template search looking for authors with links improved by 20 times.

The improvement is less visible with column icon rules because these are computed when visible on the screen rather than when used in some other operation.