diff options
Diffstat (limited to 'src/hydrilla/proxy')
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 %} |