Package org.opencms.jsp.util

Class CmsJspImageBean

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

    • Field Detail

      • MIN_DIMENSION

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

    • Constructor Detail

      • CmsJspImageBean

        public CmsJspImageBean​(CmsObject cms,
                       CmsResource imageRes,
                       java.lang.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,
                       java.lang.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,
                       java.lang.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 Detail

      • 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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.util.Map<java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.util.Map<java.lang.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 java.util.Map<java.lang.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 java.util.Map<java.lang.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 java.lang.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 java.lang.String getSrcSetEntry()
        Generates a srcset attribute parameter for this image bean.

        Returns:
        a srcset attribute parameter for this image bean

      • getSrcSetMap

        public java.util.Map<java.lang.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

      • getSrcUrl

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

        Returns:
        the image URL

      • getVfsUri

        public java.lang.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​(java.lang.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 java.lang.String toString()
        Returns the image source URL as String representation.

        Overrides:
        toString in class java.lang.Object
        Returns:
        the image source URL
        See Also:
        getSrcUrl()

      • calcRatioHeightPercentage

        protected java.lang.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,
                    java.lang.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.