mirror of
https://github.com/webrecorder/pywb.git
synced 2025-03-15 00:03:28 +01:00
manual
- split out the ui customization documentation into its own file ui-customization.rst - added initial documentation covering the new template setup to the ui-customization.rst
This commit is contained in:
John Berlin
parent
d6ab31d529
commit
379f7de1ba
@ -16,6 +16,7 @@ A subset of features provides the basic functionality of a "Wayback Machine".
|
||||
|
||||
manual/usage
|
||||
manual/configuring
|
||||
manual/ui-customization
|
||||
manual/architecture
|
||||
manual/apis
|
||||
code/pywb
|
||||
|
||||
@ -105,95 +105,6 @@ When resolving a ``example.warc.gz``, pywb will then check (in order):
|
||||
* Then, ``http://remote-backup.example.com/collections/<coll name>/example.warc.gz`` (if first lookup unsuccessful)
|
||||
|
||||
|
||||
UI Customizations
|
||||
-----------------
|
||||
|
||||
pywb supports UI customizations, either for an entire archive,
|
||||
or per-collection.
|
||||
|
||||
Static Files
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The replay server will automatically support static files placed under the following directories:
|
||||
|
||||
* Files under the root ``static`` directory can be accessed via ``http://my-archive.example.com/static/<filename>``
|
||||
|
||||
* Files under the per-collection ``./collections/<coll name>/static`` directory can be accessed via ``http://my-archive.example.com/static/_/<coll name>/<filename>``
|
||||
|
||||
Templates
|
||||
^^^^^^^^^
|
||||
|
||||
pywb users Jinja2 templates to render HTML to render the HTML for all aspects of the application.
|
||||
A version placed in the ``templates`` directory, either in the root or per collection, will override that template.
|
||||
|
||||
To copy the default pywb template to the template directory run:
|
||||
|
||||
``wb-manager template --add search_html``
|
||||
|
||||
The following templates are available:
|
||||
|
||||
* ``home.html`` -- Home Page Template, used for ``http://my-archive.example.com/``
|
||||
|
||||
* ``search.html`` -- Collection Template, used for each collection page ``http://my-archive.example.com/<coll name>/``
|
||||
|
||||
* ``query.html`` -- Capture Query Page for a given url, used for ``http://my-archive.example.com/<coll name/*/<url>``
|
||||
|
||||
Error Pages:
|
||||
|
||||
* ``not_found.html`` -- Page to show when a url is not found in the archive
|
||||
|
||||
* ``error.html`` -- Generic Error Page for any error (except not found)
|
||||
|
||||
Replay and Banner templates:
|
||||
|
||||
* ``frame_insert.html`` -- Top-frame for framed replay mode (not used with frameless mode)
|
||||
|
||||
* ``head_insert.html`` -- Rewriting code injected into ``<head>`` of each replayed page.
|
||||
This template includes the banner template and itself should generally not need to be modified.
|
||||
|
||||
* ``banner.html`` -- The banner used for frameless replay. Can be set to blank to disable the banner.
|
||||
|
||||
|
||||
Custom Outer Replay Frame
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<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 to the outer frame html:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Special and Custom Collections
|
||||
------------------------------
|
||||
|
||||
115
docs/manual/ui-customization.rst
Normal file
115
docs/manual/ui-customization.rst
Normal file
@ -0,0 +1,115 @@
|
||||
.. _configuring-pywb-ui:
|
||||
|
||||
UI Customizations
|
||||
-----------------
|
||||
|
||||
pywb supports UI customizations, either for an entire archive,
|
||||
or per-collection.
|
||||
|
||||
Static Files
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The replay server will automatically support static files placed under the following directories:
|
||||
|
||||
* Files under the root ``static`` directory can be accessed via ``http://my-archive.example.com/static/<filename>``
|
||||
|
||||
* Files under the per-collection ``./collections/<coll name>/static`` directory can be accessed via ``http://my-archive.example.com/static/_/<coll name>/<filename>``
|
||||
|
||||
Templates
|
||||
^^^^^^^^^
|
||||
|
||||
pywb users Jinja2 templates to render HTML to render the HTML for all aspects of the application.
|
||||
|
||||
A version placed in the ``templates`` directory, either in the root or per collection, will override that template.
|
||||
|
||||
To copy the default pywb template to the template directory run:
|
||||
|
||||
``wb-manager template --add search_html``
|
||||
|
||||
The following templates are available:
|
||||
|
||||
* ``home.html`` -- Home Page Template, used for ``http://my-archive.example.com/``
|
||||
|
||||
* ``search.html`` -- Collection Template, used for each collection page ``http://my-archive.example.com/<coll name>/``
|
||||
|
||||
* ``query.html`` -- Capture Query Page for a given url, used for ``http://my-archive.example.com/<coll name/*/<url>``
|
||||
|
||||
Error Pages:
|
||||
|
||||
* ``not_found.html`` -- Page to show when a url is not found in the archive
|
||||
|
||||
* ``error.html`` -- Generic Error Page for any error (except not found)
|
||||
|
||||
Replay and Banner templates:
|
||||
|
||||
* ``frame_insert.html`` -- Top-frame for framed replay mode (not used with frameless mode)
|
||||
|
||||
* ``head_insert.html`` -- Rewriting code injected into ``<head>`` of each replayed page.
|
||||
This template includes the banner template and itself should generally not need to be modified.
|
||||
|
||||
* ``banner.html`` -- The banner used for frameless replay. Can be set to blank to disable the banner.
|
||||
|
||||
|
||||
For those looking to customize the default template(s) when deploying pywb, the following templates located in the
|
||||
pywb/templates directory.
|
||||
|
||||
* ``base.html`` -- The base template used for non-replay related pages.
|
||||
|
||||
* ``head.html`` -- Template containing content to be added to the ``<head>`` of the ``base`` template
|
||||
|
||||
* ``header.html`` -- Template to be added as the first content of the ``<body>`` tag of the ``base`` template
|
||||
|
||||
* ``footer.html`` -- Template for adding content as the "footer" of the ``<body>`` 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 ``<head>``, includes ``head.html`` template
|
||||
|
||||
* ``header`` -- Block for adding content to the ``<body>`` 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 ``<body>`` after the ``body`` block, includes the ``footer.html`` template
|
||||
|
||||
Custom Outer Replay Frame
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<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 to the outer frame html:
|
||||
|
||||
.. code-block:: javascript
|
||||
|
||||
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.
|
||||
Loading…
x
Reference in New Issue
Block a user