aboutsummaryrefslogtreecommitdiff
path: root/src/hydrilla/proxy
diff options
context:
space:
mode:
Diffstat (limited to 'src/hydrilla/proxy')
-rw-r--r--src/hydrilla/proxy/self_doc/packages.html.jinja180
-rw-r--r--src/hydrilla/proxy/web_ui/templates/import.html.jinja5
-rw-r--r--src/hydrilla/proxy/web_ui/templates/index.html.jinja8
-rw-r--r--src/hydrilla/proxy/web_ui/templates/items/libraries.html.jinja5
-rw-r--r--src/hydrilla/proxy/web_ui/templates/items/packages.html.jinja5
-rw-r--r--src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja1
6 files changed, 196 insertions, 8 deletions
diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/packages.html.jinja
index a9bedc5..c27c161 100644
--- a/src/hydrilla/proxy/self_doc/packages.html.jinja
+++ b/src/hydrilla/proxy/self_doc/packages.html.jinja
@@ -27,15 +27,189 @@ code in a proprietary work, I am not going to enforce this in court.
{% call section() %}
{% call paragraph() %}
- blah blah
+ Users can modify web pages by creating, installing and enabling
+ <span class="bold">packages</span>.
+ A package associates {{ doc_page_link('URL patterns', 'url_patterns') }}
+ with payloads (i.e. sets of scripts) that can be injected to pages.
+ For instance, if an enabled package associates pattern
+ <code>https://example.com/***</code> with a script that adds a big
+ "Hello world!" text to the page, this package shall cause "Hello world!"
+ to appear on pages under <code>example.com</code>.
{% endcall %}
{% endcall %}
{% call section() %}
- {{ medium_heading('blah blah') }}
+ {{ medium_heading('Packages and libraries') }}
{% call paragraph() %}
- more blah blah...
+ To make mapping custom JavaScript applications and their dependencies to
+ web pages more manageable, Haketilo defines its own concept of "packages"
+ and "libraries".
+ {% endcall %}
+
+ {% call unordered_list() %}
+ {% call list_entry() %}
+ package - Also called <span class="bold">mapping</span>.
+ It associates URL patterns with libraries.
+ {% endcall %}
+ {% call list_entry() %}
+ library - Sometimes also referred to as
+ <span class="bold">resource</span>.
+ Defines a set of scripts that can be injected together into a page.
+ It can also name other libraries as its dependencies.
+ When injecting scripts of a given library into some page, Haketilo will
+ first inject scripts of all libraries depended on.
+ {% endcall %}
+ {% endcall %}
+
+ {% call paragraph() %}
+ It's ultimately a package that provides concrete functionality to the end
+ user and that can be enabled or disabled.
+ For this reason, a casual user does not even need to be aware of the
+ existence of libraries.
+ Haketilo UI advanced interface features need to be enabled on the
+ {{ hkt_link('settings page', 'home.home') }} for installed libraries to be
+ viewable.
+ {% endcall %}
+ {% endcall %}
+
+ {% call section() %}
+ {{ medium_heading('Installing') }}
+
+ {% call paragraph() %}
+ Useful packages prepared by others can be installed from Hydrilla
+ repositories. The repositories can be configured
+ {{ hkt_link('through Haketilo user interface', 'repos.repos') }} and as of
+ Haketilo 3.0-beta1 need to be manually "refreshed" for new packages from
+ them to be shown in Haketilo.
+ Available packages viewable on the
+ {{ hkt_link('packages listing page', 'items.packages') }} are not
+ immediately installed.
+ This only happens after they are explicitly enabled or automatically
+ enabled (if the user configured Haketilo to do this).
+ {% endcall %}
+
+ {% call paragraph() %}
+ For convenience, users can also create simple packages
+ {{ hkt_link('directly in Haketilo UI', 'import.items_import') }}.
+ A simple form can be used to quickly define a standalone script payload
+ for a set of URL patterns. As of Haketilo 3.0 only simple (i.e.
+ single-library) payloads can be created this way.
+ {% endcall %}
+
+ {% call paragraph() %}
+ It is also possible to import packages from files.
+ For this, a directory of serveable mappings and reasources - as produced
+ by Hydrilla builder and used by Hydrilla server - has to be put into a ZIP
+ archive.
+ It can then be uploaded to Haketilo via its
+ {{ hkt_link('import page', 'import.items_import') }}.
+ {% endcall %}
+ {% endcall %}
+
+ {% call section() %}
+ {{ medium_heading('Uninstalling') }}
+
+ {% call paragraph() %}
+ Haketilo tracks dependencies between packages and libraries and
+ automatically determines which of them are no longer needed.
+ These are called <span class="bold">orphans</span> and if present, can be
+ removed from the {{ hkt_link('settings page', 'home.home') }}.
+ A version of package or library that is not being used but is still
+ available from an active repository is not considered an orphan. It
+ automatically becomes one when the repository either stops advertising it
+ as available or gets removed by the user from
+ {{ hkt_link('the repositories list', 'repos.repos') }}.
+ {% endcall %}
+
+ {% call paragraph() %}
+ When advanced UI features are enabled, it is additionally possible to
+ manually uninstall any single package that is not in use at a given
+ moment.
+ {% endcall %}
+ {% endcall %}
+
+ {% call section() %}
+ {{ medium_heading('Package contents') }}
+
+ {% call paragraph() %}
+ Each package has an <span class="bold">identifier</span> (built from a
+ restricted set of characters), a <span class="bold">long name</span>, a
+ <span class="bold">description</span>, a <span class="bold">version</span>
+ and almost always a list of <span class="bold">license files</span> and a
+ set of <span class="bold">URL patterns mapped to libraries</span>.
+ In addition there might also be other pieces of information such as
+ required permissions.
+ {% endcall %}
+ {% endcall %}
+
+ {% call section() %}
+ {{ medium_heading('Enabling/disabling') }}
+
+ {% call paragraph() %}
+ The user can put package in any of 3 possible states.
+ It can be either <span class="bold">enabled</span>,
+ <span class="bold">disabled</span> or
+ <span class="bold">not configured</span>.
+ {% endcall %}
+
+ {% call paragraph() %}
+ An enabled package always has its payloads injected on pages matched by
+ their patterns (unless some more specific pattern takes precedence on the
+ given page as described on the
+ {{ doc_page_link('policy selection page', 'policy_selection') }}).
+ {% endcall %}
+
+ {% call paragraph() %}
+ A disabled package is always ignored.
+ It has to be manually re-enabled for Haketilo to take it into account
+ again.
+ {% endcall %}
+
+ {% call paragraph() %}
+ Finally, a package that is neither explicitly enabled nor disabled can be
+ treated differently depending on user's choice on the
+ {{ hkt_link('settings page', 'home.home') }}.
+ It is possible to have Haketilo
+ {% endcall %}
+
+ {% call unordered_list() %}
+ {% call list_entry() %}
+ automatically inject such packages' payloads on mathing pages,
+ {% endcall %}
+ {% call list_entry() %}
+ prompt the user on matching pages asking whether the package should be
+ enabled or
+ {% endcall %}
+ {% call list_entry() %}
+ completely ignore non-configured packages.
+ {% endcall %}
+ {% endcall %}
+ {% endcall %}
+
+ {% call section() %}
+ {{ medium_heading('Handling multiple versions') }}
+
+ {% call paragraph() %}
+ It is possible to have many versions of the same package or library
+ installed.
+ When this is the case, Haketilo by default uses the newest versions it
+ can.
+ Additionally, if certain package is enabled, its page also allows the user
+ to configure its <span class="bold">pinning</span>.
+ A package can be
+ {% endcall %}
+
+ {% call unordered_list() %}
+ {% call list_entry() %}
+ pinned to use a particular version,
+ {% endcall %}
+ {% call list_entry() %}
+ pinned to use the best version from a particular repository or
+ {% endcall %}
+ {% call list_entry() %}
+ not pinned at all (best version overall is used).
+ {% endcall %}
{% endcall %}
{% endcall %}
{% endblock main %}
diff --git a/src/hydrilla/proxy/web_ui/templates/import.html.jinja b/src/hydrilla/proxy/web_ui/templates/import.html.jinja
index afeb5a2..34f1b66 100644
--- a/src/hydrilla/proxy/web_ui/templates/import.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/import.html.jinja
@@ -72,7 +72,10 @@ code in a proprietary work, I am not going to enforce this in court.
<div class="horizontal-separator"></div>
- <h4>{{ _('web_ui.import.heading_import_ad_hoc') }}</h4>
+ <h4>
+ {{ _('web_ui.import.heading_import_ad_hoc') }}
+ {{ hkt_doc_link('packages') }}
+ </h4>
{% if invalid_ad_hoc_package is defined %}
{{ error_note(_('web_ui.err.invalid_ad_hoc_package')) }}
diff --git a/src/hydrilla/proxy/web_ui/templates/index.html.jinja b/src/hydrilla/proxy/web_ui/templates/index.html.jinja
index 36d9941..93b834a 100644
--- a/src/hydrilla/proxy/web_ui/templates/index.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/index.html.jinja
@@ -67,7 +67,9 @@ code in a proprietary work, I am not going to enforce this in court.
{{ _('web_ui.home.heading.options') }}
</h4>
- {{ label(_('web_ui.home.mapping_usage_mode_label')) }}
+ {% call label(_('web_ui.home.mapping_usage_mode_label')) %}
+ {{ hkt_doc_link('packages') }}
+ {% endcall %}
{% set use_enabled_but_classes = ['green-button'] %}
{% set use_auto_but_classes = ['green-button'] %}
@@ -103,7 +105,9 @@ code in a proprietary work, I am not going to enforce this in court.
<div class="horizontal-separator"></div>
- {{ label(_('web_ui.home.script_blocking_mode_label')) }}
+ {% call label(_('web_ui.home.script_blocking_mode_label')) %}
+ {{ hkt_doc_link('script_blocking') }}
+ {% endcall %}
{% set allow_but_classes = ['red-button'] %}
{% set block_but_classes = ['blue-button'] %}
diff --git a/src/hydrilla/proxy/web_ui/templates/items/libraries.html.jinja b/src/hydrilla/proxy/web_ui/templates/items/libraries.html.jinja
index 0996b8b..d94d51c 100644
--- a/src/hydrilla/proxy/web_ui/templates/items/libraries.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/items/libraries.html.jinja
@@ -36,7 +36,10 @@ code in a proprietary work, I am not going to enforce this in court.
{% endblock %}
{% block main %}
- <h3>{{ _('web_ui.libraries.heading') }}</h3>
+ <h3>
+ {{ _('web_ui.libraries.heading') }}
+ {{ hkt_doc_link('packages') }}
+ </h3>
<ul class="item-list">
{% for info in display_infos %}
diff --git a/src/hydrilla/proxy/web_ui/templates/items/packages.html.jinja b/src/hydrilla/proxy/web_ui/templates/items/packages.html.jinja
index b79d594..43acaf7 100644
--- a/src/hydrilla/proxy/web_ui/templates/items/packages.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/items/packages.html.jinja
@@ -36,7 +36,10 @@ code in a proprietary work, I am not going to enforce this in court.
{% endblock %}
{% block main %}
- <h3>{{ _('web_ui.packages.heading') }}</h3>
+ <h3>
+ {{ _('web_ui.packages.heading') }}
+ {{ hkt_doc_link('packages') }}
+ </h3>
<ul class="item-list">
{% for info in display_infos %}
diff --git a/src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja b/src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja
index 8b070d9..939b2d6 100644
--- a/src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja
+++ b/src/hydrilla/proxy/web_ui/templates/repos/show_single.html.jinja
@@ -162,6 +162,7 @@ code in a proprietary work, I am not going to enforce this in court.
.format(mappings = display_info.mapping_count)
}}
{% endif %}
+ {{ hkt_doc_link('packages') }}
</p>
{% if not display_info.deleted %}