Basics

A host rule is MPIV's compact description of how to grab images from a site. You can make MPIV work with more sites by adding your own host rules.

Host rules are installed by pasting them into MPIV's settings dialog which is accessible from your script manager's toolbar icon menu, e.g. "User Script Commands" → "Set up Mouseover Popup Image Viewer" (Greasemonkey).

MPIV's host rule repository contains rules shared by other users. These rules can be accessed directly via settings dialog. In addition, rules you see in GreasyFork's forum can be installed by clicking them.

Read on if you're familiar with HTML, CSS selectors and regular expressions.

In the simplest case, a host rule consists of a URL pattern and a CSS selector:

Host rules are written in JSON format. The regular expression goes in property "r", the CSS selector goes in property "q" (query). Don't forget to escape special characters, e.g. \ becomes \\ and " becomes \" when written as JSON string.

Example: {"r":"imagebam\\.com/image/", "q":"img[id]"}

You can show text as caption using property "c" which works similarly to property "q", i.e. you specify a CSS selector and MPIV will pick the appropriate HTML attribute of the first matching element. The element's textual content will be used in case no fitting attributes exist. Property "c" reads from the same document as property "q". If "q" doesn't exist, the selector will be applied on the local (currently active) browser tab.

Example: {"r":"pinterest\\.com/pin/", "q":".pinImage", "c":"meta[property='og:description']"}

MPIV shows HTML tooltips as caption by defaut. This means if property "c" is not used, MPIV will display the text from the title attribute of the element under the mouse cursor. Setting "c" to "" (empty string) turns this off. In order to disable HTML tooltips for more than just a single host rule, check out Custom CSS.

Special Cases

If the actual image URL can be derived from the link/thumbnail alone, you can speed up the whole loading process by specifying a URL substitution pattern so the HTML fetching and parsing step is being avoided. The pattern can be a URL or a vim/sed-inspired /regexp/replacement/flags string. Use $1, $2 and so forth to reference RegExp groups you defined in property "r".

Example 1: {"r":"hotimg\\.com/image/([a-z0-9]+)", "s":"http://www.hotimg.com/direct/$1"}

Example 2: {"r":"hotimg\\.com/image", "s":"/image/direct/"}

It's also possible to provide a list (in square brackets) of substitution patterns. If the first replacement doesn't load successfully, MPIV will silently try the second one and so forth.

Example: {"r":"example\\.com/pics", "s":["/small/large/", "/small/medium/"]}

Properties "s" and "q" can be used together if "s" is a single pattern. In this case, your constructed URL will be the input for "q" - not the element's original one. Use this fact to clean up URLs before MPIV starts requesting them.

By default, the regular expression is applied on href and src attributes of links and images. MPIV looks at thumbnail locations first and surrounding links second. Insert "html":true to search inside their HTML source instead. This way your regular expression is able to access URL segments in e.g. data attributes and inline styles. However, processing large chunks of HTML is bad for performance. You should therefore avoid using "html":true without additional constrains (explained further below).

If "html":true is present, you must provide a substitution pattern.

Some sites (usually the ones with money-making schemes and obnoxious ads) force users to view their images directly on their site by prohibiting hotlinking. Insert the property "xhr":true into the host rule and images will be downloaded in an alternative way which should circumvent such protections.

Example: {"r":"stooorage\\.com/show/", "q":"#page_body div div img", "xhr":true}

If you want MPIV to process elements other than <a> and <img> because a site uses let's say <li> elements with CSS backgrounds as thumbnails, you need to specify a selector for them in property "e". Keep in mind that even now regular expressions will only be applied on href and src attributes. That means if the matching element lacks href and src attributes, you need to set "html":true or write your own parsing code. Property "e" can also be used as an elegant alternative to "r".

Example: {"e":"a.avatar", "s":"/small/large/"}

In order to avoid needless evaluation of rules that make only sense on a single website, write the site's domain (or a part of it) in property "d".

Example: {"d":"example-shop", "r":"data-product-pic=\"(http+?)\"", "s":"$1", "html":true}

Advanced Use

Rule properties "s", "q" and "c" may contain JavaScript code which provides a maximum of flexibility.

While "s" and "q" can either return a single URL or an array of URLs, "c" is expected to return a descriptive text string.

Example 1: {"r":"example\\.com/foo", "s":"if(node.className == 'ad') return ''; else return m.input.toLowerCase();"}

Example 2: {"e":"a.pic", "s":"return ['png', 'gif', 'jpg'].map(function(ext) { return node.dataset.base + ext; });"}

If "s" returns false, MPIV will proceed to the next rule. If "s" returns '' (empty string), no further rule will be evaluated.

Available variables in "s":

m
RegExp result array
node
HTML element that triggered popup

Available variables in "q" and "c":

doc
DOM tree of remote page (when "q" exists and HTTP response could be parsed)
text
raw HTTP response / source code of HTML page
node
HTML element that triggered popup (in local DOM tree)

Property "follow":true causes MPIV to completely restart rule evaluation with the URL returned by "q" or "s" as input. This comes in handy when you deal with sites that don't host images themselves. If neither "q" nor "s" exists, MPIV will follow all HTTP redirections (Location header) and restart evaluation with the last URL requested. Rules with "html":true will be skipped during re-evaluation if the new input URL was taken from a different page.

Example 1: {"r":"example\\.com/view", "q":"a[href*="imagebam"]", "follow":true}

Example 2: {"r":"example\\.com/redirect\\.php\\?decrypt=", "follow":true}

A few sites clip their thumbnails by putting them in containers smaller than the thumbnails themselves. As a result, MPIV's popup stays open longer than you would expect because your mouse cursor hasn't left the invisible part of the thumbnail yet. If you encounter a situation like this, write a CSS selector in property "rect" to guide MPIV to an ancestor node whose bounding rectangle makes more sense to you.

Insert property "manual":true to disable automatic popup activation on a case-by-case basis.

Use property "css" to apply CSS styling to the page in case the rule gets chosen.

Example: {"e":"a.user-profile", "q":"#user-pic", "css":"#user-hovercard { display:none; }"}

MPIV has basic support for HTML5 video. Host rules may point to source elements and return URLs ending in webm/mp4.

Rule-O-Matic™

Apply this regular expression
/ /i
on of links and thumbnails.

Rewrite URL to
which points to

Grab actual image from remote page using this CSS selector:

The remote site hotlinking.

Host rule will appear here.

Tips & Gotchas