Grand Sorcerer
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.
|