diff options
Diffstat (limited to 'src/hydrilla/proxy/self_doc/packages.html.jinja')
| -rw-r--r-- | src/hydrilla/proxy/self_doc/packages.html.jinja | 218 |
1 files changed, 0 insertions, 218 deletions
diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/packages.html.jinja deleted file mode 100644 index 23e6f45..0000000 --- a/src/hydrilla/proxy/self_doc/packages.html.jinja +++ /dev/null @@ -1,218 +0,0 @@ -{# -SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0 - -Documentation page describing the concept of packages in Haketilo. - -This file is part of Hydrilla&Haketilo. - -Copyright (C) 2022 Wojtek Kosior - -Dual licensed under -* GNU General Public License v3.0 or later and -* Creative Commons Attribution Share Alike 4.0 International. - -You can choose to use either of these licenses or both. - - -I, Wojtek Kosior, thereby promise not to sue for violation of this -file's licenses. Although I request that you do not make use of this -code in a proprietary work, I am not going to enforce this in court. -#} -{% extends "doc_base.html.jinja" %} - -{% block title %} Packages {% endblock %} - -{% block main %} - {{ big_heading('Packages in Haketilo') }} - - {% call section() %} - {% call paragraph() %} - 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('Packages and libraries') }} - - {% call paragraph() %} - 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') }} as - described on - {{ doc_page_link('the relevant documentation page', 'repositories') }}. - As of Haketilo 3.0-beta1 they 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 - {{ doc_page_link('repository', 'repositories') }} or - {% endcall %} - {% call list_entry() %} - not pinned at all (best version overall is used). - {% endcall %} - {% endcall %} - {% endcall %} -{% endblock main %} |