Package io.wcm.handler.media

Interface MediaBuilder

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

  • Method Details

    • 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)
      Enable or disable auto-cropping mode.
      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)
      Set accepted file extensions.
      Parameters:
      values - Accepted file extensions
      Returns:
      this

    • fileExtension

      @NotNull @NotNull MediaBuilder fileExtension(@NotNull @NotNull String value)
      Set accepted file extension.
      Parameters:
      value - Accpeted file extension
      Returns:
      this

    • enforceOutputFileExtension

      @NotNull @NotNull MediaBuilder enforceOutputFileExtension(@NotNull @NotNull 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)
      Set URL mode.
      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)
      Set whether Content-Disposition header should be set to attachment.
      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 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)
      Set whether to force alt text from DAM asset description.
      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)
      Set whether image is decorative.
      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)
      Set whether dummy image is enabled.
      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)
      Set URL of custom dummy image.
      Parameters:
      value - Url of custom dummy image. If null default dummy image is used.
      Returns:
      this

    • imageQualityPercentage

      @NotNull @NotNull MediaBuilder imageQualityPercentage(@NotNull @NotNull Double value)
      Set image quality percentage.
      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 Set<AemRenditionType> value)
      Set which types of AEM-generated renditions are included.
      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 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

    • download

      @NotNull @NotNull MediaBuilder download(boolean value)
      Set whether to accept only download media formats.
      Parameters:
      value - Accept only media formats that have the download flag set.
      Returns:
      this

    • videoManifestFormat

      @NotNull @NotNull MediaBuilder videoManifestFormat(@Nullable @Nullable String value)
      Set the preferred video manifest format.
      Parameters:
      value - Preferred video manifest 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

    • 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

    • hostedVideoPlayer

      @NotNull @NotNull MediaBuilder hostedVideoPlayer(boolean value)
      Use hosted video player.
      Parameters:
      value - Whether to use Adobe's hosted video player instead of a streaming manifest, affecting both URL generation and markup (iframe vs. HTML5 video element).
      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.