Installation and Usage

Upload and install as normal using the Joomla! installer.

Usage

You can access the image generator directly by passing the image you want to resize to it in a URL:-

index.php?option=com_imgen&img=myimage.jpg&format=image

There are two URL parameters that are mandatory

1. format=image is essentially to tell Joomla to output an image rather than an html page.
2. img=image_value, where you replace image_value with the path to your image. If the image is in the default images folder (defined in the component parameters) then you do not need to specify a complete path, just the image file name. Alternatively,
3. imgencoded=base64encoded_value can be used instead of the img parameter to pass a base 64 encoded image path (useful for disguising the source of the original image).

There are also some optional URL parameters:-

1. layout=layout_type, where layout_type can be jpg, png, or gif. If this URL parameter is not set then the layout type will be taken from the image type, so it is normally not necessary to set this parameter, but if for example you have a jpg image which you want to output as a png then you would set the layout to png.
2. width=width, where this is the width value in pixels.
3. height=height, where this is the height value in pixels.
4. quality=quality_value, where this is a value between 1 (worst quality) to 100 (best quality). Lower quality values reduce the file size but lower the quality of the resulting image. The value only affects jpg and png images. This parameter is optional and defaults to 100, or to the value set in the component options.
5. userid=id, where this is the user id of the image owner

Note that the width and height parameters are optional if you have set the default width and/or height in the component options. If you want to preserve the aspect ratio of the image, then just set either the width or the height, the other value will then be automatically calculated. If you set the width and height then there will be some image cropping unless the aspect ratio of the original image is the same as for the supplied with and height. Where image cropping takes place the component will attempt to centre the cropped area.

If you do not set either a width or height in the URL or the component options then no resizing will take place. This is useful if you want to keep the original image size, but apply some image compression or add a watermark for example.

So a complete example URL looks like the following:-

index.php?option=com_imgen&format=image&img=images%2Fstories%2Fmyimage.png&layout=jpg&width=300&height=300&quality=90

Setting the Component Options

Log into the Joomla administrator area, click on Components->Imgen, and click the options button. This will open the options dialogue.

Image Caching

It is a good idea to turn on the image caching, as this will reduce the load on your server. If you are installing the watermark plugin, remember to delete any old cached images in order to see the watermark.

Normally cached images are all stored in the images/imgen folder of your site. You can change this in the component options. If you are having problems with image naming conflicts you can enable the 'Preserve Folder Structure When Caching' option, this should prevent the problem from arising.

You can also pass a user id in the URL request:-

index.php?option=com_imgen&format=image&img=images%2Fstories%2Fmyimage.png&layout=jpg&width=300&height=300&quality=90&userid=87

the effect of this is to store the cached image in a subdirectory named for the user id. If you are using a default folder for images, the component will also look for the original image in a folder named by the user id.

Using Imgen With Virtuemart and Other Extensions

Using Imgen with other extensions is very straightforward, particularly if the extension uses a templating system, since it is normally just a case of editing the template to access images via Imgen. For example if you are using Virtuemart with the default theme, then you will need to edit the theme.php file.

To resize the main product image using Imgen you just need to add an additional line at line 82:-

Below lines 76 to 81:

if( stristr( $product['product_full_image'], "http" ) ) {
$imageurl = $product['product_full_image'];
}
else {
$imageurl = IMAGEURL.'product/'.rawurlencode( $VM_LANG->convert($product['product_full_image']));
}

Add this:-

$imageurl = 'index.php?option=com_imgen&format=image&img='.$imageurl;

Imgen Plugins

The imgen component supports its own 'image' plugin framework. This framework triggers two image events:-

1. 'onImagePrepare' is triggered when the image source path is determined, and the image path is passed to the plugin. This could potentially be used to determine if the current user is permitted to view the image, if not the source could be changed to null or a generic image.
2. 'onImageOutput' is triggered when the image is ready to be output, the gd image resource is passed to the plugin. The imgen watermark plugin uses this to embed a watermark image.

There are (so far) three free plugins for Imgen:

Image Resizer

This content plugin can automatically resize all your article images for you, it simply checks all the image urls in your articles, and alters them so that the images are accessed via Imgen so that they can be resized, compressed and have a watermark added (if you are using the watermark plugin as well). The plugin supports different sizing for the images depending on whether they are being viewed on the front page, in blog format, or article format. The plugin also allows you to base64 encode the image path, making it easier to disguise the original file source of your image.

This plugin works with Joomla 1.5 and above content articles, and should work with all content components that support content plugins.

Watermark Plugin

This plugin allows you to overlay a semi-transparent watermark image over the top of Imgen generated images. To use if you will require the Imgen component to be installed, then install and enable the watermark plugin. You then access the image generator as described above, either through the image url, or using the Image Resizer plugin.

You will get the much best results by using a transparent png for your overlay image, because the image alpha transparency will be preserved. However if you haven't got one you can use a jpeg or gif image and set the watermark opacity (to a value between 1 and 100, the default value is 10).

You can also set the minimum image size of image for which a watermark will be applied through the watermark plugin parameters.

Image Restrict Plugin

This plugin allows you to restrict the viewing of your Joomla images to chosen user groups.

To use if you will require the Imgen component to be installed, then install and enable the Image Restrict plugin. You then access the image generator as described above, either through the image url, or using the Image Resizer plugin.

You can set the user groups that you want to be able to view images in the plugin parameters, and choose whether you want them to be shown an alternative image.