View Single Post
Old 02-12-2025, 12:33 PM   #160
chaley
Grand Sorcerer
chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.chaley ought to be getting tired of karma fortunes by now.
 
Posts: 12,509
Karma: 8065348
Join Date: Jan 2010
Location: Notts, England
Device: Kobo Libra 2
New template functions

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:
      Code:
      make_url('https://en.wikipedia.org/w/index.php', 'search', 'Niccolò Machiavelli')
      returns
      Code:
      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:
      Code:
      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:
      Code:
      make_url_extended(scheme, authority, path, [query_name, query_value]+)
      and
      Code:
      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:
      Code:
      make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', 'Niccolò Machiavelli')
      returns
      Code:
      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 :
      Code:
      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
      Code:
      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"
      Code:
      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.

Last edited by chaley; 02-16-2025 at 06:56 AM.
chaley is offline   Reply With Quote