Haketilo

# User manual

{{toc}}

## Installation

Instructions for different browsers have been put on their respective pages:

* [[Installation instructions (Mozilla)]]

* [[Installation instructions (Chromium)]]

Users who want to install Haketilo from source can also visit [[Building the extension]] page.

## Understanding the concepts

### Script blocking and injection

Haketilo combines features of a user script manager and a content blocker. Out of the box, it can be used to block site's JavaScript, similarly to how NoScript (for example) does it. Once you import custom scripts into Haketilo (either from a Hydrilla repository server or by typing code in a form in the settings page), it can also inject them into pages.

Script blocking and injection is configured using [[URL patterns]]. Patterns have different specificity. More specific patterns will override the settings of the less specific ones. In short, for every visited page, Haketilo performs the following steps:

1. Check if the page is privileged (e.g. it is its own settings page or a directory listing of local filesystem). If it is, don't attempt to block nor inject anything on this page and don't perform the remaining steps.

2. Try to find a script blocking/allowing/injection rule with a pattern matching page's URL. If found, apply the rule and don't perform the next step.

   * If multiple rules match, pick the one with the most specific pattern.

3. Check whether the default policy is to block scripts or allow them. Act accordingly.

In the end, Haketilo's action shall be one of the following:

* block page's own scripts

* allow page's own scripts to execute (i.e. don't do anything)

* inject the supplied user script **and** block page's own scripts

We can see that Haketilo's concepts are different from those of most user script managers. GreaseMonkey, for instance, executes user scripts alongside page's original scripts. Haketilo effectively **replaces** page's scripts with the user-supplied ones.

### Mappings and Resources

To make handling JavaScript libraries more manageable, we introduced our own concept of packages. Currently, Haketilo understands 2 different types of items (i.e. packages):

* Resource - It defines a set of scripts that can be injected together into a page. It can also name other resources as its dependencies. When injecting scripts of a given resource into some page, Haketilo will first inject scripts of all resources depended on.

* Mapping - It associates URL patterns with resources in a 1:1 fashion. If pattern `https://example.com/***` is associated with resource `my-sample-res` it means the scripts from `my-sample-res` should be injected into all HTTPS pages under the example.com domain.

For simple cases, this may be overly complex. Because of that, Haketilo's settings page contains a simple form that can be used to quickly define a script payload for a set of URL patterns.

Mappings and resources can also be installed from Hydrilla repository which serves both simple and complex (i.e. multi-resource) payloads. Defining more complex mappings and resources within Haketilo itself is not (yet) supported.

## Operating the popup window

**Note: this section of the manual corresponds to old Haketilo version 0.1 and is awaiting an update**

While browsing with Haketilo installed, a small Haketilo icon will be present in the extension panel (usually located to the right of the url bar). Clicking on this will open the popup.

![Haketilo popup](hachette_popup.png)

At the very top and bottom of the popup are two very convenient shortcuts: the page's URL, prominently displayed, and a link to the [[#Using-the-settings|settings page]]. In the centre is the page's status report, containing information on how Haketilo has modified a page. For the above website there is no custom policy set, and so Haketilo simply applies the default policy of blocking scripts; however, where a policy is set for a matching [[URL patterns|URL pattern]], the pattern will be listed and the set policy used instead.

![Haketilo popup on opencores.org](hachette_popup_opencores.png)

Settings can also be modified from the popup. Clicking the "Edit settings for this page" button above the status report will bring up the editor panel.

![Haketilo popup with possible patterns list](hachette_popup_possible_patterns.png)

Policies for [[URL patterns]] matching the current page can be modified by clicking the corresponding buttons on the right-hand side (with any current matched URL pattern bolded), while script-blocking settings for the default policy are modified with the "Toggle policy" button. Note that setting this to " **block** [pages'] own scripts "- the default- will break many websites; this is an unfortunate side effect of bad web design, and we recommend persisting with it where possible.

Where sites break, among other reasons, you might wish to look for ethical fixes prepared by others. This can also be done from the the popup: clicking the "Install scripts for this page" towards the bottom of the main popup view will search all configured repositories for custom scripts compatible with the current page, and list any results. Haketilo comes with `https://api-demo.hachette-hydrilla.org` configured as the default repository to use. This can of course be changed in the settings page.

![Haketilo popup repository query results](hachette_popup_install_scripts.png)

Currently, there are very few custom scripts listed in the main Hydrilla instance; if you are lucky enough to find a match, however, click on the "Install" button to its right to install the policy.

In the frame that appears you can select which components you want to install. Note that components might behave improperly if you disable other ones they depend on. As of version 0.1, Haketilo will do nothing to stop you from messing things up ;)

![Haketilo popup importing scripts](hachette_popup_install_scripts_import_frame.png)

