aboutsummaryrefslogtreecommitdiff
path: root/src/hydrilla/proxy/self_doc
diff options
context:
space:
mode:
Diffstat (limited to 'src/hydrilla/proxy/self_doc')
-rw-r--r--src/hydrilla/proxy/self_doc/packages.html.jinja180
1 files changed, 177 insertions, 3 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 %}