2015-06-13 01:42:51 +02:00
|
|
|
summary: Learn how to crop and resize images in templates and PHP code
|
|
|
|
|
|
|
|
# Image
|
|
|
|
|
2016-02-25 02:51:59 +01:00
|
|
|
Image files can be stored either through the `[api:Image]` dataobject, or though [api:DBFile] fields.
|
2015-09-15 04:52:02 +02:00
|
|
|
In either case, the same image resizing and manipulation functionality is available though the common
|
2016-02-25 02:51:59 +01:00
|
|
|
[api:ImageManipulation] trait.
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
### Managing images through form fields
|
|
|
|
|
2016-02-17 22:21:59 +01:00
|
|
|
Images can be uploaded like any other file, through [api:FileField].
|
2015-06-13 01:42:51 +02:00
|
|
|
Allows upload of images through limiting file extensions with `setAllowedExtensions()`.
|
|
|
|
|
|
|
|
### Inserting images into the WYSIWYG editor
|
|
|
|
|
2016-03-08 12:20:51 +01:00
|
|
|
Images can be inserted into `[api:HTMLValue]` database fields
|
|
|
|
through the built-in WYSIWYG editor. In order to retain a relationship
|
|
|
|
to the underlying `[api:Image]` records, images are saved as [shortcodes](/developer-guides/extending/shortcodes).
|
|
|
|
The shortcode (`[image id="<id>" alt="My text" ...]`) will be converted
|
|
|
|
into an `<img>` tag on your website automatically.
|
|
|
|
|
|
|
|
See [HTMLEditorField](/forms/field-types/htmleditorfield).
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
### Manipulating images in Templates
|
|
|
|
|
|
|
|
You can manipulate images directly from templates to create images that are
|
|
|
|
resized and cropped to suit your needs. This doesn't affect the original
|
|
|
|
image or clutter the CMS with any additional files, and any images you create
|
|
|
|
in this way are cached for later use. In most cases the pixel aspect ratios of
|
|
|
|
images are preserved (meaning images are not stretched).
|
|
|
|
|
|
|
|
![](../../_images/image-methods.jpg)
|
|
|
|
|
|
|
|
Here are some examples, assuming the `$Image` object has dimensions of 200x100px:
|
|
|
|
|
|
|
|
:::ss
|
|
|
|
// Scaling functions
|
|
|
|
$Image.ScaleWidth(150) // Returns a 150x75px image
|
|
|
|
$Image.ScaleMaxWidth(100) // Returns a 100x50px image (like ScaleWidth but prevents up-sampling)
|
|
|
|
$Image.ScaleHeight(150) // Returns a 300x150px image (up-sampled. Try to avoid doing this)
|
|
|
|
$Image.ScaleMaxHeight(150) // Returns a 200x100px image (like ScaleHeight but prevents up-sampling)
|
|
|
|
$Image.Fit(300,300) // Returns an image that fits within a 300x300px boundary, resulting in a 300x150px image (up-sampled)
|
|
|
|
$Image.FitMax(300,300) // Returns a 200x100px image (like Fit but prevents up-sampling)
|
|
|
|
|
2015-09-15 04:52:02 +02:00
|
|
|
// Warning: This method can distort images that are not the correct aspect ratio
|
|
|
|
$Image.ResizedImage(200, 300) // Forces dimensions of this image to the given values.
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
// Cropping functions
|
|
|
|
$Image.Fill(150,150) // Returns a 150x150px image resized and cropped to fill specified dimensions (up-sampled)
|
|
|
|
$Image.FillMax(150,150) // Returns a 100x100px image (like Fill but prevents up-sampling)
|
|
|
|
$Image.CropWidth(150) // Returns a 150x100px image (trims excess pixels off the x axis from the center)
|
|
|
|
$Image.CropHeight(50) // Returns a 200x50px image (trims excess pixels off the y axis from the center)
|
|
|
|
|
|
|
|
// Padding functions (add space around an image)
|
|
|
|
$Image.Pad(100,100) // Returns a 100x100px padded image, with white bars added at the top and bottom
|
|
|
|
$Image.Pad(100, 100, CCCCCC) // Same as above but with a grey background
|
|
|
|
|
|
|
|
// Metadata
|
|
|
|
$Image.Width // Returns width of image
|
|
|
|
$Image.Height // Returns height of image
|
|
|
|
$Image.Orientation // Returns Orientation
|
|
|
|
$Image.Title // Returns the friendly file name
|
|
|
|
$Image.Name // Returns the actual file name
|
|
|
|
$Image.FileName // Returns the actual file name including directory path from web root
|
|
|
|
$Image.Link // Returns relative URL path to image
|
|
|
|
$Image.AbsoluteLink // Returns absolute URL path to image
|
|
|
|
|
|
|
|
Image methods are chainable. Example:
|
|
|
|
|
|
|
|
:::ss
|
|
|
|
<body style="background-image:url($Image.ScaleWidth(800).CropHeight(800).Link)">
|
|
|
|
|
2015-02-11 09:26:49 +01:00
|
|
|
### Padded Image Resize
|
|
|
|
|
|
|
|
The Pad method allows you to resize an image with existing ratio and will
|
|
|
|
pad any surplus space. You can specify the color of the padding using a hex code such as FFFFFF or 000000.
|
|
|
|
|
|
|
|
You can also specify a level of transparency to apply to the padding color in a fourth param. This will only effect
|
|
|
|
png images.
|
|
|
|
|
|
|
|
:::php
|
|
|
|
$Image.Pad(80, 80, FFFFFF, 50) // white padding with 50% transparency
|
|
|
|
$Image.Pad(80, 80, FFFFFF, 100) // white padding with 100% transparency
|
|
|
|
$Image.Pad(80, 80, FFFFFF) // white padding with no transparency
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
### Manipulating images in PHP
|
|
|
|
|
|
|
|
The image manipulation functions can be used in your code with the same names, example: `$image->Fill(150,150)`.
|
|
|
|
|
|
|
|
Some of the MetaData functions need to be prefixed with 'get', example `getHeight()`, `getOrientation()` etc.
|
|
|
|
|
2016-02-25 02:51:59 +01:00
|
|
|
Please refer to the [api:ImageManipulation] API documentation for specific functions.
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
### Creating custom image functions
|
|
|
|
|
2015-09-15 04:52:02 +02:00
|
|
|
You can also create your own functions by decorating the `Image` class.
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
:::php
|
2017-06-22 18:39:33 +02:00
|
|
|
class ImageExtension extends \SilverStripe\Core\Extension
|
|
|
|
{
|
|
|
|
|
|
|
|
public function Square($width)
|
|
|
|
{
|
|
|
|
$variant = $this->owner->variantName(__FUNCTION__, $width);
|
|
|
|
return $this->owner->manipulateImage($variant, function (\SilverStripe\Assets\Image_Backend $backend) use($width) {
|
|
|
|
$clone = clone $backend;
|
|
|
|
$resource = clone $backend->getImageResource();
|
|
|
|
$resource->fit($width);
|
|
|
|
$clone->setImageResource($resource);
|
|
|
|
return $clone;
|
|
|
|
});
|
|
|
|
}
|
|
|
|
|
|
|
|
public function Blur($amount = null)
|
|
|
|
{
|
|
|
|
$variant = $this->owner->variantName(__FUNCTION__, $amount);
|
|
|
|
return $this->owner->manipulateImage($variant, function (\SilverStripe\Assets\Image_Backend $backend) use ($amount) {
|
|
|
|
$clone = clone $backend;
|
|
|
|
$resource = clone $backend->getImageResource();
|
|
|
|
$resource->blur($amount);
|
|
|
|
$clone->setImageResource($resource);
|
|
|
|
return $clone;
|
|
|
|
});
|
|
|
|
}
|
|
|
|
|
|
|
|
}
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
:::yml
|
2017-06-22 18:39:33 +02:00
|
|
|
SilverStripe\Assets\Image:
|
2015-06-13 01:42:51 +02:00
|
|
|
extensions:
|
2017-06-22 18:39:33 +02:00
|
|
|
- ImageExtension
|
2015-08-30 07:02:55 +02:00
|
|
|
SilverStripe\Filesystem\Storage\DBFile:
|
2015-09-15 04:52:02 +02:00
|
|
|
extensions:
|
2017-06-22 18:39:33 +02:00
|
|
|
- ImageExtension
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
### Form Upload
|
|
|
|
|
2016-02-17 22:21:59 +01:00
|
|
|
For usage on a website form, see [api:FileField].
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
### Image Quality
|
|
|
|
|
2017-06-28 23:40:18 +02:00
|
|
|
#### Source images
|
2015-06-13 01:42:51 +02:00
|
|
|
|
2017-06-28 23:40:18 +02:00
|
|
|
Whenever SilverStripe performs a manipulation on an image, it saves the output
|
|
|
|
as a new image file, and applies compression during the process. If the source
|
|
|
|
image already had lossy compression applied, this leads to the image being
|
|
|
|
compressed twice over which can produce a poor result. To ensure the best
|
|
|
|
quality output images, it's recommended to upload high quality source images
|
|
|
|
(minimal or no compression) in to your asset store, and let SilverStripe take
|
|
|
|
care of applying compression.
|
|
|
|
|
|
|
|
Very high resolution images may cause GD to crash (especially on shared hosting
|
|
|
|
environments where resources are limited) so a good size for website images is
|
|
|
|
around 2000px on the longest edge.
|
|
|
|
|
|
|
|
#### Forced resampling
|
2015-06-13 01:42:51 +02:00
|
|
|
|
2017-06-28 23:40:18 +02:00
|
|
|
Since the 'master' images in your asset store may have a large file size, by
|
|
|
|
default SilverStripe will always apply compression to your images to save
|
|
|
|
bandwidth - even if no other manipulation (such as a crop or resize) is taking
|
|
|
|
place. If you expect the images in your asset store to already have
|
|
|
|
compression applied and want to serve up the original when no resampling is
|
|
|
|
necessary, you can add this to your mysite/config/config.yml file:
|
2015-06-13 01:42:51 +02:00
|
|
|
|
|
|
|
:::yml
|
2015-09-15 04:52:02 +02:00
|
|
|
# Configure resampling for File dataobject
|
|
|
|
File:
|
2017-06-28 23:40:18 +02:00
|
|
|
force_resample: false
|
2015-09-15 04:52:02 +02:00
|
|
|
# DBFile can be configured independently
|
2015-08-30 07:02:55 +02:00
|
|
|
SilverStripe\Filesystem\Storage\DBFile:
|
2017-06-28 23:40:18 +02:00
|
|
|
force_resample: false
|
2015-06-13 01:42:51 +02:00
|
|
|
|
2017-06-28 23:40:18 +02:00
|
|
|
#### Resampled image quality
|
|
|
|
|
|
|
|
To adjust the quality of the generated images when they are resampled, add the
|
|
|
|
following to your mysite/config/config.yml file:
|
|
|
|
|
|
|
|
:::yml
|
|
|
|
SilverStripe\Core\Injector\Injector:
|
|
|
|
SilverStripe\Assets\InterventionBackend:
|
|
|
|
properties:
|
|
|
|
Quality: 90
|
2015-06-13 01:42:51 +02:00
|
|
|
|
2017-06-22 18:39:33 +02:00
|
|
|
## Changing the manipulation driver to Imagick
|
|
|
|
|
|
|
|
If you want to change the image manipulation driver to use Imagick instead of GD, you'll need to change your config so
|
|
|
|
that the `Intervention\Image\ImageManager` is instantiated with the `imagick` driver instead of GD:
|
|
|
|
|
|
|
|
```yml
|
|
|
|
SilverStripe\Core\Injector\Injector:
|
|
|
|
Intervention\Image\ImageManager:
|
|
|
|
constructor:
|
|
|
|
- { driver: imagick }
|
|
|
|
```
|
|
|
|
|
2015-06-13 01:42:51 +02:00
|
|
|
## API Documentation
|
2015-09-15 04:52:02 +02:00
|
|
|
|
2016-02-25 02:51:59 +01:00
|
|
|
* [api:File]
|
|
|
|
* [api:Image]
|
|
|
|
* [api:DBFile]
|
|
|
|
* [api:ImageManipulation]
|