[chaley]

12 Feb 2025 - (in calibre 7.26)

• Book details search URLs for text, enumeration, series, and composite custom columns. 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]+) -- 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. 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. 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. 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.