Package org.opencms.jsp.util

Class CmsJspImageBean

java.lang.Object
org.opencms.jsp.util.CmsJspImageBean
public class CmsJspImageBean extends Object
Bean containing image information for the use in JSP (for example formatters).

  • Field Details

    • MIN_DIMENSION

      public static int MIN_DIMENSION
      The minimum dimension (width and height) a generated image must have.

  • Constructor Details

    • CmsJspImageBean

      public CmsJspImageBean(CmsObject cms, CmsResource imageRes, String scaleParams)
      Initializes a new image bean based on a VFS resource and optional scaler parameters.

      Parameters:
      cms - the current OpenCms user context
      imageRes - the VFS resource to read the image from
      scaleParams - optional scaler parameters to apply to the VFS resource

    • CmsJspImageBean

      public CmsJspImageBean(CmsObject cms, String imageUri) throws CmsException
      Initializes a new image bean based on a string pointing to a VFS resource that may contain appended scaling parameters.

      Parameters:
      cms - the current OpenCms user context
      imageUri - the URI to read the image from in the OpenCms VFS, may also contain appended scaling parameters
      Throws:
      CmsException - in case of problems reading the image from the VFS

    • CmsJspImageBean

      public CmsJspImageBean(CmsObject cms, String imageUri, CmsImageScaler initScaler) throws CmsException
      Initializes a new image bean based on a VFS input string and applies additional re-scaling.

      The input string is is used to read the images from the VFS. It can contain scaling parameters. The additional re-scaling is then applied to the image that has been read.

      Parameters:
      cms - the current uses OpenCms context
      imageUri - the URI to read the image from in the OpenCms VFS, may also contain scaling parameters
      initScaler - the additional re-scaling to apply to the image
      Throws:
      CmsException - in case of problems reading the image from the VFS

    • CmsJspImageBean

      protected CmsJspImageBean()
      Initializes a new empty image bean.

      All values must be set with setters later.

  • Method Details

    • createVariation

      protected static CmsImageScaler createVariation(int originalWidth, int originalHeight, CmsImageScaler baseScaler, int targetWidth, int targetHeight, int quality)
      Create a variation scaler fir this image.

      Parameters:
      originalWidth - the original image pixel width
      originalHeight - the original image pixel height
      baseScaler - the base scaler that may contain crop parameters
      targetWidth - the target image pixel width
      targetHeight - the target image pixel height
      quality - the compression quality factor to use for image generation
      Returns:
      the created variation scaler for this image

    • addHiDpiImage

      public void addHiDpiImage(String factor, CmsJspImageBean image)
      adds a CmsJspImageBean as hi-DPI variant to this image
      Parameters:
      factor - the variant multiplier, e.g. "2x" (the common retina multiplier)
      image - the image to be used for this variant

    • addSrcSetWidthVariants

      public void addSrcSetWidthVariants(int minWidth, int maxWidth)
      Adds a number of size variations to the source set.

      In case the screen size is not really known, it may be a good idea to add some variations for large images to make sure there are some common options in case the basic image is very large.

      Parameters:
      minWidth - the minimum image width to add size variations for
      maxWidth - the maximum width size variation to create

    • createHiDpiVariation

      public CmsJspImageBean createHiDpiVariation(String hiDpiStr)
      Creates a hi-DPI scaled version of the current image.

      Parameters:
      hiDpiStr - the hi-DPI variation to generate, for example "2.5x".

      Returns:
      a hi-DPI scaled version of the current image

    • createRatioVariation

      public CmsJspImageBean createRatioVariation(String ratioStr)
      Creates a ratio scaled version of the current image.

      Parameters:
      ratioStr - the rato variation to generate, for example "4-3" or "1-1".

      Returns:
      a ratio scaled version of the current image

    • createWidthVariation

      public CmsJspImageBean createWidthVariation(String widthStr)
      Creates a width scaled version of the current image.

      Parameters:
      widthStr - the with variation to generate, for example "1078" or "800".

      Returns:
      a width scaled version of the current image

    • getHeight

      public int getHeight()
      Returns the original pixel height of the image.

      Returns:
      the original pixel height of the image

    • getHiDpiImages

      @Deprecated public Map<String,CmsJspImageBean> getHiDpiImages()
      Deprecated.
      use getScaleHiDpi() instead
      Returns a lazy initialized Map that provides access to ratio scaled instances of this image bean.

      Returns:
      a lazy initialized Map that provides access to ratio scaled instances of this image bean

    • getImgSrc

      public String getImgSrc()
      Returns the basic source parameters for this image.

      In case the image was cropped or otherwise manipulated, the values are created for the manipulated version.

      The return form is "src='(srcUrl)' height='(h)' width='(w)'".

      Returns:
      the basic source parameters for this image

    • getQuality

      public int getQuality()
      Returns the compression quality factor used for image generation.

      Returns:
      the compression quality factor used for image generation

    • getRatio

      public String getRatio()
      Returns the image ratio.

      The ratio is in the form 'width-height', for example '4-3' or '16-9'. In case no ratio was set, the pixel dimensions of the image are returned.

      Returns:
      the image ratio

    • getRatioHeightPercentage

      public String getRatioHeightPercentage()
      Returns the image height percentage relative to the image width as a String.

      In case a ratio has been used to scale the image, the height percentage is calculated based on the ratio, not on the actual image pixel size. This is done to avoid rounding differences.

      Returns:
      the image height percentage relative to the image width

    • getResource

      public CmsJspResourceWrapper getResource()
      Returns the JSP access wrapped VFS resource for this image.

      Returns:
      the JSP access wrapped VFS resource for this image

    • getScaleHiDpi

      public Map<String,CmsJspImageBean> getScaleHiDpi()
      Returns a lazy initialized Map that provides access to hi-DPI scaled instances of this image bean.

      • key: the variant multiplier, e.g. "2x" (the common retina multiplier)
      • value: a CmsJspImageBean representing the hi-DPI variant
      Returns:
      a lazy initialized Map that provides access to hi-DPI scaled instances of this image bean

    • getScaler

      public CmsImageScaler getScaler()
      Returns the image scaler that is used for the scaled version of this image bean.

      Returns:
      the image scaler that is used for the scaled version of this image bean

    • getScaleRatio

      public Map<String,CmsJspImageBean> getScaleRatio()
      Returns a lazy initialized Map that provides access to ratio scaled instances of this image bean.

      Returns:
      a lazy initialized Map that provides access to ratio scaled instances of this image bean

    • getScaleWidth

      public Map<String,CmsJspImageBean> getScaleWidth()
      Returns a lazy initialized Map that provides access to width scaled instances of this image bean.

      Returns:
      a lazy initialized Map that provides access to width scaled instances of this image bean

    • getSrcSet

      public String getSrcSet()
      Generates a srcset attribute parameter list from all images added to this image bean.

      Returns:
      a srcset attribute parameter list from all images added to this image bean

    • getSrcSetEntry

      public String getSrcSetEntry()
      Generates a srcset attribute parameter for this image bean.

      Returns:
      a srcset attribute parameter for this image bean

    • getSrcSetMap

      public Map<Integer,CmsJspImageBean> getSrcSetMap()
      Returns the source set map.

      In case no source set entries have been added before, the map is not initialized and null is returned.

      Returns:
      the source set map

    • getSrcSetMaxImage

      public CmsJspImageBean getSrcSetMaxImage()
      Returns the largest image from the generated source set.

      In case the source set has not been initialized, it returns the instance itself.

      Returns:
      the largest image from the generated source set

    • getSrcSetMaxWidth

      public int getSrcSetMaxWidth()
      Returns the largest width value form the source set.

      In case no source set entries have been added before, the map is not initialized and 0 is returned.

      Returns:
      the largest width value form the source set

    • getSrcSets

      public CmsJspImageBean getSrcSets()
      Getter for setSrcSets(CmsJspImageBean) which returns this image bean.

      Exists to make sure setSrcSets(CmsJspImageBean) is available as property on a JSP.

      Returns:
      this image bean
      See Also:

    • getSrcUrl

      public String getSrcUrl()
      Returns the image URL that may be used in img or picture tags.

      Returns:
      the image URL

    • getVfsUri

      public String getVfsUri()
      Returns the URI of the image in the OpenCms VFS.

      Returns:
      the URI of the image in the OpenCms VFS

    • getWidth

      public int getWidth()
      Returns the original (unscaled) width of the image.

      Returns:
      the original (unscaled) width of the image

    • isImage

      public boolean isImage()
      Returns true if this image bean has been correctly initialized with an image VFS resource.

      Returns:
      true if this image bean has been correctly initialized with an image VFS resource

    • isScaled

      public boolean isScaled()
      Returns true if the image has been scaled or otherwise processed.

      Returns:
      true if the image has been scaled or otherwise processed

    • setQuality

      public void setQuality(int quality)
      Sets the compression quality factor to use for image generation.

      Parameters:
      quality - the compression quality factor to use for image generation

    • setSrcSetQuality

      public void setSrcSetQuality()
      Adjusts the quality settings for all image beans in the srcSet depending on the pixel count.

      The idea is to make sure large pixel images use a higher JPEG compression in order to reduce the size.

      The following quality settings are used depending on the image size:

      • larger then 1200 * 800: quality 75
      • larger then 1024 * 768: quality 80
      • otherwise: quality 85

    • setSrcSets

      public void setSrcSets(CmsJspImageBean imageBean)
      Adds another image bean instance to the source set map of this bean.

      Parameters:
      imageBean - the image bean to add

    • setVfsUri

      public void setVfsUri(String vfsUri)
      Sets the URI of the image in the OpenCms VFS.

      Parameters:
      vfsUri - the URI of the image in the OpenCms VFS to set

    • toString

      public String toString()
      Returns the image source URL as String representation.

      Overrides:
      toString in class Object
      Returns:
      the image source URL
      See Also:

    • calcRatioHeightPercentage

      protected String calcRatioHeightPercentage(double width, double height)
      Returns the ratio height percentage of an image based on width and height.

      Parameters:
      width - width to calculate percentage from
      height - height to calculate percentage from
      Returns:
      the ratio height percentage of an image based on width and height

    • createVariation

      protected CmsJspImageBean createVariation(CmsImageScaler targetScaler)
      Returns a variation of the current image scaled with the given scaler.

      It is always the original image which is used as a base, never a scaled version. So for example if the image has been cropped by the user, the cropping are is ignored.

      Parameters:
      targetScaler - contains the information about how to scale the image
      Returns:
      a variation of the current image scaled with the given scaler

    • getBaseScaler

      protected CmsImageScaler getBaseScaler()
      Sets the scaler that describes the basic adjustments (usually cropping) that have been set on the original image.

      Returns:
      the scaler that describes the basic adjustments (usually cropping) that have been set on the original image

    • getCmsObject

      protected CmsObject getCmsObject()
      Returns the current OpenCms user context.

      Returns:
      the current OpenCms user context

    • getOriginalScaler

      protected CmsImageScaler getOriginalScaler()
      Returns the image scaler that describes the original proportions of this image.

      Returns:
      the image scaler that describes the original proportions of this image

    • getSelf

      protected CmsJspImageBean getSelf()
      Returns this instance bean, required for the transformers.

      Returns:
      this instance bean

    • init

      protected void init(CmsObject cms, CmsResource imageRes, String scaleParams)
      Initializes this new image bean based on a VFS resource and optional scaler parameters.

      Parameters:
      cms - the current OpenCms user context
      imageRes - the VFS resource to read the image from
      scaleParams - optional scaler parameters to apply to the VFS resource

    • setBaseScaler

      protected void setBaseScaler(CmsImageScaler baseScaler)
      Returns the scaler that describes the basic adjustments (usually cropping) that have been set on the original image.

      Parameters:
      baseScaler - the scaler that describes the basic adjustments (usually cropping) that have been set on the original image

    • setCmsObject

      protected void setCmsObject(CmsObject cms)
      Sets the current OpenCms user context.

      Parameters:
      cms - the current OpenCms user context to set

    • setOriginalScaler

      protected void setOriginalScaler(CmsImageScaler originalScaler)
      Sets the scaler that describes the original proportions of this image.

      Parameters:
      originalScaler - the scaler that describes the original proportions of this image

    • setResource

      protected void setResource(CmsObject cms, CmsResource resource)
      Sets the CmsResource for this image.

      Parameters:
      cms - the current OpenCms user context, required for wrapping the resource
      resource - the VFS resource for this image

    • setScaler

      protected void setScaler(CmsImageScaler scaler)
      Sets the image scaler that was used to create this image.

      Parameters:
      scaler - the image scaler that was used to create this image.