Asset Configuration
General
The rendition builder is using a configuration set for the image transformation.
From the asset resource such a configuration set is searched traversing the repository tree upwards to find an asset configuration node with the relative path jcr:content/assetconfig and the node type cpa:AssetConfiguration.
Such a configuration resource declares all variations and their renditions. Each configuration resource (rendition / variation / configuration root) can define some configuration properties. The properties observe inheritance: each defined property hides the same property in a parent configuration node, if there is one. The rendition builder combines the properties to a complete configuration set and creates the appropriate rendition image on demand.
Image Configuration
It is possible to override some properties of the assetConfig for a single image via an imageConfig node with primaryType cpa:ImageConfiguration. There you can create notes named like the nodes in the assetConfig and override selected properties.
Example (in the prototype content)
/content/prototype/composum/assets/site-3/images/image-03.jpg
Overlays the property crop.vertical for the wide variation to ensure that the visible detail looks good for this image.
Assets-related primary types in the JCR
- cpa:Asset: marks an JCR-node as containing information about one asset
- cpa:AssetContent: subnode jcr:content of an asset. Versionable.
- cpa:AssetConfiguration: a set of configurations for one asset - can be a subnode of cpa:AssetContent or a subnode of a jcr:content node of any folder containing assets, in which case they inherit the configuration specified here. The jcr:node containing the AssetConfiguration must be versionable (which it is automatically if it's an cpa:AssetContent).
- cpa:VariationConfig: contains the configuration specific to one variation of an asset (e.g. special settings for a certain aspect ratio used in specific content components like a carousel)
- cpa:RenditionConfig: configuration for a rendition of variation (e.g. various sizes of the same image, from which the browser chooses the one appropriate to the screen size). A special rendition called
originalis the basis for the automatic rendering of the other renditions, possibly also other variations. - cpa:MetaData: contains the metadata (author, copyright / licence, origin, modification time, ...) for an asset. Subnode of cpa:AssetContent and on the nt:file+cpa:AssetResource of an uploaded original.
- cpa:Variation: node that contains the renditions for a variation specified in a cpa:VariationConfig. These nodes are named like the corresponding cpa:VariationConfig.
- cpa:Rendition: node that contains the images for a variation specified in a cpa:RenditionConfig. These nodes are named like the corresponding cpa:RenditionConfig.
- cpa:AssetResource: mixin for the
nt:filein an uploaded original-rendition that contains the image. Allows specifying metadata for the file and is versionable.
Example asset configuration
In this illustration all images are using the configuration declared in the folders content node folder/jcr:content/assetconfig. But the image another-image.jpg itself has an additional image configuration resource which has the same structure as an asset configuration resource and overlays the properties from the asset configuration for this image.
Properties in an Asset Configuration
Please notice that all transformations for images are executed in the following order:
- Resizing / Cropping
- Blurring
- Adding of a watermark
|
file |
.jpg |
.quality |
optional; default: 82.5 |
the quality of the image file in percent (0..100) or as float value (0.0..1.0) |
|---|
|
size |
.width |
optional; image original used if not present or calculated |
the designated image width in pixels, calculated using height and aspect ratio (given or from image) if not present |
|---|---|---|---|
|
.height |
the designated image height in pixels, calculated using width and aspect ratio (given or from image) if not present |
||
|
.aspectRatio |
the designated aspect ratio for the rendition as value 1.5 (3:2) or proportion like '16:9' |
The size of a rendition can be specified according to the design. The goal is to used one high quality image and build renditions from this image optimized for the designated design.
A rendition is cropped automatically if the aspect ratio of the original and the renditions differs. By default the the crop rectangle is centered horizontally and vertically. This rectangle can be placed by the configuration. It's also possible the determine the scaling which is combined with the cropping. By default the whole image is used and scaled to fill out the rectangle (scale: '1.0').
|
crop |
.horizontal |
optional; default: 0.5 |
the weight (0.0..1.0)to place the cropping rectangle horizontally |
|---|---|---|---|
|
.vertical |
optional; default: 0.5 |
the weight (0.0..1.0) to place the cropping rectangle vertically |
|
|
.scale |
optional; default: 1.0 |
the scale factor 0.0..1.00.0: no scaling a cropped rectangle without scaling is produced1.0: fill out the rectangle with the whole image |
Additional transformations are also possible (planned).
|
transformation |
.blur |
.factor |
optional |
the loop count (1..) for the blurring algorithm or default which means: do it and use 9 |
|---|
If a watermark text is defined and not blank this text will be written over the image. You can specify the text parameters and the placement of this watermark.
|
watermark |
.text |
the text to write over (necessary and not empty if watermark should be written) |
|
|---|---|---|---|
|
..font |
.family |
optional; default: 'sans-serif' |
the name of the font family (Java VM declared fonts are used) |
|
.bold |
optional |
if 'true' the bold style of the font is used |
|
|
.italic |
optional |
if 'true' the italic style of the font is used |
|
|
.size |
optional; default: 18 |
the font size (value only) in points |
|
|
.horizontal |
optional; default: 0.5 |
the weight (0.0..1.0)to place the watermark text horizontally |
|
|
.vertical |
optional; default: 0.5 |
the weight (0.0..1.0)to place the watermark text vertically |
|
|
.color |
optional; default: ffffff |
the text color |
|
|
.alpha |
optional; default: 0.25 |
the opacity value |
Nested Configuration
Replacement of an asset configuration
You can replace the current asset configuration in a subfolder by creating there another asset configuration. Only the properties of this configuration are used for image rendering of the containing images.
Example (in the prototype content)
/content/prototype/composum/assets/site-3/images/special
defines a new configuration and hides /content/prototype/composum/assets/site-3
Extension of an asset configuration
You can extend an asset configuration in a subfolder by creating there another asset configuration with property extension=true. For all the images in the subfolder this configuration is merged with the configuration for folders above.
Example (in the prototype content)
/content/prototype/composum/assets/site-3/extended
overlays the general rules of /content/prototype/composum/assets/site-3
adds an additional variation 'extrahigh'
