[chaley]

12 July 2025 - (in calibre 8.7.0)

• formats_path_segments(with_author, with_title, with_format, with_ext, sep)
  
  Spoiler:

  Return parts of the path to a book format in the calibre library separated by ``sep``. The parameter ``sep`` should usually be a slash (``'/'``). One use is to be sure that paths generated in Save to disk and Send to device templates are shortened consistently. Another is to be sure the paths on the device match the paths in the calibre library.
  
  See the manual for full documentation.
  

09 July 2025 - (in calibre 8.6.0)

• format_duration(value, template, [largest_unit])
  
  Spoiler:

  Format the value, a number of seconds, into a string showing weeks, days, hours, minutes, and seconds. If the value is a float then it is rounded to the nearest integer. You choose how to format the value using a template consisting of value selectors surrounded by [ and ] characters. The selectors are:
  

  [w]: weeks 
  [d]: days 
  [h]: hours 
  [m]: minutes 
  [s]: seconds

  You can put arbitrary text between selectors.
  
  The optional largest_unit parameter specifies the largest of weeks, days, hours, minutes, and seconds that will be produced by the template. If provided it must be one of the
  value selectors.
  
  The following examples use a duration of 2 days (172,800 seconds) 1 hour (3,600 seconds) and 20 seconds, which totals to 176,420 seconds.

  • format_duration(176420, '[d][h][m][s]') will return the value 2d 1h 0m 20s.
  • format_duration(176420, '[h][m][s]') will return the value 49h 0m 20s.
  • format_duration(176420, 'Your reading time is [d][h][m][s]', 'h') returns the value Your reading time is 49h 0m 20s.
  • format_duration(176420, '[w][d][h][m][s]') returns the value 2d 1h 0m 20s. Note that the zero weeks value is not returned.

  More functionality is documented in calibre.
  
  
  

08 July 2025 - (in calibre 8.6.0)

• In GPM, allow comment lines to start with blanks or tabs before the '#' instead of only allowing the '#' in the first column.

26 June 2025 ((in calibre preview 8.5.100 and subsequent releases)

• Remove the GUI-only restriction from check_yes_no(). The function will now work in device templates.

12 Feb 2025 (in calibre 7.26)

• Book details search URLs for text, enumeration, series, and composite custom columns.
  Spoiler:

  This isn't a template language change but here is a good place to mention it. You can now define a "search template" for a custom column. It is used to generate a search URL for the column, replacing the standard calibre 'search'. You enter the template in the "Search template:" box in the column definition dialog (Preferences / Add your own columns). The documentation is in the tool tip. Worth mentioning here: there are three new metadata variables available to these search templates:

  • item_value: the value of the item clicked in Book details.
  • item_value_quoted: the value of the item URL-encoded with spaces replaced by plus signs.
  • item_value_no_plus: the value of the item URL-encoded with spaces replaced by '%20'.
• New template functions:
  • make_url(path, [query_name, query_value]+)
    Spoiler:

    -- this function is the easiest way to construct a query URL. It uses a path, the web site and page you want to query, and query_name, query_value pairs from which the query is built. In general, the query_value must be URL-encoded. With this function it is always encoded and spaces are always replaced with '+' signs.
    
    At least one query_name, query_value pair must be provided.
    
    Example: constructing a Wikipedia search URL for the author Niccolò Machiavelli:
    

    make_url('https://en.wikipedia.org/w/index.php', 'search', 'Niccolò Machiavelli')

    returns
    

    https://en.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli

    If you are writing a custom column book details URL template then use $item_name or field('item_name') to obtain the value of the field that was clicked on. Example: if Niccolò Machiavelli was clicked then you can construct the URL using:
    

    make_url('https://en.wikipedia.org/w/index.php', 'search', $item_name)

    See also the functions make_url_extended, query_string and encode_for_url.
  • make_url_extended(...) -- this function is similar to make_url but gives you more control over the URL components.
    Spoiler:

    The components of a URL are
    
    scheme:://authority/path?query string.
    
    See Uniform Resource Locater on Wikipedia for more detail.
    
    The function has two variants:
    

    make_url_extended(scheme, authority, path, [query_name, query_value]+)

    and
    

    make_url_extended(scheme, authority, path, query_string)

    This function returns a URL constructed from the scheme, authority, path, and either the query_string or a query string constructed from the query argument pairs. The authority can be empty, which is the case for calibre scheme URLs. You must supply either a query_string or at least one query_name, query_value pair. If you supply query_string and it is empty then the resulting URL will not have a query string section.
    
    Example 1: constructing a Wikipedia search URL for the author Niccolò Machiavelli:
    

    make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', 'Niccolò Machiavelli')

    returns
    

    https://en.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli

    See the query_string() function for an example using make_url_extended() with a query_string.
    
    If you are writing a custom column book details URL template then use $item_name or field('item_name') to obtain the value of the field that was clicked on. Example: if Niccolò Machiavelli was clicked on then you can construct the URL using :
    

    make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', $item_name')

    See also the functions make_url, query_string and encode_for_url.
  • query_string([query_name, query_value, how_to_encode]+)-- returns a URL query string constructed from the (query_name, query_value, how_to_encode) triads.
    Spoiler:

    A query string is a series of items where each item looks like query_name=query_value where query_value is URL-encoded as instructed. The query items are separated by '&' (ampersand) characters.
    
    If how_to_encode is 0 then query_value is encoded and spaces are replaced with '+' (plus) signs. If how_to_encode is 1 then query_value is encoded with spaces replaced by %20. If how_to_encode is 2 then query_value is returned unchanged; no encoding is done and spaces are not replaced. If you want query_value not to be encoded but spaces to be replaced then use the re function, as in re($series, ' ', '%20')
    
    You use this function if you need specific control over how the parts of the query string are constructed. You could then use the resultingquery string in make_url_extended, as in
    

    make_url_extended(
           'https', 'your_host', 'your_path',
           query_string('encoded', 'Hendrik Bäßler', 0, 'unencoded', 'Hendrik Bäßler', 2))

    giving you the the URL that is invalid because of the space after "Hendrik"
    

    https://your_host/your_path?encoded=Hendrik+B%C3%A4%C3%9Fler&unencoded=Hendrik Bäßler

    You must have at least one query_name, query_value, how_to_encode triad, but can have as many as you wish.
    
    The returned value is a URL query string with all the specified items, for example: name1=val1[&nameN=valN]*. Note that the '?' path / query string separator is not included in the returned result.
    
    If you are writing a custom column book details URL template then use $item_name or field('item_name') to obtain the unencoded value of the field that was clicked. You also have item_value_quoted where the value is already encoded with plus signs replacing spaces, and item_value_no_plus where the value is already encoded with %20 replacing spaces.
    
    See also the functions make_url, make_url_extended and encode_for_url.
  • encode_for_url(value, use_plus) -- returns the value encoded for use in a URL as specified by use_plus.
    Spoiler:

    The value is first URL-encoded. Next, if use_plus is 0 then spaces are replaced by '+' (plus) signs. If it is 1 then spaces are replaced by %20.
    
    If you do not want the value to be encoding but to have spaces replaced then use the re function, as in re($series, ' ', '%20')
    
    See also the functions make_url, make_url_extended and query_string.