SiteImage - silverorange/site GitHub Wiki

Overview

SiteImage dataobjects provide a convenient and powerful way of creating and manipulating multiple dimensions of images as well as well as simple methods for creating HTML image tags and retrieving path and file information about the images. The basic hierarchy of dataobjects related to SiteImage includes:

• SiteImageSet
  • Each SiteImage dataobject is assigned a SiteImageSet which specifies what denotes what sort of image it is. Each site can have multiple SiteImageSet objects such as titles, photos, or products.
• SiteImageDimension
  • Each SiteImageSet is assigned one or more SiteImageDimension objects. When a new image is saved, an image file for each dimension is saved as well. Besides the obvious width/height settings for each dimension, SiteImageDimension also provide options for cropping, dpi, quality, and interlacing. The maximum width an height properties are optional, and if not specified, the original height and width of the image will be preserved. If a default_type is set on an ImageDimension, all images will be converted to this specified type. If no default type is specified, and no maximum dimensions are also not specified, the image will be copied directly to the dimension directory without modification which useful for storing original images.
• SiteImageType
  • SiteImage objects each have a SiteImageType which defines what file format should be used for saving the image (jpeg, png, etc.) A default is set on the SiteImageDimension.

Creating a new SiteImageSet

Create a new image set involves both database and file-system changes.

Database

Sample SQL for setting up a new image set with 3 dimensions follows.

-- first, insert a SiteImageSet that defines the type of image being created:

insert into ImageSet (shortname, obfuscate_filename) values ('products', false);

-- next, create a ImageType if one doesn't exist yet. Here we'll create a jpeg:

insert into ImageType (extension, mime_type) values ('jpg', 'image/jpeg');

/*
 * Finally, define which dimensions you'd like created for each SiteImage.
 * For this example, we'll create 2 dimensions, a square-cropped thumbnail,
 * and a large image that fits within a 500px x 700px bounding box:
 */

insert into ImageDimension
(image_set, default_type, shortname, title, max_width, max_height, crop, dpi, quality, strip, interlace)
values (1, 1, 'thumbnail', 'Thumbnail', 100, 100, true, 72, 80, true, false);

insert into ImageDimension
(image_set, default_type, shortname, title, max_width, max_height, crop, dpi, quality, strip, interlace)
values
(1, 1, 'large', 'Zoomed In', 500, 700, false, 72, 80, false, true);

Filesystem

SiteImage stores the images in a hierarchical directory structure. The basic directory structure is images/ $image_set_shortname / $image_dimension_shortname. Directories are created automatically by SiteImage it they do not already exist. For our example, the following directories will be created:

• www/images/products
• www/images/products/thumbnail
• www/images/products/large

Note: the default base directory is images, but this can be changed by sub-classing SiteImage and overriding the getUriBase() method.

SiteImage Dataobject Usage

The following example demonstrates how to save an image directly from a file-input form submission:

<?php

class ImageSubClass extends Image
{
   protected function init()
   {
      $this->image_set_shortname = 'products';
   }
}

$image = new ImageSubClass();
$image->setDatabase($db);
$image->setFileBase('../images');
$image->title = 'My Product'; // optional
$image->process($_FILES['input_name']['tmp_name']);
// note that the dataobject is automatically saved in the process method

?>

The following demonstrates some of the information about the image that is available:

<?php

echo $image->getMimeType('large');
// image/jpeg

printf(
  'Large image dimensions are %d x %d',
  $image->getWidth('large'),
  $image->getHeight('large')
);
// Large image dimensions are 500 x 480

echo $image->getUri('large');
// images/products/large/filename.jpg

echo $image->getFilePath('large');
// ../images/products/large/filename.jpg

echo $image->getImgTag('large');
// <img src="images/products/large/filename.jpg" width="500" height="480"
//  alt="Image of My Product" title="My Product" />

// getImgTag() actually returns a SwatHtmlTag which can be manipulated to add
// extra tag attributes
$tag = $image->getImgTag('large');
$tag->class = 'product-image';
$tag->display();
// <img src="images/products/large/filename.jpg" width="500" height="480"
//  alt="Image of My Product" title="My Product" class="product-image" />

?>