Repository & reflections

ImpressPages has a centralized repository for all files used by the system. Original files uploaded by user are stored in file/repository directory. You should never handle files in this directory manually. To add new files, use ipRepositoryAddFile() function. When added, they appear in a user interface and are available for use.

You can use ipBrowseFile() JavaScript function to open a repository browser. It shows all files in file/repository directory. This function is available only if a user is logged in as an administrator. Pass a callback function as a first parameter – this callback function is executed after a user has selected some files in repository browser window.

<script>
    function doSomething(files) {
        console.log(files);
    }
</script>
<a onclick="ipBrowseFile(doSomething);">Open repository</a>

ipBrowseFile() JavaScript function works only for users logged into administration panel.

Second parameter of ipBrowseFile() function accepts a list of options. All available options are shown in a table bellow:

Option name	Accepted values
preview	'list' or 'thumbnails'
filter	null or 'images'

<script>
    function doSomething(files) {
        console.log(files);
    }
</script>
<a href="#" onclick="ipBrowseFile(doSomething, {preview: 'thumbnails', filter: 'images'});">Open repository</a>

It is up to you how do you deal with a returned list of files. Usually, you have to execute AJAX to store them in a database. Use ipBindFile() function to instruct the system that your plugin is using a particular file. Then the repository will not allow to delete it. And don't forget to release unused files using ipUnbindFile() function.

No serious issues should happen if you don't use these functions, however, ImpressPages simply will not know that your plugin is using the file.

RepositoryFile form field

To upload a file to the repository using a form, you can use RepositoryFile field. Two requirements must be fulfilled: a user must be logged into the administration page and a form environment should be set to admin, as in the following example:

<?php
    $form = new \Ip\Form();
    $form->setEnvironment('admin');
    $field = new \Ip\Form\Field\RepositoryFile(array(
        'name' => 'myFile'
    ));
    $form->addField($field);
    $html = $form->render();
    echo $html;

Reflections

ipBrowseFile() function gives you original file name. But you likely need to have a smaller version of the image or its thumbnail. Reflections come to help here. Reflections are modified versions of original files. A common case is re-sized and cropped thumbnail images.

Use ipReflection() PHP function to get a modified version of an original file (the one that you got using ipBrowseFile() JavaScript function).

You don't have to worry about created reflections. You can create as much of them as you like. ImpressPages remembers all of them and removes every reflection when the original file is deleted.

ipReflection() function accepts these four parameters:

Type	Parameter	Comment
string	$file	A file name relative to /file/repository directory. Exactly the one you get using ipBrowseFile() in JavaScript.
array	$options	An image transformation options. Possible options: 'fit', 'crop', 'center' and 'copy'. Read bellow for more details.
string\|null	$desiredName = null	A desired filename of modified copy. A number will be added if desired name is already taken.
boolean	$onDemand = true	A transformation created on the fly when an image is accessed for the first time. If set to false, function forces creating the reflection.

The result is a path to the modified file relative to website's root. Use ipFileUrl() and ipFile() to get absolute URL or path.

By default ipReflection() function doesn't create a modified file immediately. The cropped file is being created at the first time when accessed in the browser. This is not true if you have rewritesDisabled set to true or realTimeReflections set to false in your config.php. In that case reflections are created immediately making image widgets sluggish.

Fit example

Scale down the image till it fits specified with and height. Image proportions are preserved.

$file = 'test.jpg'; //file existing in file/repository/ directory
$options = array(
    'type' => 'fit',
    'width' => 200,
    'height' => 200,    
    'quality' => 80, //optional, 0 - 100
    'forced' => false //optional. Smaller images will be scaled up if set to true
);
$thumbnail = ipReflection($file, $options);
if (!$thumbnail) {
    echo ipReflectionException();
} else {
    echo '<img src="' . ipFileUrl($thumbnail) . '" />';
}

Crop example

Crop out square area defined by two coordinates and scale it to width and height.

$file = 'test.jpg'; //file name in 'file/repository' dir.
$options = array(
    'type' => 'crop',
    'x1' => 10,
    'y1' => 10,
    'x2' => 50,
    'y2' => 50,
    'width' => 200,
    'height' => 200,
    'quality' => 80, //optional, 0 - 100
);
$thumbnail = ipReflection($file, $options);
if (!$thumbnail) {
    echo ipReflectionException();
} else {
    echo '<img src="' . ipFileUrl($thumbnail) . '" />';
}

Center example

Crop edges to reach required proportions, then scale to required proportions.

$file = 'test.jpg'; //file name in 'file/repository' dir.
$options = array(
    'type' => 'center',
    'width' => 100,
    'height' => 200,
    'quality' => 80, //optional, 0 - 100
);
$thumbnail = ipReflection($file, $options);
if (!$thumbnail) {
    echo ipReflectionException();
} else {
    echo '<img src="' . ipFileUrl($thumbnail) . '" />';
}

Width example (since 4.1.2)

            $file = 'test.jpg'; //file name in 'file/repository' dir.
            $options = array(
                'type' => 'width',
                'width' => 200
                'forced' => true //smaller images will be scaled up if set to true
            );
            $image = ipFileUrl(ipReflection($image, $options));

Copy example

The example below makes a copy of an image without transforming its size or quality.

$file = 'test.jpg'; //file name in 'file/repository' dir.
$options = array(
    'type' => 'copy',
);
$copiedImage = ipReflection($file, $options);
if (!$copiedImage) {
    echo ipReflectionException();
} else {
    echo '<img src="' . ipFileUrl($copiedImage) . '" />';
}

Custom cropping types

ipReflection() function throws ipCreateReflection job. You can write a plugin that catches this job and implements your custom cropping types or even transformations, e.g. from DOC to PDF, etc.

When coding custom reflection plugin in your development environment, it might be useful to set ipReflection() function's onDemand setting to false.