If you click "Ok", scripts and settings are imported. Voilà! They will appear in the popup on page reload, or can be viewed and managed under the appropriate tabs on the [[#Using-the-settings|settings page]].

Above all else, Haketilo is designed to put you in control of your web browsing. On pages where a custom policy is applied, buttons on the right-hand side of the popup allow you to view it in the settings page. The injected scripts can also be viewed there or even right in the popup! Like Haketilo itself, all scripts distributed as defaults with the extension and published in the Hydrilla repository are free software, which allows you to read, modify and distribute them in source code or compiled form without undue restriction.

![Haketilo popup viewing currently injected scripts](hachette_popup_injected_scripts.png)

## Manually importing custom scripts

**Note: this section of the manual corresponds to old Haketilo version 0.1 and is awaiting an update**

Although installation of site fixes and custom content is meant to be convenient through the use of a repository, one can also export and import such payloads to and from JSON files. In fact, all the scripts currently served by the default Hydrilla repository can be downloaded in that format from https://hachette-hydrilla.org/. Most are fixes for js-encumbered websites, but there are also some alternative interfaces for already-functional sites. You can download and install particular scripts one by one or go crazy and just import it all at once from the "All-in-one bundle".

After you've downloaded the right .json file, go to Haketilo's settings page (reachable by clicking the button at the bottom of the popup window) and click "Import".

![Haketilo settings page with import button](hachette_settings_import_but.png)

Now, find and choose the .json file with scripts.

![selecting bundle.json in file chooser](navigate_scripts_bundle.png)

In the frame that appears you can select which components you want to install. Note that components might behave improperly if you disable other ones they depend on. As of version 0.1, Haketilo will do nothing to stop you from messing things up ;)

![selecting which components to import from .json file](hachette_settings_import_frame.png)

If you click "Ok", scripts and settings are imported. Voilà! They can be viewed and managed under the appropriate tabs on the [[#Using-the-settings|settings page]].

## Using the settings

**Note: this section of the manual corresponds to old Haketilo version 0.1 and is awaiting an update**

As well as allowing you to [[#Manually-importing-custom-scripts|manually import scripts from JSON files]], the settings page provides access to all configurable options available in Haketilo. These are arranged under four tabs, one for each type of item- repository, page (pattern), bag, and script.

![the bags tab in the Haketilo settings](haketilo_bags_tab.png)

Each tab is arranged similarly, with a list of items followed by an "Add ..." button (which opens an empty new item for editing). Besides every item is an edit button, a remove button, and- except for on repositories- an export button, which exports the item and its dependencies to JSON format for download.

Editing an item will open up a form with appropriate fields. **Changes are not autosaved**; they must be manually committed using the "save" button at the bottom of each form.

![an edit form, in this case for a repository](haketilo_repo_edit.png)

Repositories and scripts currently employ relatively simple forms. However, to allow ample space for editing the source code of scripts, the form overflows the page,

which requires scrolling down to find the "save" button and avoid losing changes.

![an edit form for a script, too large to fit on one page](haketilo_script_edit.png)

Bags can contain scripts and other bags, and opening one to edit it will present alongside the name a list of items contained within. To add new items, click on the "Add scripts" button towards the bottom of the form, select which new items, and click "Ok".

![the edit form for a bag](haketilo_bag_edit.png)

![the item selection popup for a bag](haketilo_bag_popup.png)

Editing a page is slightly different to other items, even if the form works the same way. Instead of a name, pages have a field for a [[URL patterns|URL pattern]] that they apply to and a field for a payload to inject into them. This payload can be changed by clicking on the "Choose payload" button, which will bring up a popup similar to the one for bags except that only one item is selected at a time. Injecting a payload **will block all scripts that are sent with a page natively**.

![the edit form for a page](haketilo_page_edit.png)

![choosing a payload for a page](haketilo_page_popup.png)

As well as a list of all available scripts and bags, at the very bottom of the payloads popup there is the option "(None)" for no payload. When selected, this enables an additional checkbox in the editing form, which controls whether or not a the scripts sent with a page natively should be blocked. Script-blocking behavior on URLs without a corresponding page policy listed can also be set, at any time, using the "Toggle policy" button at the bottom of the pages tab.

![controlling script-blocking behavior in the pages tab](haketilo_edit_script_blocking.png)

## What to do next

Please [[Reporting bugs|REPORT BUGS]]. This is incredibly important. If nobody reports them, they likely won't get fixed.

You might want to learn about [[Known limitations|current limitations]] of Haketilo. If despite these you like the extension, please spread the word. We'll be also happy to receive some feedback or - if you're a programmer - code contributions. Consider [creating an account](/account/register) on our issue tracker or writing to koszko@koszko.org :)