Template Guide¶
Introduction¶
This guide provides a reference of all of the templates available in pywb and how they could be modified.
These templates are found in the pywb/templates
directory and can be overridden as needed, one HTML page at a time.
Template variables are listed as {{ variable }}
to indicate the syntax used for rendering the value of the variable in Jinja2.
Copying a Template For Modification¶
To modify a template, it is often useful to start with the default template. To do so, simply copy a default template
to a local templates
directory.
For convenience, you can also run: wb-manager template --add <template-name>
to add the template automatically.
For a list of available templates that can be overridden in this way, run wb-manager template --list
.
Per-Collection Templates¶
Certain templates can be customized per-collection, instead of for all of pywb.
To override a template for a specific collection only, run wb-manager template --add <template-name> <coll-name>
For example:
wb-manager init my-coll
wb-manager template --add search_html my-coll
This will create the file collections/my-coll/templates/search.html
, a copy of the default search.html, but configured to be used only
for the collection my-coll
.
Base Templates (and supporting templates)¶
File: base.html
This template includes the HTML added to all other pages, replay and non-replay. Shared JS and CSS includes can be added here. For theming all pywb UI, it may be useful to modify this template.
To customize the default pywb UI across multiple pages, the following additional templates can also be overriden:
head.html
– Template containing content to be added to the<head>
of thebase
templateheader.html
– Template to be added as the first content of the<body>
tag of thebase
templatefooter.html
– Template for adding content as the “footer” of the<body>
tag of thebase
template
Note: The default pywb head.html
and footer.html
are currently blank. They can be populated to customize the rendering, add analytics, etc… as needed.
The base.html
template also provides five blocks that can be supplied by templates that extend it.
title
– Block for supplying the title for the pagehead
– Block for adding content to the<head>
, includeshead.html
templateheader
– Block for adding content to the<body>
before thebody
block, includes theheader.html
templatebody
– Block for adding the primary content to templatefooter
– Block for adding content to the<body>
after thebody
block, includes thefooter.html
template
Home, Collection and Search Templates¶
Home Page Template¶
File: index.html
This template renders the home page for pywb, and by default renders a list of available collections.
Template variables:
{{ routes }}
- a list of available collection routes.{{ all_metadata }}
- a dictionary of all metadata for all collections, keyed by collection id. See Custom Metadata for more info on the custom metadata.
Additionally, the Shared Template Variables are also available to the home page template, as well as all other templates.
Collection Page Template¶
File: search.html
The ‘collection page’ template is the page rendered when no URL is specified, e.g. http://localhost:8080/my-collection/
.
The default template renders a search page that can be used to start searching for URLs.
Template variables:
{{ coll }}
- the collection name identifier.{{ metadata }}
- an optional dictionary of metadata. See Custom Metadata for more info.{{ ui }}
- an optionalui
dictionary fromconfig.yaml
, if any
Custom Metadata¶
If custom collection metadata is provided, this page will automatically show this metadata as well.
It is possible to also add custom metadata per-collection that will be available to the collection.
For dynamic collections, any fields placed in <coll_name>/metadata.yaml
files can be accessed
via the {{ metadata }}
variable.
For example, if the metadata file contains:
somedata: value
Accessing {{ metadata.somedata }}
will resolve to value
.
The metadata can also be added via commandline: wb-manager metadata myCollection --set somedata=value
.
URL Query/Calendar Page Template¶
File: query.html
This template is rendered for any URL search response pages, either a single URL or more complex queries.
For example, the page http://localhost:8080/my-collection/*/https://example.com/
will be rendered using this template, with functionality provided by a Vue application.
Template variables:
{{ url }}
- the URL being queried, e.g.https://example.com/
{{ prefix }}
- the collection prefix that will be used for replay, e.g.http://localhost:8080/my-collection/
{{ ui }}
- an optionalui
dictionary fromconfig.yaml
, if any{{ static_prefix }}
- the prefix from which static files will be accessed from, e.g.http://localhost:8080/static/
.
Replay and Banner Templates¶
The following templates are used to configure the replay view itself.
Banner Template¶
File: banner.html
This template is used to render the banner and is used both in framed replay and frameless replay.
In framed replay, the template is only rendered in the top/outer frame, while in frameless replay, it is added to every page.
Template variables:
{{ url }}
- the URL being replayed.{{ timestamp }}
- the timestamp being replayed, e.g.20211226
inhttp://localhost:8080/pywb/20211226/mp_/https://example.com/
{{ is_framed }}
- true/false if currently in framed mode.{{ wb_prefix }}
- the collection prefix, e.g.http://localhost:8080/pywb/
{{ host_prefix }}
- the pywb server origin, e.g.http://localhost:8080
{{ config }}
- provides the contents of theconfig.yaml
as a dictionary.{{ ui }}
- an optionalui
dictionary fromconfig.yaml
, if any.
The default banner creates the UI dynamically in JavaScript using Vue.
Head Insert Template¶
File: head_insert.html
This template represents the HTML injected into every replay page to add support for client-side rewriting via wombat.js
.
This template is part of the core pywb replay, and modifying this template is not recommended.
For customizing the banner, modify the banner.html
template instead.
Top Frame Template¶
File: frame_insert.html
This template represents the top-level frame that is inserted to render the replay in framed mode.
By design, this template does not extend from the base template.
This template is responsible for creating the iframe that will render the content.
This template only renders the banner and is designed not to set the encoding to allow the browser to ‘detect’ the encoding for the containing iframe. For this reason, the template should only contain ASCII text, and %-encode any non-ASCII characters.
Template variables:
{{ url }}
- the URL being replayed.{{ wb_url }}
- A completeWbUrl
object, which contains theurl
,timestamp
andmod
properties, representing the replay url.{{ wb_prefix }}
- the collection prefix, e.g.http://localhost:8080/pywb/
{{ is_proxy }}
- set to true if page is being loaded via an HTTP/S proxy (checks if WSGI env haswsgiprox.proxy_host
set)
Customizing the Top Frame Template¶
The top-frame used for framed replay can be replaced or augmented
by modifying the frame_insert.html
.
To start with modifying the default outer page, you can add it to the current
templates directory by running wb-manager template --add frame_insert_html
To initialize the replay, the outer page should include wb_frame.js
,
create an <iframe>
element and pass the id (or element itself) to the ContentFrame
constructor:
<script src='{{ host_prefix }}/{{ static_path }}/wb_frame.js'> </script>
<script>
var cframe = new ContentFrame({"url": "{{ url }}" + window.location.hash,
"prefix": "{{ wb_prefix }}",
"request_ts": "{{ wb_url.timestamp }}",
"iframe": "#replay_iframe"});
</script>
The outer frame can receive notifications of changes to the replay via postMessage
For example, to detect when the content frame changed and log the new url and timestamp, use the following script in the outer frame html:
window.addEventListener("message", function(event) {
if (event.data.wb_type == "load" || event.data.wb_type == "replace-url") {
console.log("New Url: " + event.data.url);
console.log("New Timestamp: " + event.data.ts);
}
});
The load
message is sent when a new page is first loaded, while replace-url
is used
for url changes caused by content frame History navigation.
Error Templates¶
The following templates are used to render errors.
Page Not Found Template¶
File: not_found.html
- template for 404 error pages.
This template is used to render any 404/page not found errors that can occur when loading a URL that is not in the web archive.
Template variables:
{{ url }}
- the URL of the page{{ wbrequest }}
- the fullWbRequest
object which can be used to get additional info about the request.
(The default template checks {{ wbrequest and wbrequest.env.pywb_proxy_magic }}
to determine if the request is via an HTTP/S Proxy Mode connection or a regular request).
Generic Error Template¶
File: error.html
- generic error template.
This template is used to render all other errors that are not ‘page not found’.
Template variables:
{{ err_msg }}
- a shorter error message indicating what went wrong.{{ err_details }}
- additional details about the error.