Package io.wcm.handler.media

Interface MediaBuilder

  • @ProviderType
public interface MediaBuilder
    Define media handling request using builder pattern.

    • 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. Additionally mediaFormatsMandatory(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. Additionally mediaFormatsMandatory(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 width
        heightValue - 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 (with cq5dam. 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 use includeAssetAemRenditions(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 use includeAssetAemRenditions(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 key
        value - Property value
        Returns:
        Media builder

      • imageSizes

        @NotNull
@NotNull MediaBuilder imageSizes​(@NotNull
                                 @NotNull java.lang.String sizes,
                                 long @NotNull ... widths)
        Apply responsive image handling for the img 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 the img element with renditions for each width given, and set the sizes attribute to the sizes string given.

        Parameters:
        sizes - A valid source size list
        widths - Widths for the renditions in the srcset 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 the img 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 the img element with renditions for each width given, and set the sizes attribute to the sizes string given.

        Parameters:
        sizes - A valid source size list
        widthOptions - Widths for the renditions in the srcset 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 using picture and source elements. This will add one source element with an media attribute set to the given media string, and a srcset 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.