|
UserGuide
ThumbsDown User Guide.
This User Guide is slightly out of date at some points. Nothing major but still something you should be aware of. Updated when I have the time. IntroductionThumbsDown 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:
Prerequisites
ConfigurationThumbsDown is configured through its Options dialog. The dialog is accessed like any other extension's Options dialog from Tools menu: Windows: Tools > Add-ons > Extensions > ThumbsDown > Options 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. ScriptsThumbsDown 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 whenever possible. Whatever method you use, a little familiarity with things like HTML, DOM, 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:
There are four types of scripts: Direct, RegExp, Wrapped and Custom. They 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 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. DirectScript 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 full-size images of the thumbnails below:
If everything went according to plan, DownThemAll! Manager window should open and start downloading the images. RegExpScript 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 the image URL. For example, if you wanted to download the full-size images of the thumbnails below:
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. WrappedSometimes 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 <img> 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 through the <img> tag's attributes. For example, if you wanted to download the full-size images of the thumbnails below:
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. The above example used alt attribute, but any <img> tag's attribute works as well. Usually id attribute is the best choice if available. And remember that script's value field is actually a regular expression. So for example, you can write a regular expression to match <img> tag's src attribute. CustomSometimes 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 full-size images of the thumbnails below:
Now you should be seeing a few lines of code. You don't have to understand what it does (Well, in phase 0 it loads the web page that wraps the full-size image, and in phase 1 loops through web pages images and tests if their src attribute matches the provided regular expression (attrValuePattern)). But here we are not going to use src, but alt attribute instead.
Like in Wrapped script, ThumbsDown Script Runner executes your script and hands the image URL to DownThemAll! to download. The above example used alt attribute, but code template's original src attribute would have worked as well. Though the easiest solution is to use Image ID code template if <img> tag has id attribute available. Now, you might ask why not just use Wrapped script from previous chapter. Well yes, it would have work just as well. Wrapped is actually kind of built-in custom script that was added in ThumbsDown 0.12 to handle just the above case because majority of Custom scripts fit the pattern where simple <img> tag attribute matching is enough. ThumbsDown scripts are currently executed in stages (switch (state)). It's not very pretty but it works for now. VariablesVariables available to Custom scripts.
FunctionsFunctions available to Custom scripts.
Script WizardInstead 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. For practice, you should create a script for each example in Scripts chapter using Script Wizard. Below are some things you need to keep in mind when using Script Wizard:
UsageDepending 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
Activate/Deactivate ThumbsDownThumbsDown needs be activated separetely for each tab before you can use it.
Selecting imagesThumbsDown needs to be activated before you can select images. Though Select All activates ThumbsDown automatically.
DownloadingAfter you have selected some images you can start the download. This will automatically deactivate ThumbsDown.
Support
| ||||||||||||||||||||||
|
|
