Overview
The Jamroom Image script (image.php) is used in Jamroom to display images, and offers many different features and options to allow you the most flexible use of images possible. Some features include:
- The ability to resize (and cache) images on the fly
- The ability to add "filters" to images to add special effects
- The ability to handle caching and viewer browser caching scenarios to reduce bandwidth usage.
- The ability to add a watermark to images
The Image Script is at the core of all images in Jamroom, so understanding some of the options available to you can help you when designing your site.
Usage
The Jamroom image.php script is meant to be used in the "src" parameter in an HTML <img> tag - i.e.
<img src="{$JAMROOM_URL}/image.php?mode=band_image&band_id=1">
All of the options that are available to the image.php script will be passed in to the script via the URL.
Parameters
The following URL parameters are supported:
| Parameter |
Type |
Required |
Description |
| mode |
string |
yes |
The "mode" tells the Jamroom image.php script the "type" of image that you want to display. Valid values for the "mode" are: band_image, song_image, video_image, photo_image, event_image, store_image, vault_image, radio_image, channel_image, user_image, message_image, captcha and rotator. Some custom modules can also define an image "mode", in which case the "mode" will be the name of the module. |
| band_id |
number |
yes* |
The band_id parameter is required for all image modes, * except captcha |
| quota_id |
number |
no |
When using the image.php script in "rotator" mode, you can pass in a valid string of quota_id's (or a single quota_id) to only rotate images from the given id's - i.e. quota_id=5,3,1 or quota_id=-5 |
| *_id |
number |
yes* |
Depending on the "mode", and additional "id" may be required to show the image. This includes: video_id, image_id, event_id, item_id, vault_id, radio_id, channel_id, user_id or message_id |
| width |
number |
no |
If the "width" parameter is defined, the image will be resized to the given width. If no "height" parameter is provided, Jamroom will scale the height to match the aspect ratio determined from the given width. |
| height |
number |
no |
If the "height" parameter is defined, the image will be resized to the given height. If no "width" parameter is provided, Jamroom will scale the width to match the aspect ratio determined from the given height. |
| max_width |
number |
no |
If the "max_width" parameter is given, then the image will not be resized larger then the max_width in width, even if the aspect ratio of the image based on the height would cause the width to be wider (instead the height will be lessened). |
| max_height |
number |
no |
If the "max_height" parameter is given, then the image will not be resized larger then the max_height in height, even if the aspect ratio of the image based on the width would cause the height to be taller (instead the width will be lessened). |
| crop_height |
number |
no |
The "crop_height" parameter will crop the image to the given height, using a special formula to "crop out" the middle of the image. |
| theme |
string |
no |
When an image is being displayed, if there is no image data for the requested mode, then Jamroom will use a "default" image. If a Profile Theme defines custom "default" images, the name of the theme must be provided, or else the "default" default images located in jamroom/images will be used. |
| skin |
string |
no |
When an image is being displayed, if there is no image data for the requested mode, then Jamroom will use a "default" image. If a Jamroom Skin defines custom "default" images, the name of the skin must be provided, or else the "default" default images located in jamroom/images will be used. |
| filter[] |
string |
no |
The Jamroom image script also provides a set of "filters" that can be used on your images in order to apply special effects to the output (cached) file. Filters are called using a special format for the URL:
&filter[]=filter_name:param1:param2:paramN
Available filters include:
- rounded - creates rounded corners on an image - i.e. "image.php?mode=band_image&band_id=1&filter=rounded:5"
- parameter 1 is a "number" that defines the number of pixels of rounding to apply to the image corners
- You can optionally define all 4 corners as separate values - i.e. "image.php?mode=band_image&band_id=1&filter[]=rounded:5:8:11:14" to define the top left, top right, bottom left and bottom right corner values individually.
- cut - creates "cut" corners on an image - i.e. "image.php?mode=band_image&band_id=1&filter=cut:5"
- parameter 1 is a number that defines the number of pixels into the image corner to make the corner cut.
- You can optionally define all 4 corners as separate values - i.e. "image.php?mode=band_image&band_id=1&filter[]=cut:5:8:11:14" to define the top left, top right, bottom left and bottom right corner values individually.
- grayscale - creates a grayscale version of the image.
- reflection - create a "reflection" of the image in front of the image.
- parameter 1 defines the percentage of the image height that should be reflected "in front" of the image.
Filters can be "chained" together to produce effects, but the order that the filters are used in is important, as some filters "override" other filters
|
Configuration Options
Along with the URL parameters listed above, there are also some settings within the Jamroom Config and Jamroom Quota sections that can be set that will affect image appearance and script performance.
The first set of options are found in the Jamroom Config -> Media Settings section:
These settings are applied to ALL calls to the image.php script - in other words, they are "global" settings. Individual help is associated with each item by holding your mouse over the small question mark image (help).
There are also some image settings that are applied on a per-Jamroom Quota basis:
These settings allow you to set a "cap" on the max image width/height - this prevents the image.php script from trying to resize an image to a really large size (which consumes a lot of CPU power and Memory).
|
