• Tuesday February 9th 2010
• Do you want fries with that project?

ThumbsDown

resources:	Home Screenshots Installation User Guide Forum Source Code Bugs Feedback

User Guide

1. Introduction
2. Prerequisites
3. Configuration
4. Scripts
5. Script: Direct
6. Script: RegExp
7. Script: Wrapped
8. Script: Custom
9. Script Wizard
10. Usage
11. Support

Introduction

ThumbsDown is a bulk/mass image downloader for Firefox. Or to be precise, ThumbsDown doesn't actually download any images. It just helps you to select the images you want to download from a web page, and then resolves the actual image URLs from the thumbnails before passing on the URLs to an external download manager.

Before ThumbsDown is any use to you, it requires some configuration. More specifically, writing some scripts, which is what this User Guide is mostly about. After you have done that, the normal usage goes like this:

1. Go to a web page with thumbnails.
2. Activate ThumbsDown.
3. Select the images you want to download by clicking their thumbnails on the web page.
4. Start the download.

Prerequisites

1. Firefox 3 or newer
2. ThumbsDown
3. download manager: DownThemAll! 1.0 or newer

Configuration

ThumbsDown is configured through its Options dialog. The dialog is accessed like any other extension's Options dialog from Tools menu: Tools > Add-ons > Extensions > ThumbsDown > Options (that's in Windows; Linux and Mac differ).

The options dialog has three panels: Main, User Interface and Scripts. The options there should be quite self-explanatory. Writing the actual scripts is discussed later in more detail.

You should also check DownThemAll! settings that they are to your liking. What they are, don't affect ThumbsDown.

Scripts

ThumbsDown scripts are used to identify thumbnails on a web page and resolve the actual image URL from them. You can create and edit them by hand in Options dialog's Script pane, or you can generate them semi-automatically using Script Wizard. Using the latter method is strongly recommended when ever possible. Whatever method you use, a little familiarity with things like HTML, regular expressions and JavaScript helps. If you don't know them, don't worry. This is not that complex.

But before going to details, a few terms and concepts that are used in this User Guide:

Full-size image

The original, full-size image.

Thumbnail

A reduced-size version of a full-size image. ThumbsDown also requires a thumbnail image to be a link. That is, the IMG tag must be enclosed in an A tag (<a href="…"><img src="…"/></a>) for it to be considered a thumbnail. In practice this means for example that ThumbsDown won't work with sites that use <div>s to show thumbnails. A and IMG tags' URLs are referred as link and thumbnail URLs respectively.

Thumbnail URL

URL of the thumbnail image.

Link URL

URL of thumbnail link.

Source URL

Common name for thumbnail/link URL.

Image URL

URL of the full-size image.

There are four types of scripts (Direct, RegExp, Wrapped and Custom) which are used depending how the full-size image is hosted. All scripts have a name, matcher and action that resolves the final image URL. Script name is simply some descriptive name. Script matcher is regular expression that it is used to match against link URL so that ThumbsDown can identify which script to use. Script action is specific to the script type which are explained below in more detail.

Script: Direct

Script type Direct is used when the full-size image is available directly. That is, the thumbnail links directly to full-size image. Therefore, Direct script has no action, as the final image URL is the link URL. The only thing needed, is to write a matcher (regular expression) that matches thumbnails' link URLs.

For example, if you wanted to download the images below:

1. Open ThumbsDown Options dialog.
2. From Scripts panel, add a new script.
3. Give the script a descriptive name.
4. Write a matcher that matches the link URLs.
5. Set the type to Direct.
6. Close the script dialog by pressing OK.
7. Activate ThumbsDown, select the thumbnails and start the download. See Usage for details.

If everything went according to the plan, DownThemAll! Manager window should open and start downloading the images.

Script: RegExp

Script type RegExp is used when the thumbnail doesn't link directly to the full-size image. For example, the thumbnail leads to another web page that wraps full-size image.

Like Direct script, RegExp has a name, and a matcher to match link URL. But in addition, it has an action that converts a thumbnail or link URL (source URL) into a image URL. The action has two parts: pattern and template. Pattern (regular expression) is used to match the source URL and capture interesting bits from it (like path or file name). Then those bits are substituted into a template to create a image URL.

For example, if you wanted to download the images below:

1. Open ThumbsDown Options dialog.
2. From Scripts panel, add a new script.
3. Give the script a descriptive name.
4. Write a matcher that matches the link URLs.
5. Set the type to RegExp.
6. Set pattern source to Thumbnail.
7. Write a pattern that matches and captures the source URL.
8. Write a template for image URL.
9. Close the script dialog by pressing OK.
10. Activate ThumbsDown, select the thumbnails and start the download. See Usage for details.

When you get that working, try setting the pattern source to Link and writing pattern for it. In practice, it doesn't matter which pattern source you use. Sometimes the other is just easier to use than the other.

Script: Wrapped

Sometimes resolving a image URL from a thumbnail or link URL is not possible. The image URL may have some part that varies but it doesn't exist in the source URL. Wrapped script is for these instances when link URL leads to the web page that wraps the full-size image but RegExp script isn't enough to get it to work.

Wrapped script has a name and a matcher, just like Direct and RegExp scripts, but in addition it uses another regular expression to match the image tag by one of its attributes. Unlike Direct and RegExp, Wrapped script actually loads the web page that wraps the full-size image so that it can look though the image tags attributes.

For example, if you wanted to download the images below:

