UnPlug

Rules

Write your own UnPlug rules

Rules are stored at chrome://unplug/content/rules.xml (and in rules.xml on this website). There is no easy way of changing this yet (this will probably be written for 2.1 or 2.2 release).

Technical definitions of the elements in rules.xml is in chrome/content/rules.js.

More information will be placed here in future.

Overview

rules.xml contains an <unplug> root node with several <rule> children. These children are evaluated as follows:

1. <if_*> statements are evaluated. If the statement is given a "ref" attribute, it may export variables so they can be used by <each_*>, <download>, <rule> and <media> stages (see below). If an <if_*> statement evaluates to false, the rule has failed and later stages will not be evaluated.
2. <optional_*> statements are evaluated. These are identical to <if_*> statements, but can evaluate to false without failing the rule. These can be used to search for additional information (such as a description or thumbnail) without fear of breaking the whole rule if they fail.
3. <each_*> statements are evaluated. These contain child statements which will be evaluated as if they were in a <rule> tag. The child statements may be evaluated many times. If the <each_*> has a "ref" element, variables are exported to the child statements.
4. <download> and <playlist> statements are evaluated. These contain child statements which will be evaluated (once) when a file has been downloaded. The child statements are evaluated against the downloaded file (eg: <if_re> searches the text of the download, and not the original document). <playlist> will be used to report that the download is a playlist in future UnPlug releases.
5. <rule> statements are evaluated. This lets you apply additional <if_*> and <optional_*> statements (which have access to the variables exported by the <if_*> and <optional_*> statements in this <rule>).
6. <media> statements are evaluated. These report to the UI that a media file has been found.

Example: get video from HTML5 <video> tags

This iterates over <video> tags on the page which have a "src" attribute. Because the <each_element> element has a "ref" tag, it makes both "src" and "poster" attributes of the <video> tag available to the <media> statement inside it. These variables are substituted into the ${videoref.src} and ${videoref.poster} placeholders.

<rule id="html5-video">
    <each_element ref="videoref" tagname="video" require_attrs="src" attrs="poster">
        <media url="${videoref.src}" thumbnail="${videoref.poster}"/>
    </each_element>
</rule>