ImageManipulation
trait ImageManipulation mixin AssetContainer (View source)
Provides image manipulation functionality.
Provides limited thumbnail generation functionality for non-image files. Should only be applied to implementors of AssetContainer
Allows raw images to be resampled via Resampled()
Image scaling manipluations, including:
- Fit()
- FitMax()
- ScaleWidth()
- ScaleMaxWidth()
- ScaleHeight()
- ScaleMaxHeight()
- ResizedImage()
Image cropping manipulations, including:
- CropHeight()
- CropWidth()
- Fill()
- FillMax()
Thumbnail generation methods including:
- Icon()
- CMSThumbnail()
Other manipulations that do not create variants:
- LazyLoad()
Traits
This trait can be applied to a ViewableData class to add the logic to render attributes in an SS template.
Properties
| protected | array | $attributes | List of attributes to render on the frontend |
from AttributesHTML |
| protected | Image_Backend | $imageBackend | ||
| protected | bool | $allowGeneration | If image resizes are allowed |
Methods
Add a HTML attribute when rendering this object. This method is immutable, it will return you a copy of the original object.
Retrieve the value of an HTML attribute
Allows customization through an 'updateAttributes' hook on the base class.
Custom attributes to process. Falls back to getAttributes().
Fit image to specified dimensions and fill leftover space with a solid colour (default white). Use in templates with $Pad.
Generate a resized copy of this image with the given width & height.
Scale image proportionally to fit within the specified bounds
Proportionally scale down this image if it is wider or taller than the specified dimensions.
Scale image proportionally by width. Use in templates with $ScaleWidth.
Proportionally scale down this image if it is wider than the specified width.
Scale image proportionally by height. Use in templates with $ScaleHeight.
Proportionally scale down this image if it is taller than the specified height.
Crop image on X axis if it exceeds specified width. Retain height.
Crop image on Y axis if it exceeds specified height. Retain width.
Crop this image to the aspect ratio defined by the specified width and height, then scale down the image to those dimensions if it exceeds them.
Resize and crop image to fill specified dimensions.
Generates a thumbnail for use in the gridfield view
Thubnail generation for all file types.
Convert the file to another format if there's a registered converter that can handle it.
Return the relative URL of an icon for the file type, based on the appCategory() value.
Wrapper for manipulate() that creates a variant file with a different extension than the original file.
Wrapper for manipulate that passes in and stores Image_Backend objects instead of tuples
Generate a new DBFile instance using the given callback if it hasn't been created yet, or return the existing one if it has.
Name a variant based on a format with arbitrary parameters
Validate a width or size is valid and casts it to integer
Details
AssetContainer
setAttribute(string $name, mixed $value)
Add a HTML attribute when rendering this object. This method is immutable, it will return you a copy of the original object.
mixed|null
getAttribute(string $name)
Retrieve the value of an HTML attribute
protected array
getDefaultAttributes()
No description
array
getAttributes()
Allows customization through an 'updateAttributes' hook on the base class.
Existing attributes are passed in as the first argument and can be manipulated, but any attributes added through a subclass implementation won't be included.
string
getAttributesHTML(array $attributes = null)
Custom attributes to process. Falls back to getAttributes().
If at least one argument is passed as a string, all arguments act as excludes, by name.
$this
setAllowGeneration(bool $allow)
Set whether image resizes are allowed
bool
getAllowGeneration()
Check if resizes are allowed
DBFile
existingOnly()
Return clone of self which promises to only return existing thumbnails
abstract string
getString()
No description
abstract resource
getStream()
No description
abstract string
getURL(bool $grant = true)
No description
abstract string
getAbsoluteURL()
No description
abstract array|null
getMetaData()
Get metadata for this file
abstract string
getMimeType()
Get mime type
abstract int
getAbsoluteSize()
Return file size in bytes.
abstract bool
exists()
Determine if this container has a valid value
abstract string
getFilename()
Get value of filename
abstract string
getHash()
Get value of hash
abstract string
getVariant()
Get value of variant
abstract bool
getIsImage()
Determine if a valid non-empty image exists behind this asset
AssetContainer
Pad(int $width, int $height, string $backgroundColor = 'FFFFFF', int $transparencyPercent = 0)
Fit image to specified dimensions and fill leftover space with a solid colour (default white). Use in templates with $Pad.
AssetContainer
Resampled()
Forces the image to be resampled, if possible
updateURL(string $url)
Update the url to point to a resampled version if forcing
AssetContainer
ResizedImage(int $width, int $height)
Generate a resized copy of this image with the given width & height.
This can be used in templates with $ResizedImage but should be avoided, as it's the only image manipulation function which can skew an image.
AssetContainer
Fit(int $width, int $height)
Scale image proportionally to fit within the specified bounds
AssetContainer
FitMax(int $width, int $height)
Proportionally scale down this image if it is wider or taller than the specified dimensions.
Similar to Fit but without up-sampling. Use in templates with $FitMax.
AssetContainer
ScaleWidth(int $width)
Scale image proportionally by width. Use in templates with $ScaleWidth.
AssetContainer
ScaleMaxWidth(int $width)
Proportionally scale down this image if it is wider than the specified width.
Similar to ScaleWidth but without up-sampling. Use in templates with $ScaleMaxWidth.
AssetContainer
ScaleHeight(int $height)
Scale image proportionally by height. Use in templates with $ScaleHeight.
AssetContainer
ScaleMaxHeight(int $height)
Proportionally scale down this image if it is taller than the specified height.
Similar to ScaleHeight but without up-sampling. Use in templates with $ScaleMaxHeight.
AssetContainer
CropWidth(int $width)
Crop image on X axis if it exceeds specified width. Retain height.
Use in templates with $CropWidth. Example: $Image.ScaleHeight(100).$CropWidth(100)
AssetContainer
CropHeight(int $height)
Crop image on Y axis if it exceeds specified height. Retain width.
Use in templates with $CropHeight. Example: $Image.ScaleWidth(100).CropHeight(100)
AssetContainer
FillMax(int $width, int $height)
Crop this image to the aspect ratio defined by the specified width and height, then scale down the image to those dimensions if it exceeds them.
Similar to Fill but without up-sampling. Use in templates with $FillMax.
AssetContainer
Fill(int $width, int $height)
Resize and crop image to fill specified dimensions.
Use in templates with $Fill
AssetContainer
Quality(int $quality)
Set the quality of the resampled image
DBFile|DBHTMLText
CMSThumbnail()
Default CMS thumbnail
AssetContainer|DBHTMLText
StripThumbnail()
Generates a thumbnail for use in the gridfield view
AssetContainer|DBHTMLText
PreviewThumbnail()
Get preview for this file
AssetContainer
Thumbnail(int $width, int $height)
Default thumbnail generation for Images
AssetContainer|DBHTMLText
ThumbnailIcon(int $width, int $height)
Thubnail generation for all file types.
Resizes images, but returns an icon <img /> tag if this is not a resizable image
DBHTMLText
IconTag()
Get HTML for img containing the icon for this file
string
ThumbnailURL(int $width, int $height)
Get URL to thumbnail of the given size.
May fallback to default icon
AssetContainer|null
Convert(string $toExtension)
Convert the file to another format if there's a registered converter that can handle it.
string
getIcon()
Return the relative URL of an icon for the file type, based on the appCategory() value.
Images are searched for in "framework/images/app_icons/".
Image_Backend
getImageBackend()
Get Image_Backend instance for this image
$this
setImageBackend(Image_Backend $backend)
No description
int
getWidth()
Get the width of this image.
int
getHeight()
Get the height of this image.
int
getOrientation()
Get the orientation of this image.
bool
isSize(int $width, int $height)
Determine if this image is of the specified size
bool
isWidth(int $width)
Determine if this image is of the specified width
bool
isHeight(int $height)
Determine if this image is of the specified width
DBFile|null
manipulateExtension(string $newExtension, callable $callback)
Wrapper for manipulate() that creates a variant file with a different extension than the original file.
DBFile|null
manipulateImage(string $variant, callable $callback)
Wrapper for manipulate that passes in and stores Image_Backend objects instead of tuples
DBFile|null
manipulate(string $variant, callable $callback)
Generate a new DBFile instance using the given callback if it hasn't been created yet, or return the existing one if it has.
string
variantName(string $format, $arg = null)
Name a variant based on a format with arbitrary parameters
array|null
variantParts($variantName)
Reverses variantName().
The "format" part of a variant name is a method name on the owner of this trait. For legacy reasons, there's no delimiter between this part, and the encoded arguments. This means we have to use a whitelist of "known formats", based on methods available on the Image class as the "main" user of this trait. The one exception to this is the variant for swapping file extensions, which is explicitly allowed. This class is commonly decorated with additional manipulation methods through DataExtension.
protected int
castDimension(mixed $value, string $dimension)
Validate a width or size is valid and casts it to integer
bool
IsLazyLoaded()
Determine whether the image should be lazy loaded
AssetContainer
LazyLoad(mixed $lazyLoad)
Set the lazy loading state for this Image