From 92078b53c81dcea0fdd2b5abd3ac327323326a28 Mon Sep 17 00:00:00 2001 From: Charles Haley Date: Wed, 22 Jan 2025 11:40:51 +0000 Subject: [PATCH] Updates to the manual. NB: I used references like :ref:`ff_func` gui.rst. but don't know if they work. --- manual/gui.rst | 2 +- manual/template_lang.rst | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/manual/gui.rst b/manual/gui.rst index 9a2ed8ee81..f0cd74adc8 100644 --- a/manual/gui.rst +++ b/manual/gui.rst @@ -743,7 +743,7 @@ To choose icons for values in categories, right-click on a value then choose `Ma * ``count``: the number of books with this value. If the value is part of a hierarchy then the count includes the children. * ``avg_rating``: the average rating for books with this value. If the value is part of a hierarchy then the average includes the children. - Book metadata such as title is not available. Template database functions such as book_count() and book_values() will work, but the performance might not be acceptable. The following template functions will work in the GUI but won't work in the content server: ``connected_device_name()``, ``connected_device_uuid()``, ``current_virtual_library_name()``, ``is_marked()``, and ``virtual_libraries()``. + Book metadata such as title is not available. Template database functions such as :ref:`ff_book_count` and :ref:`ff_book_values` will work, but the performance might not be acceptable. The following template functions will work in the GUI but won't work in the content server: :ref:`ff_connected_device_name`, :ref:`ff_connected_device_uuid`, :ref:`ff_current_virtual_library_name`, :ref:`ff_is_marked`, and :ref:`ff_virtual_libraries`. In the GUI, Python templates have full access to the calibre database. In the content server, Python templates have access to new API (see `API documentation for the database interface `_) but not the old API (LibraryDatabase). diff --git a/manual/template_lang.rst b/manual/template_lang.rst index aa4aacfa37..d9a11b9c01 100644 --- a/manual/template_lang.rst +++ b/manual/template_lang.rst @@ -629,6 +629,29 @@ User-defined Python template functions You can add your own Python functions to the template processor. Such functions can be used in any of the three template programming modes. The functions are added by going to :guilabel:`Preferences -> Advanced -> Template functions`. Instructions are shown in that dialog. Note that you can use `Python Templates` for a similar purpose. As calling user-defined functions is faster than calling a Python template, user-defined functions might be more efficient depending on the complexity of what the function or template does. +Special notes for using templates in difference contexts +-------------------------------------------------------- + +In the GUI (`Columns made from other columns` and `Template searches`): + +* GPM templates work as before. +* Python templates have full access to the calibre database. + +In icon rules: + +* icon rule templates have no book data so field-based functions such as :ref:`ff_format_date_field`, :ref:`ff_list_count_field`, and :ref:`ff_check_yes_no` won't work. + +In the content server: + +* Templates have access to the new API but not the old API (LibraryDatabase). +* Because of the above, the following formatter functions are not guaranteed to work in GPM templates (composite columns, icon rules, etc) and should be avoided if you use the content server: + + * :ref:`ff_connected_device_name` + * :ref:`ff_connected_device_uuid` + * :ref:`ff_current_virtual_library_name` + * :ref:`ff_is_marked` + * :ref:`ff_virtual_libraries` + Special notes for save/send templates ---------------------------------------