.. _template-guide: 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 `` 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

`` For example: .. code:: console 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 ```` of the ``base`` template * ``header.html`` -- Template to be added as the first content of the ```` tag of the ``base`` template * ``footer.html`` -- Template for adding content as the "footer" of the ```` tag of the ``base`` template 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 page * ``head`` -- Block for adding content to the ````, includes ``head.html`` template * ``header`` -- Block for adding content to the ```` before the ``body`` block, includes the ``header.html`` template * ``body`` -- Block for adding the primary content to template * ``footer`` -- Block for adding content to the ```` after the ``body`` block, includes the ``footer.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 :ref:`custom-metadata` for more info on the custom metadata. Additionally, the :ref:`shared-template-vars` 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 :ref:`custom-metadata` for more info. * ``{{ ui }}`` - an optional ``ui`` dictionary from ``config.yaml``, if any .. _custom-metadata: 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 ``/metadata.yaml`` files can be accessed via the ``{{ metadata }}`` variable. For example, if the metadata file contains: .. code:: yaml 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. The default template supports the standard pywb table view, as well as a conditional new vue-based UI. (See :ref:`new-vue-ui` for more info on the new UI) 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 optional ``ui`` dictionary from ``config.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`` in ``http://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/`` * ``{{ config }}`` - provides the contents of the ``config.yaml`` as a dictionary. * ``{{ ui }}`` - an optional ``ui`` dictionary from ``config.yaml``, if any. The default banner creates all UI dynamically via JS. However, a custom banner could also insert HTML to render the banner directly. By default, the banner checks the ``{{ ui.vue_timeline_banner }}`` and renders the new UI or the standard default UI. The default UI is created via the ``default_banner.js`` script. See :ref:`new-vue-ui` for more details on the new Vue UI. 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 complete ``WbUrl`` object, which contains the ``url``, ``timestamp`` and ``mod`` properties, representing the replay url. * ``{{ is_framed }}`` - true/false if currently in framed mode. * ``{{ wb_prefix }}`` - the collection prefix, e.g. ``http://localhost:8080/pywb/`` .. _custom-top-frame: 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 ``