Bluga WebThumbs

The Bluga WebThumbs module provides a very complete implementation of the Bluga WebThumb API. It does not, however, provide much else. The most useful (and intended) use of this module is either to be used by other modules wishing to build on it or provide a way for a Drupal site with a custom theme to display a thumbnail based on the content of a node. This can be used with a custom PHP filter if you prefer as well.

Configuration

After installing the module, you will need to go to the settings page (found under Site Configuration if you are logged in as a role capable of administering the site).

• Here you will need to enter your API key. The link to sign up for an account is on that page.
• You will also select a directory under which to store your thumbnails. The configuration screen will warn you if the directory needs to be created or made accessible for writing.

Creating a Thubmnail

The basic syntax is:

print bluga_webthumb('http://drupal.org');

That snippet, once everything is installed, will ask the Bluga WebThumb service to create a thumbnail image of what the Drupal.org site looks like in a browser. Bluga does not immediately return a thumbnail, so a placeholder will show at that point in the PHP file. If you do not print the output of the bluga_webthumb function, it will still ask Bluga to generate a webthumb, but will not display it or a placeholder. Either by reloading the page, or, if JavaScript is enabled, waiting a few seconds, the thumbnail will appear in place of the placeholder once Bluga takes the snapshot and makes it available.

More Options

Additional options may be given to control the details of the request. Here's the full signature of the function:

$html = bluga_webthumb($url, $size = 'medium', $refetch = 'never', $options = array());

$url

The URL that will be captured

$size

Each webthumb comes with at least 5 different sizes available and may come with up to three others (at least as of 1.1 of the Bluga API):

small

This is an 80x60 thumbnail image

medium (default)

This is a 160x120 thumbnail image.

medium2

This is a 320x240 thumbnail image.

large

This is a 640x480 thumbnail image.

excerpt

This is usually a 400x150 snapshot of the web site without scaling (not actually a thumbnail). Using the "excerpt" option described below is used to customize this further.

full

This is a full size screen shot of the page. If you use this option, the "fullthumb" option of $options is implied.

custom

This is a custom thumbnail size. If this is set, you must specify the "custom" option.

effect

This is a thumbnail with a special effect applied to it. if this value is chosen, you must specify the "effect" option. (#620736: Bluga WebThumbs cannot fetch effect thumbnails: There appears to be a bug in the Bluga WebThumb service that prevents this from being fetched properly by the Bluga WebThumbs module.)

$refetch

The thumbnail that you request will be cached so that you do not use up your tokens every time someone looks at your page. However, you may want to refresh a thumbnail periodically. This option determines how often that refresh will happen.

never

The Bluga module will avoid refreshing unless one of the rules mentioned below is true.

always

Every page load and refresh will cause a refetch. This is probably never desirable except as a one-off.

Date/Time String

Any date understood by strtotime may be used. The base date will be the last request made for this URL, so relative dates like "+1 week" or "+1 month" will refresh every week or every month, respectively.

$options

This is an array of options. There are many:

output_type

This may be either "jpg" (the default) or "png". Choosing "png" may result in additional token charges.

browser

An array of options:

width

This is the width of the browser window to open for the thumbnail. This is in the range of 15 to 1280.

height

This is the height of the browser window to open for the thumbnail. This is in the range of 15 to 2048. Larger than 1024 may result in additional token charges.

fullthumb

This is either 0 or 1. A value of 0 is the default. If you set this to 1, you will have an additional thumbnail size "fullsize" available (in addition to the regular "medium" or other size selected). This will be a fullsize screenshot of the web site at the dimensions set for the "browser" option.

custom

This is an array of options. Specifying this option may result in additional token charges.

width

The pixel width of your custom thumbnail.

height

The pixel height of your custom thumbnail.

effect

This is a special effect that Bluga will apply to your thumbnail to generate the "effect" thumbnail. The size of this thumbnail depends on the effect chosen. Using this option implies that "output_type" is set to "png". Using this option may incur additional token charges. The available effects include:

mirror

Adds a upside down reflection below the thumbnail, as if the thumbnail were a plate standing up perpendicular to a glass surface. The effect image will be 300x361.

dropshadow

Adds a drop shadow behind the thumbnail. The result will be 311x251 pixels.

border

This adds a thing black border around the thumbnail. The result will be 302x242 pixels.

delay

This is the number of seconds Bluga will wait for a page to load before taking the snapshot. The default is 3 and may be set as low as 1 or as high as 15.

excerpt

This value is used to control the size an position of the "excerpt" image. This is an array of the following options:

x

The left edge of the excerpt. The default is 0.

y

The top edge of the excerpt. The default is 0.

width

The width of the excerpt. The default is 400. Values greater than 800 may incur additional token charges.

height

The height of the excerpt. The default is 150. Values greater than 600 may incur additional token charges.

Saving Your Tokens

Whenever possible, the API will try not to cost you additional tokens by making fresh requests to Bluga. The bluga_webthumb function will attempt to use the most recent thumbnail available if doing so is possible with the given parameters. A new request will occur if any of the following are true.

• The given $url has never been fetched before by this module,
• The "browser" option is given and no previous matching request was made using the same "width" and "height" values,
• The "fullthumb" option is given (or by specifying a $size of "full", which implies the same option) and no previous matching request was made with that option
• The "custom"option is given and no previous matching request was made using the same "width" and "height" values. This will occur even if the $size argument is not set to "custom".
• The "output_type" option specified has not been used for a matching request previously (even if the "effect" thumbnail, which is not effected by this option, is specified).
• The "effect" option specified has not been used for a matching request previously. This is true even if the "effect" thumbnail is not specified.
• The "delay" option is given as a different value than has been used before on a matching request.
• The "excerpt" option is given as a different value than has been used before. This causes a refetch even if the $size chosen is not "excerpt".

In addition to these rules, the refetch is caused by setting the $refetch value. The meaning of the values are:

"never" (default)

A refetch will only occur if no thumbnail ever generated matches the request (i.e., the rules just stated).

"always"

A new request will be made everytime.

Date/Time (any date string understood by strtotime)

A new request will be made after the given date. If you use a relative date, the base date will be the last time a request was made for the URL. For example, you could use "+1 week", which would refresh the thumbnail every week.