diff options
Diffstat (limited to 'src/hydrilla/proxy/self_doc/packages.html.jinja')
| -rw-r--r-- | src/hydrilla/proxy/self_doc/packages.html.jinja | 180 |
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 %} |