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 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 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 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 String @NotNull ... values)
        Parameters:
        values - File extensions
        Returns:
        this

      • fileExtension

        @NotNull
@NotNull MediaBuilder fileExtension​(@NotNull
                                    @NotNull String value)
        Parameters:
        value - File extension
        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 String value)
        Allows to specify a custom alternative text that is to be used instead of the one defined in the the media lib item
        Parameters:
        value - Custom alternative text. If null or empty, the default alt text from media library is used.
        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 String value)
        Parameters:
        value - Url of custom dummy image. If null default dummy image is used.
        Returns:
        this

      • includeAssetThumbnails

        @NotNull
@NotNull MediaBuilder includeAssetThumbnails​(boolean value)
        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
@NotNull MediaBuilder includeAssetWebRenditions​(boolean value)
        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 String key,
                               @Nullable
                               @Nullable 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 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 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

      • pictureSource

        @Deprecated
@NotNull
@NotNull MediaBuilder pictureSource​(@NotNull
                                    @NotNull MediaFormat mediaFormat,
                                    @NotNull
                                    @NotNull String media,
                                    long @NotNull ... widths)
        Deprecated.
        Use pictureSource(io.wcm.handler.media.MediaArgs.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:
        mediaFormat - Media format with ratio for the renditions of the source element
        media - A valid media query list
        widths - Widths for the renditions in the srcset attribute. All renditions will use the ratio of the given media format.
        Returns:
        this

      • pictureSource

        @Deprecated
@NotNull
@NotNull MediaBuilder pictureSource​(@NotNull
                                    @NotNull MediaFormat mediaFormat,
                                    long @NotNull ... widths)
        Deprecated.
        Use pictureSource(io.wcm.handler.media.MediaArgs.PictureSource)
        Apply responsive image handling using picture and source elements. This will add one source element without an media attribute, and a srcset attribute with renditions for each width given based on the given media format.
        Parameters:
        mediaFormat - Media format with ratio for the renditions of the source element
        widths - Widths for the renditions in the srcset attribute. All renditions will use the ratio of the given media format.
        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

      • refProperty

        @NotNull
@NotNull MediaBuilder refProperty​(@NotNull
                                  @NotNull 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 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 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 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

        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

        String buildUrl()
        Resolve media and get URL to reference it directly.
        Returns:
        URL pointing to media object or null if resolving was not successful.