Documentation 2.x and 3.x

We have moved! This is an old documentation of ImpressPages 3.x.
Check out our new v4.0 documentation.

Reflections (image cropping)

Reflections is a service that provides an easy interface to create image thumbnails or make other file transformations

This service is available since ImpressPages CMS 3.0

How it works

Since v3.0 ImpressPages CMS provides a flexible system to create thumbnails of images or other modifications to original files. That means you don't need to handle all those options by yourself. The only file you should be concerned about is the original, which ideally should be placed in the default Repository.

Each time when you need a modified version of the original image, you use this service to get it and needn't worry when and how to delete it. It is extremely useful for image related widgets. Each theme requires differently cropped images. Using this service you can easily provide any number of differently cropped images depending on theme needs. Each modified variation of the original file is called it's reflection.

To create a thumbnail use the following code:

<?php
$reflectionService = \Modules\administrator\repository\ReflectionService::instance();
$file = FILE_REPOSITORY_DIR.'example.jpg';
$newName = 'example.jpg'; // or null
$transform = new TransformObject(); // see below in documentation
$reflection = $reflectionService->getReflection($file, $newName, $transform);
?>
  • $file - existing file that will be used as a source to create a modified version (reflection)
  • $newNamedesired filename for the modified file. If this particular filename is not available, the system will add a number at the end. You can pass null to leave the the filename the same as the source
  • $transform - transformation object which will actually do the transformation. You set all cropping / resize options when creating this object. Please read below for more details
  • $reflection - path (string) to newly created file. Display it to the user

Don't ever manually delete reflection files. They will be deleted automatically when they are no longer used. 

Use this service only for files within FILE_REPOSITORY_DIR (default file/repository) directory, unless you have read the source and you know exactly what you are doing.

You don't need to cache or otherwise store the result. Reflection service does that for you. If you request the same transformation over again, you will get the same result at no cost.

Fit image example

<?php
$maxWidth = 100;
$maxHeight = 100;
$quality = null; //number 0 - 100 or null to use default quality level
$forced = TRUE; //if true and image is smaller it will be scaled up
$transform = new Transform\ImageFit($maxWidth, $maxHeight, $quality, $forced);

$reflectionService = \Modules\administrator\repository\ReflectionService::instance();
$file = FILE_REPOSITORY_DIR.'example.jpg';
$newName = 'example.jpg'; // or null
$reflection = $reflectionService->getReflection($file, $newName, $transform);

?>

In this example we are creating $transform object of type ImageFit. This transformation type downscales the image until it fits provided dimensions. Then this transformation object is passed as a parameter to a reflection service. The resulting $reflection variable contains a path to created new file.

Crop image example

<?php
$x1 = 0;
$y1 = 0;
$x2 = 100;
$y2 = 50;
$requiredWidth = 50;
$requiredHeight = 25
$quality = null; //number 0 - 100 or null to use default quality level
$transform = new \Modules\administrator\repository\Transform\ImageCrop(
    $x1,
    $y1,
    $x2,
    $y2,
    $requiredWidth,
    $requiredHeight,
    $quality
);

$reflectionService = \Modules\administrator\repository\ReflectionService::instance();
$file = FILE_REPOSITORY_DIR.'example.jpg';
$newName = 'example.jpg'; // or null
$reflection = $reflectionService->getReflection($file, $newName, $transform);

?>

This example will crop 100 x 50 rectangle and scale it down to 50 x 25.

Custom transformation

You can create your own transformation type. To do so you need to extend \Modules\administrator\repository\Transform\Base class, and extend transform($sourceFile, $destinationFile) method. Both arguments are strings.

$sourceFile is an existing source relative to site BASE_DIR.

$destinationFile is the pathname of the modified file to be created, which is also relative to BASE_DIR

Easiest possible custom transformation (which does nothing) would be this:

<?php

namespace Modules\modulegroup\modulename\Transform;

class None extends \Modules\administrator\repository\Transform\Base
{
    public function transform($sourceFile, $destinationFile)
    {
        copy($sourceFile, $destinationFile);
    }

}

Modify this function to do something useful and you can use this class to create transformation object for getReflection method. Don't forget to change class name from None to something meaningful.

Write a comment

You must be logged in to comment.