Package io.wcm.handler.media
Interface MediaBuilder
-
@ProviderType public interface MediaBuilder
Define media handling request using builder pattern.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description @NotNull MediaBuilder
altText(@NotNull java.lang.String value)
Allows to specify a custom alternative text that is to be used instead of the one defined in the the asset metadata.@NotNull MediaBuilder
args(@NotNull MediaArgs mediaArgs)
Sets additional arguments affection media resolving e.g.@NotNull MediaBuilder
autoCrop(boolean value)
@NotNull Media
build()
Resolve media and return metadata objects that contains all results.io.wcm.handler.commons.dom.HtmlElement
buildElement()
Resolve media and return directly the markup as DOM element generated by the media markup builder.java.lang.String
buildMarkup()
Resolve media and return directly the markup generated by the media markup builder.java.lang.String
buildUrl()
Resolve media and get URL to reference it directly.@NotNull MediaBuilder
contentDispositionAttachment(boolean value)
@NotNull MediaBuilder
cropProperty(@NotNull java.lang.String cropProperty)
Set the name of the property which contains the cropping parameters.@NotNull MediaBuilder
decorative(boolean value)
@NotNull MediaBuilder
dragDropSupport(@NotNull DragDropSupport value)
Drag&Drop support for media builder.@NotNull MediaBuilder
dummyImage(boolean value)
@NotNull MediaBuilder
dummyImageUrl(@NotNull java.lang.String value)
@NotNull MediaBuilder
dynamicMediaDisabled(boolean value)
Disable dynamic media support.@NotNull MediaBuilder
enforceOutputFileExtension(@NotNull java.lang.String value)
Enforces image file type for renditions.@NotNull MediaBuilder
fileExtension(@NotNull java.lang.String value)
@NotNull MediaBuilder
fileExtensions(@NotNull java.lang.String @NotNull ... values)
@NotNull MediaBuilder
fixedDimension(long widthValue, long heightValue)
Use fixed dimensions instead of width from media format or original image@NotNull MediaBuilder
fixedHeight(long value)
Use fixed height instead of width from media format or original image@NotNull MediaBuilder
fixedWidth(long value)
Use fixed width instead of width from media format or original image@NotNull MediaBuilder
forceAltValueFromAsset(boolean value)
@NotNull MediaBuilder
imageQualityPercentage(@NotNull java.lang.Double value)
@NotNull MediaBuilder
imageSizes(@NotNull java.lang.String sizes, long @NotNull ... widths)
Apply responsive image handling for theimg
element based on the primary media format given.@NotNull MediaBuilder
imageSizes(@NotNull java.lang.String sizes, @NotNull MediaArgs.WidthOption @NotNull ... widthOptions)
Apply responsive image handling for theimg
element based on the primary media format given.@NotNull MediaBuilder
includeAssetAemRenditions(@NotNull java.util.Set<AemRenditionType> value)
@NotNull MediaBuilder
includeAssetThumbnails(boolean value)
Deprecated.Please useincludeAssetAemRenditions(Set)
instead.@NotNull MediaBuilder
includeAssetWebRenditions(boolean value)
Deprecated.Please useincludeAssetAemRenditions(Set)
instead.@NotNull MediaBuilder
mandatoryMediaFormatNames(@NotNull java.lang.String @NotNull ... values)
Sets list of media formats to resolve to.@NotNull MediaBuilder
mandatoryMediaFormats(@NotNull MediaFormat @NotNull ... values)
Sets list of media formats to resolve to.@NotNull MediaBuilder
mapProperty(@NotNull java.lang.String mapProperty)
Set the name of the property which contains the image map data.@NotNull MediaBuilder
mediaFormat(@NotNull MediaFormat value)
Sets a single media format to resolve to.@NotNull MediaBuilder
mediaFormatName(@NotNull java.lang.String value)
Sets a single media format to resolve to.@NotNull MediaBuilder
mediaFormatNames(@NotNull java.lang.String @NotNull ... values)
Sets list of media formats to resolve to.@NotNull MediaBuilder
mediaFormatOptions(@NotNull MediaArgs.MediaFormatOption @NotNull ... values)
Sets list of media formats to resolve to.@NotNull MediaBuilder
mediaFormats(@NotNull MediaFormat @NotNull ... values)
Sets list of media formats to resolve to.@NotNull MediaBuilder
mediaFormatsMandatory(boolean value)
If set to true, media handler never returns a dummy image.@NotNull MediaBuilder
pictureSource(@NotNull MediaArgs.PictureSource pictureSource)
Apply responsive image handling usingpicture
andsource
elements.@NotNull MediaBuilder
property(@NotNull java.lang.String key, @Nullable java.lang.Object value)
Adds a custom property that my be used by application-specific markup builders or processors.@NotNull MediaBuilder
refProperty(@NotNull java.lang.String refProperty)
Sets the name of the property from which the media reference path is read, or node name for inline media.@NotNull MediaBuilder
rotationProperty(@NotNull java.lang.String rotationProperty)
Set the name of the property which contains the rotation parameter.@NotNull MediaBuilder
urlMode(@NotNull io.wcm.handler.url.UrlMode value)
@NotNull MediaBuilder
webOptimizedImageDeliveryDisabled(boolean value)
Disable web-optimized image delivery.
-
-
-
Method Detail
-
args
@NotNull @NotNull MediaBuilder args(@NotNull @NotNull MediaArgs mediaArgs)
Sets additional arguments affection media resolving e.g. media formats.- Parameters:
mediaArgs
- Media arguments- Returns:
- Media builder
-
mediaFormats
@NotNull @NotNull MediaBuilder mediaFormats(@NotNull @NotNull MediaFormat @NotNull ... values)
Sets list of media formats to resolve to.- Parameters:
values
- Media formats- Returns:
- this
-
mandatoryMediaFormats
@NotNull @NotNull MediaBuilder mandatoryMediaFormats(@NotNull @NotNull MediaFormat @NotNull ... values)
Sets list of media formats to resolve to. AdditionallymediaFormatsMandatory(boolean)
is set to true.- Parameters:
values
- Media formats- Returns:
- this
-
mediaFormat
@NotNull @NotNull MediaBuilder mediaFormat(@NotNull @NotNull MediaFormat value)
Sets a single media format to resolve to.- Parameters:
value
- Media format- Returns:
- this
-
mediaFormatsMandatory
@NotNull @NotNull MediaBuilder mediaFormatsMandatory(boolean value)
If set to true, media handler never returns a dummy image. Otherwise this can happen in edit mode.- Parameters:
value
- Resolving of all media formats is mandatory.- Returns:
- this
-
mediaFormatNames
@NotNull @NotNull MediaBuilder mediaFormatNames(@NotNull @NotNull java.lang.String @NotNull ... values)
Sets list of media formats to resolve to.- Parameters:
values
- Media format names.- Returns:
- this
-
mandatoryMediaFormatNames
@NotNull @NotNull MediaBuilder mandatoryMediaFormatNames(@NotNull @NotNull java.lang.String @NotNull ... values)
Sets list of media formats to resolve to. AdditionallymediaFormatsMandatory(boolean)
is set to true.- Parameters:
values
- Media format names.- Returns:
- this
-
mediaFormatName
@NotNull @NotNull MediaBuilder mediaFormatName(@NotNull @NotNull java.lang.String value)
Sets a single media format to resolve to.- Parameters:
value
- Media format name- Returns:
- this
-
mediaFormatOptions
@NotNull @NotNull MediaBuilder mediaFormatOptions(@NotNull @NotNull MediaArgs.MediaFormatOption @NotNull ... values)
Sets list of media formats to resolve to.- Parameters:
values
- Media formats- Returns:
- this
-
autoCrop
@NotNull @NotNull MediaBuilder autoCrop(boolean value)
- Parameters:
value
- Enables "auto-cropping" mode. If no matching rendition is found it is tried to generate one by automatically cropping another one.- Returns:
- this
-
fileExtensions
@NotNull @NotNull MediaBuilder fileExtensions(@NotNull @NotNull java.lang.String @NotNull ... values)
- Parameters:
values
- Accepted file extensions- Returns:
- this
-
fileExtension
@NotNull @NotNull MediaBuilder fileExtension(@NotNull @NotNull java.lang.String value)
- Parameters:
value
- Accpeted file extension- Returns:
- this
-
enforceOutputFileExtension
@NotNull @NotNull MediaBuilder enforceOutputFileExtension(@NotNull @NotNull java.lang.String value)
Enforces image file type for renditions.By default, renditions are rendered with the same file type as the original rendition (except if the original renditions uses a file type not directly supported in browser, e.g. a TIFF image). With this parameter, it is possible to enforce generating renditions with this file type.
Supported file types: JPEG, PNG
- Parameters:
value
- File extension to be used for returned renditions- Returns:
- this
-
urlMode
@NotNull @NotNull MediaBuilder urlMode(@NotNull @NotNull io.wcm.handler.url.UrlMode value)
- Parameters:
value
- URS mode- Returns:
- this
-
fixedWidth
@NotNull @NotNull MediaBuilder fixedWidth(long value)
Use fixed width instead of width from media format or original image- Parameters:
value
- Fixed width- Returns:
- this
-
fixedHeight
@NotNull @NotNull MediaBuilder fixedHeight(long value)
Use fixed height instead of width from media format or original image- Parameters:
value
- Fixed height- Returns:
- this
-
fixedDimension
@NotNull @NotNull MediaBuilder fixedDimension(long widthValue, long heightValue)
Use fixed dimensions instead of width from media format or original image- Parameters:
widthValue
- Fixed widthheightValue
- Fixed height- Returns:
- this
-
contentDispositionAttachment
@NotNull @NotNull MediaBuilder contentDispositionAttachment(boolean value)
- Parameters:
value
- Whether to set a "Content-Disposition" header to "attachment" for forcing a "Save as" dialog on the client- Returns:
- this
-
altText
@NotNull @NotNull MediaBuilder altText(@NotNull @NotNull java.lang.String value)
Allows to specify a custom alternative text that is to be used instead of the one defined in the the asset metadata.- Parameters:
value
- Custom alternative text. If null or empty, the default alt text from media library is used.- Returns:
- this
-
forceAltValueFromAsset
@NotNull @NotNull MediaBuilder forceAltValueFromAsset(boolean value)
- Parameters:
value
- Whether to force to read alt. text from DAM asset description. If not set, the asset description is used as fallback value of no custom alt. text is defined.- Returns:
- this
-
decorative
@NotNull @NotNull MediaBuilder decorative(boolean value)
- Parameters:
value
- Marks this image as "decorative". Alt. text is then explicitly set to an empty string.- Returns:
- this
-
dummyImage
@NotNull @NotNull MediaBuilder dummyImage(boolean value)
- Parameters:
value
- If set to false, media handler never returns a dummy image. Otherwise this can happen in edit mode.- Returns:
- this
-
dummyImageUrl
@NotNull @NotNull MediaBuilder dummyImageUrl(@NotNull @NotNull java.lang.String value)
- Parameters:
value
- Url of custom dummy image. If null default dummy image is used.- Returns:
- this
-
imageQualityPercentage
@NotNull @NotNull MediaBuilder imageQualityPercentage(@NotNull @NotNull java.lang.Double value)
- Parameters:
value
- Image quality in percent (0..1) for images with lossy compression (e.g. JPEG).- Returns:
- this
-
includeAssetAemRenditions
@NotNull @NotNull MediaBuilder includeAssetAemRenditions(@NotNull @NotNull java.util.Set<AemRenditionType> value)
- Parameters:
value
- Defines which types of AEM-generated renditions (withcq5dam.
prefix) are taken into account when trying to resolve the media request.- Returns:
- this
-
includeAssetThumbnails
@NotNull @Deprecated(since="2.0.0") @NotNull MediaBuilder includeAssetThumbnails(boolean value)
Deprecated.Please useincludeAssetAemRenditions(Set)
instead.- Parameters:
value
- If set to true, thumbnail generated by the DAM asset workflows (with cq5dam.thumbnail prefix) are taken into account as well when trying to resolve the media request.- Returns:
- Media builder
-
includeAssetWebRenditions
@NotNull @Deprecated(since="2.0.0") @NotNull MediaBuilder includeAssetWebRenditions(boolean value)
Deprecated.Please useincludeAssetAemRenditions(Set)
instead.- Parameters:
value
- If set to true, web renditions generated by the DAM asset workflows (with cq5dam.web prefix) are taken into account as well when trying to resolve the media request.- Returns:
- Media builder
-
dragDropSupport
@NotNull @NotNull MediaBuilder dragDropSupport(@NotNull @NotNull DragDropSupport value)
Drag&Drop support for media builder.- Parameters:
value
- Drag&Drop support- Returns:
- Media builder
-
property
@NotNull @NotNull MediaBuilder property(@NotNull @NotNull java.lang.String key, @Nullable @Nullable java.lang.Object value)
Adds a custom property that my be used by application-specific markup builders or processors.- Parameters:
key
- Property keyvalue
- Property value- Returns:
- Media builder
-
imageSizes
@NotNull @NotNull MediaBuilder imageSizes(@NotNull @NotNull java.lang.String sizes, long @NotNull ... widths)
Apply responsive image handling for theimg
element based on the primary media format given. If multiple media formats are given the primary media format is the first media format with a ratio.It will add a
srcset
attribute to theimg
element with renditions for each width given, and set thesizes
attribute to the sizes string given.- Parameters:
sizes
- A valid source size listwidths
- Widths for the renditions in thesrcset
attribute (all mandatory). All renditions will use the ratio of the primary media format.- Returns:
- this
-
imageSizes
@NotNull @NotNull MediaBuilder imageSizes(@NotNull @NotNull java.lang.String sizes, @NotNull @NotNull MediaArgs.WidthOption @NotNull ... widthOptions)
Apply responsive image handling for theimg
element based on the primary media format given. If multiple media formats are given the primary media format is the first media format with a ratio.It will add a
srcset
attribute to theimg
element with renditions for each width given, and set thesizes
attribute to the sizes string given.- Parameters:
sizes
- A valid source size listwidthOptions
- Widths for the renditions in thesrcset
attribute. All renditions will use the ratio of the primary media format.- Returns:
- this
-
pictureSource
@NotNull @NotNull MediaBuilder pictureSource(@NotNull @NotNull MediaArgs.PictureSource pictureSource)
Apply responsive image handling usingpicture
andsource
elements. This will add onesource
element with anmedia
attribute set to the given media string, and asrcset
attribute with renditions for each width given based on the given media format.- Parameters:
pictureSource
- Picture source element- Returns:
- this
-
dynamicMediaDisabled
@NotNull @NotNull MediaBuilder dynamicMediaDisabled(boolean value)
Disable dynamic media support.- Parameters:
value
- If set to true, dynamic media support is disabled even when enabled on the instance.- Returns:
- this
-
webOptimizedImageDeliveryDisabled
@NotNull @NotNull MediaBuilder webOptimizedImageDeliveryDisabled(boolean value)
Disable web-optimized image delivery.- Parameters:
value
- If set to true, web-optimized image delivery is disabled even when enabled on the instance.- Returns:
- this
-
refProperty
@NotNull @NotNull MediaBuilder refProperty(@NotNull @NotNull java.lang.String refProperty)
Sets the name of the property from which the media reference path is read, or node name for inline media.- Parameters:
refProperty
- Property or node name- Returns:
- Media builder
-
cropProperty
@NotNull @NotNull MediaBuilder cropProperty(@NotNull @NotNull java.lang.String cropProperty)
Set the name of the property which contains the cropping parameters.- Parameters:
cropProperty
- Property name- Returns:
- Media builder
-
rotationProperty
@NotNull @NotNull MediaBuilder rotationProperty(@NotNull @NotNull java.lang.String rotationProperty)
Set the name of the property which contains the rotation parameter.- Parameters:
rotationProperty
- Property name- Returns:
- Media builder
-
mapProperty
@NotNull @NotNull MediaBuilder mapProperty(@NotNull @NotNull java.lang.String mapProperty)
Set the name of the property which contains the image map data.- Parameters:
mapProperty
- Property name- Returns:
- Media builder
-
build
@NotNull @NotNull Media build()
Resolve media and return metadata objects that contains all results.- Returns:
- Media metadata object. Never null, if the resolving failed the isValid() method returns false.
-
buildMarkup
java.lang.String buildMarkup()
Resolve media and return directly the markup generated by the media markup builder.- Returns:
- HTML markup string (may by an img, div or any other element) or null if resolving was not successful.
-
buildElement
io.wcm.handler.commons.dom.HtmlElement buildElement()
Resolve media and return directly the markup as DOM element generated by the media markup builder.- Returns:
- HTML element (may by an img, div or any other element) or null if resolving was not successful.
-
buildUrl
java.lang.String buildUrl()
Resolve media and get URL to reference it directly.- Returns:
- URL pointing to media object or null if resolving was not successful.
-
-