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.
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:
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
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());
- The URL that will be captured
- 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):
- This is an 80x60 thumbnail image
- medium (default)
- This is a 160x120 thumbnail image.
- This is a 320x240 thumbnail image.
- This is a 640x480 thumbnail image.
- 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.
- This is a full size screen shot of the page. If you use this option, the "fullthumb" option of
- This is a custom thumbnail size. If this is set, you must specify the "custom" option.
- This is a thumbnail with a special effect applied to it. if this value is chosen, you must specify the "effect" option. ( : There appears to be a bug in the Bluga WebThumb service that prevents this from being fetched properly by the Bluga WebThumbs module.)
- 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.
- The Bluga module will avoid refreshing unless one of the rules mentioned below is true.
- 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.
This is an array of options. There are many:
- This may be either "jpg" (the default) or "png". Choosing "png" may result in additional token charges.
- An array of options:
- This is the width of the browser window to open for the thumbnail. This is in the range of 15 to 1280.
- 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.
- 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.
- This is an array of options. Specifying this option may result in additional token charges.
- The pixel width of your custom thumbnail.
- The pixel height of your custom thumbnail.
- 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:
- 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.
- Adds a drop shadow behind the thumbnail. The result will be 311x251 pixels.
- This adds a thing black border around the thumbnail. The result will be 302x242 pixels.
- 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.
- This value is used to control the size an position of the "excerpt" image. This is an array of the following options:
- The left edge of the excerpt. The default is 0.
- The top edge of the excerpt. The default is 0.
- The width of the excerpt. The default is 400. Values greater than 800 may incur additional token charges.
- 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
$urlhas 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
$sizeof "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
$sizeargument 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
$sizechosen is not "excerpt".
- "never" (default)
- A refetch will only occur if no thumbnail ever generated matches the request (i.e., the rules just stated).
- 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.
In addition to these rules, the refetch is caused by setting the
$refetch value. The meaning of the values are: