ImageManipulation
trait ImageManipulation (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
| static private bool | $force_resample | Force all images to resample in all cases Off by default, as this can be resource intensive to apply to multiple images simultaneously. |
|
| static private int | $strip_thumbnail_width | ||
| static private int | $strip_thumbnail_height | ||
| static private int | $cms_thumbnail_width | The width of an image thumbnail in the CMS. |
|
| static private int | $cms_thumbnail_height | The height of an image thumbnail in the CMS. |
|
| static private int | $asset_preview_width | The width of an image preview in the Asset section |
|
| static private int | $asset_preview_height | The height of an image preview in the Asset section |
Methods
Add a HTML attribute when rendering this object. This method is immutable, it will return you a copy of the original object.
Allows customization through an 'updateAttributes' hook on the base class.
Custom attributes to process. Falls back to {@link getAttributes()}.
Set whether image resizes are allowed
Check if resizes are allowed
Return clone of self which promises to only return existing thumbnails
No description
No description
No description
No description
Get metadata for this file
Get mime type
Return file size in bytes.
Determine if this container has a valid value
Get value of filename
Get value of hash
Get value of variant
Determine if a valid non-empty image exists behind this asset
Fit image to specified dimensions and fill leftover space with a solid colour (default white). Use in templates with $Pad.
Forces the image to be resampled, if possible
Update the url to point to a resampled version if forcing
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.
Set the quality of the resampled image
Default CMS thumbnail
Generates a thumbnail for use in the gridfield view
Get preview for this file
Default thumbnail generation for Images
Thubnail generation for all file types.
Get HTML for img containing the icon for this file
Get URL to thumbnail of the given size.
Return the relative URL of an icon for the file type, based on the {@link appCategory()} value.
Get Image_Backend instance for this image
Get the width of this image.
Get the height of this image.
Get the orientation of this image.
Determine if this image is of the specified size
Determine if this image is of the specified width
Determine if this image is of the specified width
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
Reverses {@link variantName()}.
Determine whether the image should be lazy loaded
Set the lazy loading state for this Image
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
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 {@link 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()
abstract resource
getStream()
abstract string
getURL(bool $grant = true)
abstract string
getAbsoluteURL()
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
string
getIcon()
Return the relative URL of an icon for the file type, based on the {@link 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)
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
manipulateImage(string $variant, callable $callback)
Wrapper for manipulate that passes in and stores Image_Backend objects instead of tuples
DBFile
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 {@link 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 {@link Image} class as the "main" user of this trait. This class is commonly decorated with additional manipulation methods through {@link DataExtension}.
bool
IsLazyLoaded()
Determine whether the image should be lazy loaded
AssetContainer
LazyLoad(mixed $lazyLoad)
Set the lazy loading state for this Image