1. Open ThumbsDown Options dialog.
2. From Scripts panel, add a new script.
3. Give the script a descriptive name.
4. Write a matcher that matches the link URLs.
5. Set type to Wrapped.
6. Write "id" to attribute field (without the quotes).
7. Go the web page that wraps the full-size image (click either of the thumbnails above).
8. Open the image's Properties dialog (open context menu on image and select Properties)
9. Lookup Element id value and copy paste it to the value field in script dialog.
10. Close the script dialog by pressing OK.
11. Activate ThumbsDown, select the thumbnails and start the download. See Usage for details.

Now, instead of DownThemAll! popping up, you should see ThumbsDown Script Runner. It runs a script that downloads the web page that wraps the image and locates the full-size image. If the script completes successfully, it hands the image URL to DownThemAll! to download.

In the above example, the value appeared to be a simple string, but actually it's a regular expression. Also the attribute can be any attribute the image tag has. For example, you could write a regular expression to match image tag's src attribute.

Script: Custom

Sometimes none the above scripts work. The URLs varies in a way that cannot be handled with other scripts, or the link URL doesn't lead directly to the page that wraps the full-size image. Script type Custom is for these instances.

Custom script has a name and a matcher, just like the other scripts, but the action part is basically a small JavaScript script that you write. Like the name Custom implies, the action (script) can do anything, as long as it returns the image URL in the end.

Usually this means loading a web page that wraps the image and figuring out which image is the actual full-size image that you want. ThumbsDown includes a couple code templates that can help you to get started.

For example, if you wanted to download the images below:

1. Open ThumbsDown Options dialog.
2. From Scripts panel, add a new script.
3. Give the script a descriptive name.
4. Write a matcher that matches the link URLs.
5. Set the type to Custom.
6. Open context menu from code area and select Use Code Template > Image Id.

Now you should be seeing a few lines of code. You don't have to understand what it does (Well, in phase 1 it loads the page that wraps the full-size image, and phase 2 it looks up the correct IMG tag by its id attribute and returns its src attibute (image URL)). The thing you have to do, is to replace the XXX on line 5 with the real id attribute.

7. Go the web page that wraps the full-size image (click the thumbnail).
8. Open the image's Properties dialog (open context menu on image and select Properties)
9. Lookup Element id value and replace the XXX with that value.
10. Close the script dialog by pressing OK.
11. Activate ThumbsDown, select the thumbnails and start the download. See Usage for details.

Like in Wrapped script, ThumbsDown Script Runner executes your script and hands the image URL to DownThemAll! to download.

Now, you might ask you why not just use Wrapped script from previous chapter. Well yes, it would work just as well. Wrapped is actually kind of built-in custom script that was added in 0.12 to handle just the above case because majority of Custom scripts seem to fit that pattern (in my experience, at least).

All the variables and functions available in a script:

variable / function	description
state	Integer value. Holds the state of the script between document loads (see LOAD()). Initially its value is 1.
linkUrl	Link URL.
thumbnailUrl	Thumbnail URL.
document	Document object that was loaded by LOAD().
LOAD(url)	Exits the script. Document from url is loaded and stored in document and the script is rerun with state incremented by one.
LOG(message)	Prints the message to Firefox's Error Console (Tools > Error Console).
REDIRECT(linkUrl)	Hands over image URL resolving task to another script. Note because thumbnail URL is not availabe, only link URL is, RegExp scripts that use thumbnail URL as their source URL, cannot be the target of redirect, simply because they don't match.
RETURN(url)	Exits the script. url is the actual image URL that is passed on to download manager.
$(elementId)	Shorthand for document.getElementById().

Script Wizard

Instead of writing scripts completely by hand, you can use Script Wizard to help you to create them. Script Wizard can generate the regular expressions required by the scripts in simple cases.

Script Wizard should be easy enough to use without a guided tour. Though, below are some things you need to be aware of:

• Keep it simple: One script, one image host.
• When creating a script, select only couple thumbnails to work with. You don't need to select all the thumbnails available on a page even if you are planning to download them all later.
• When creating a new script, just accept the offered regular expressions if they match. Don't try to guess what part of the script varies and what doesn't. Do it the next time, when you are modifying an already existing script. Then it will be simpler to see what parts of the URLs vary and how.
• When modifying an existing script, you need modify the old regular expressions by yourself to match the new thumbnails/images. Script Wizard is not smart enough to do it automatically. Refer to this syntax help if you are not familiar with regular expressions.
• Script Wizard support Direct, RegExp and Wrapped scripts, but not Custom.
• When you use a script for the first time, check that it actually downloads the image file you wanted.

Usage

Depending on your settings in ThumbsDown's options, the various ways to do things below may or may not be available. Also, shortcut keys are platform specific. The ones below are what ThumbsDown uses in Windows by default. On Linux and Mac the keys differ.

Accessing ThumbsDown

• Open ThumbsDown context menu from ThumbsDown icon in the status bar.
• Open browser's context menu > ThumbsDown.
• Tools > ThumbsDown.

Activate/Deactivate ThumbsDown

ThumbsDown needs be activated separetely for each tab before you can use it.

• Click on ThumbsDown icon .
• Activate/Deactivate from ThumbsDown context menu.
• Activate/Deactivate shorcut key (Alt+1).

Selecting images

ThumbsDown needs to be activated before you can select images. Though Select All activates ThumbsDown implicitly.

• Click on a thumbnail.
• Double click on ThumbsDown icon . Selects all.
• Select All from ThumbsDown context menu.
• Select All shortcut key (Alt+2).
• Select region that has thumbnails in it like you would select text.

Downloading

After you have selected some images you can start the download. This will automatically deactivate ThumbsDown.

• Middle click on ThumbsDown icon .
• Download from ThumbsDown context menu.
• Download shorcut key (Alt+3).

Support

Questions, comments, problems, feature requests: ThumbsDown Forum.