BackendPro User Guide Version 0.6.1

Image Controller

The Image controller is a new way to load asset images. It takes all the hassle and worry out of storing images of the correct size and then displaying them on a page. It has the following features:

Setup

Before using the image library there are a few settings you may want to tweak. Thse can be found in modules/image/config/image.php.

Preference Default Value Options Description
image_default_quality 100 None The default image quality to output images at.
image_folders assets/images/ None An array of folders (relative to index.php file) where images can be located in.

Using the Image Controller

Basic Usage

You may have noticed this feature is implemented as a controller not a library, this is to keep code down and simplify the use of the class. The basic way you use the class is to pass the required parameters through the URI. Lets look at the most basic use of the class:

<img src="<?=site_url('image/get/file/my_image.jpg')?>" />

Thats it, thats all you need. Now as said this is a rather simple use of the controller. All this will do is load an image called my_image.jpg. To find this image it will search all the folders specified in the image.php config.

Resizing an Image

Now there will be times when you want to resize an image before you display it, maybe a thumbnail or something. This is fully possible, and there are three possible ways to resize an image. All methods to resize an image keep the width/height ratio.

  1. By Width

    This will resize an image down to a certain width while keeping the width/height ratio.

    <img src="<?=site_url('image/get/width/400/file/my_image.jpg')?>" />
  2. By Height

    This will resize an image down to a certain height while keeping the width/height ratio.

    <img src="<?=site_url('image/get/height/250/file/my_image.jpg')?>" />
  3. By Area

    This will resize an image down to make sure it fits in the specified constraints. This is very good if you have to handle landscape & portrait images but still want them to fit in a certain area on your page. What it does is it resizes the image based on the largest dimension. This guarantees the image will be small than the dimensions you specify in the URI.

    <img src="<?=site_url('image/get/width/100/height/200/file/my_image.jpg')?>" />

Cropping an Image

Cropping an image to a correct format can be very handy and with the Image Controller its simple to do.

<img src="<?=site_url('image/get/crop/1:1/file/my_image.jpg')?>" />

From the example above you will see I have applied a crop of 1:1 to the image, you can specify any crop ratio you want instead of 1:1, e.g. 16:9, 3:2. As long as it follows the [number]:[number] format.

Changing Output Quality

There may be times when you want to show an image at reduced quality, maybe to save bandwidth or increase loading speed. You can change the quality again with a URI parameter. Quality is expressed as a percentage from 1-100.

<img src="<?=site_url('image/get/quality/60/file/my_image.jpg')?>" />

Image Caching

The Image Controller by default caches dynamically generated images in the default CodeIgniter cache folder. This is to save processing of the images upon every load. If you do not want the image to be cached just add the following URI paramter.

<img src="<?=site_url('image/get/nocache/true/file/my_image.jpg')?>" />

Overall Use

Note: You can specify the URI parameters in any order but to aid readability please put the file/<image_name>.jpg at the end, this also allows the image to be saved with the correct file name.

All the features above can be combined into a single URI which does everything from resizing to changing the quality of the image:

<img src="<?=site_url('image/get/crop/3:2/width/100/height/300/quality/50/nocache/true/file/my_image.jpg')?>" />

Transformation of the images are done in a specific order:

  1. Cropping
  2. Resizing
  3. Quality Adjustment