From bbfe6b3314c034dd03962c06cd957540cca8a95b Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 28 Oct 2022 15:37:33 +0200 Subject: [proxy] document packages --- src/hydrilla/proxy/self_doc/packages.html.jinja | 180 ++++++++++++++++++++- .../proxy/web_ui/templates/import.html.jinja | 5 +- .../proxy/web_ui/templates/index.html.jinja | 8 +- .../web_ui/templates/items/libraries.html.jinja | 5 +- .../web_ui/templates/items/packages.html.jinja | 5 +- .../web_ui/templates/repos/show_single.html.jinja | 1 + 6 files changed, 196 insertions(+), 8 deletions(-) (limited to 'src/hydrilla/proxy') 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 + packages. + 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 + https://example.com/*** with a script that adds a big + "Hello world!" text to the page, this package shall cause "Hello world!" + to appear on pages under example.com. {% 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 mapping. + It associates URL patterns with libraries. + {% endcall %} + {% call list_entry() %} + library - Sometimes also referred to as + resource. + 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 orphans 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 identifier (built from a + restricted set of characters), a long name, a + description, a version + and almost always a list of license files and a + set of URL patterns mapped to libraries. + 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 enabled, + disabled or + not configured. + {% 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 pinning. + 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.
-

{{ _('web_ui.import.heading_import_ad_hoc') }}

+

+ {{ _('web_ui.import.heading_import_ad_hoc') }} + {{ hkt_doc_link('packages') }} +

{% 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') }} - {{ 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.
- {{ 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 %} -

{{ _('web_ui.libraries.heading') }}

+

+ {{ _('web_ui.libraries.heading') }} + {{ hkt_doc_link('packages') }} +