Copyright© 2008-2023 Sitevision AB, all rights reserved.
@Requireable(value="ImageRenderer") public interface ImageRenderer
ImageRenderer is very suitable when rendering more than one image or when you want to render images in different sizes than the original images (e.g. "thumbnails"). ImageRenderer also supports "hover" images, i.e. another image is displayed whenever the cursor hovers over the image.
ImageRenderer has few attributes:
null
.
null
.
null
. (though, the element class is always
'sv-noborder', which is equivalent with style 'border:none')
null
.
true
and there are no description set, the renderer will try to get the description metadata for the image. Default is false
.
description
will be used as value.
Default is false
.
true
and there are no description available, the renderer will try to get the description metadata for the image.
Default is false
.
true
.
srcset
attribute rendering strategy. Default is SourceSetMode.AUTO
.
ImageScaler
used to create new images in other sizes than the
original ones. Default is null
.
true
.
false
.
width/height
css style properties rendering strategy. Default is DimensionMode.AUTO
.
null
(no custom classes).
null
(no custom data attributes).
null
(no custom aria attributes).
Using the ImageRenderer is pretty straightforward, if you remember that it is stateful and that the previously loaded image will be cleared whenever you try to load a new one. Conceptually you would typically use it like this:
When you have rendered once, you can re-use the ImageRenderer until you are done. Something like:
Example of how this strategy could be implemented in Velocity:
(You want to do a simple listing of some image nodes in a collection/iterator "$images", and for each image a thumbnail should be displayed
on top of the original
## Get an ImageScaler that scales images to size 200x100
#set ($imageScaler = $sitevisionUtils.getImageScaler(200, 100))
## Get an ImageRenderer and apply the ImageScaler
#set ($imageRenderer = $sitevisionUtils.imageRenderer)
$imageRenderer.setImageScaler($imageScaler)
$imageRenderer.clearSourceSetMode() ## Disable source set (to ensure it won't interfere with the scaled size)
## Iterate through images and render them
<ul style="list-style:none">
#foreach ($image in $images)
## Load an image
$imageRenderer.update($image)
<li>
## Render the thumbnail (ensure scaler is active)
$imageRenderer.forceUseImageScaler()
$imageRenderer.render()
## Render image (ensure scaler is inactive)
$imageRenderer.clearUseImageScaler()
$imageRenderer.render()
</li>
#end
</ul>
Since ImageRenderer is stateful and likely will be used in Velocity frequently, there are some "shortcuts" that might be useful.
Due to the lack of proper boolean support in Velocity, the boolean attributes has corresponding force/clear methods to set the boolean
to true/false. Due to the lack of proper null support in Velocity, some attributes has clear methods to set the attribute to null
.
For example:
forceUseImageScaler()
results in an execution of setUseImageScaler(true)
clearUseImageScaler()
results in an execution of setUseImageScaler(false)
forceUseTitleRendering()
results in an execution of setUseTitleRendering(true)
clearUseTitleRendering()
results in an execution of setUseTitleRendering(false)
forceSourceSetMode()
results in an execution of setSourceSetMode(SourceSetMode.ON)
clearSourceSetMode()
results in an execution of setSourceSetMode(SourceSetMode.OFF)
clearHoverImage()
results in an execution of setHoverImage(null)
clearStyle()
results in an execution of setStyle(null)
forceUseLazyLoad()
results in an execution of setLazyLoad(true)
clearUseLazyLoad()
results in an execution of setLazyLoad(false)
Image type support! This interface accepts all types of images as specified by
MimeTypeUtil.isImageType(String)
.
This means that all such images can loaded and rendered, but note that not all types can be scaled by an ImageScaler
.
Thread Note! The render method is NOT thread safe! If two threads simultaneously executes
the render method on the SAME ImageRenderer instance, the rendered result is undeterminable. This is in almost
all cases nothing you need to worry about, unless your portlet or servlet actually creates a separate Thread
and starts it. If so - ensure all your created threads creates and uses their own ImageRenderer instance!
Note/Tip! This interface helps rendering images. If you want to render linked images, you would typically
use the ImageLinkRenderer
instead.
An instance of the Sitevision class implementing this interface can be obtained via Utils.getImageRenderer()
.
See Utils
for how to obtain an instance of the Utils
interface.
Modifier and Type | Method and Description |
---|---|
void |
addAriaAttribute(String aName,
String aValue)
Adds an aria-* attribute to the image element.
|
void |
addCssClass(String aClassName)
Adds a css class to the class attribute for the image element.
|
void |
addDataAttribute(String aName,
String aValue)
Adds an HTML5 data-* attribute to the image element.
|
void |
clearAriaAttributes()
Removes all existing aria attributes
|
void |
clearCssClasses()
Removes all existing css classes
|
void |
clearDataAttributes()
Removes all existing data attributes
|
void |
clearDescription()
Removes the description, i.e. executes
setDescription(null) |
void |
clearDimensionMode()
Utility method for executing
setDimensionMode( . |
void |
clearHoverImage()
Utility method for executing
setHoverImage(null) |
void |
clearImageScaler()
Removes the image scaler, i.e. executes
setImageScaler(null) |
void |
clearSourceSetMode()
Utility method for executing
setSourceSetMode( . |
void |
clearStyle()
Removes the style, i.e. executes
setStyle(null) |
void |
clearUseAutoDescription()
Utility method for executing
setUseAutoDescription(false) |
void |
clearUseAutoTitle()
Utility method for executing
setUseAutoTitle(false) |
void |
clearUseEncoding()
Utility method for executing
setUseEncoding(false) |
void |
clearUseImageScaler()
Utility method for executing
setUseImageScaler(false) |
void |
clearUseLazyLoad()
Utility method for executing
setLazyLoad(false) |
void |
clearUseTitleRendering()
Utility method for executing
setUseTitleRendering(false) |
void |
forceDimensionMode()
Utility method for executing
setDimensionMode( . |
void |
forceSourceSetMode()
Utility method for executing
setSourceSetMode( . |
void |
forceUseAutoDescription()
Utility method for executing
setUseAutoDescription(true) |
void |
forceUseAutoTitle()
Utility method for executing
setUseAutoTitle(true) |
void |
forceUseEncoding()
Utility method for executing
setUseEncoding(true) |
void |
forceUseImageScaler()
Utility method for executing
setUseImageScaler(true) |
void |
forceUseLazyLoad()
Utility method for executing
setLazyLoad(true) |
void |
forceUseTitleRendering()
Utility method for executing
setUseTitleRendering(true) |
boolean |
isHoverImageLoaded()
Whether or not a hover image is loaded.
|
boolean |
isImageLoaded()
Whether or not an image is loaded.
|
boolean |
isImageScalerLoaded()
Whether or not an image scaler is loaded.
|
String |
render()
Builds a html img element based on current state.
|
void |
resetDimensionMode()
Utility method for executing
setDimensionMode( . |
void |
resetSourceSetMode()
Utility method for executing
setSourceSetMode( . |
void |
setDescription(String aDescription)
Sets the image description (alt attribute on the img element).
|
void |
setDimensionMode(DimensionMode aDimensionMode)
The width/height rendering strategy.
|
void |
setHoverImage(Node anImageNode)
Sets a hover image that will be activated on the onmouseover javascript event.
|
void |
setImage(Node anImageNode)
Sets the image to be rendered.
|
void |
setImageScaler(ImageScaler anImageScaler)
Sets the image scaler that should be used by the renderer if
useImageScaler is true . |
void |
setLazyLoad(boolean aLazyLoad)
Sets whether or not the image should be lazy loaded (loaded when it appears in the browser's viewport).
|
void |
setSourceSetMode(SourceSetMode aSourceSetMode)
The
srcset attribute rendering strategy. |
void |
setStyle(String aStyle)
Sets the style (style attribute on the img element).
|
void |
setUseAutoDescription(boolean useAutoDescription)
A description fallback strategy that makes it possible to render a description value even if no description has been set.
|
void |
setUseAutoTitle(boolean useAutoTitle)
A title fallback strategy that makes it possible to render a title value even if no description is available.
|
void |
setUseEncoding(boolean performEncoding)
Sets whether or not descriptions should be encoded.
|
void |
setUseImageScaler(boolean useImageScaler)
Decides if an image scaler should be used or not.
|
void |
setUseTitleRendering(boolean useTitleRendering)
A title strategy that makes it possible to render a title attribute with the description as value.
|
void |
update(Node anImageNode)
Updates the renderer with a new image.
|
void |
update(Node anImageNode,
String aDescription)
Updates the renderer with a new image and a new description.
|
void setImageScaler(ImageScaler anImageScaler)
useImageScaler
is true
.
An image scaler is obtained via Utils.getImageScaler(int, int)
anImageScaler
- the image scaler that can be used by the renderer to create scaled imagesvoid clearImageScaler()
setImageScaler(null)
setImageScaler(ImageScaler)
boolean isImageScalerLoaded()
true
if an image scaler is loaded, false
if not.void setUseImageScaler(boolean useImageScaler)
Default is true
.
useImageScaler
- decides if an image scaler should be used or not.
If true
, an image scaler will be used if it is set. If false
, no image scaler will be used even if it is set.void forceUseImageScaler()
setUseImageScaler(true)
setUseImageScaler(boolean)
void clearUseImageScaler()
setUseImageScaler(false)
setUseImageScaler(boolean)
void setHoverImage(Node anImageNode)
anImageNode
- the hover image (a node with primary node type sv:image)void clearHoverImage()
setHoverImage(null)
setHoverImage(javax.jcr.Node)
boolean isHoverImageLoaded()
true
if a hover image node is loaded, false
if not.void setImage(Node anImageNode)
If anImageNode
is not a proper image, the image will be considered as null
, i.e.
the renderer will not have any image in subsequent render execution.
anImageNode
- the image (a node with primary node type sv:image)void update(Node anImageNode)
If anImageNode
is not a proper image, the image will be considered as null
, i.e.
the renderer will not have any image in subsequent render execution.
anImageNode
- the image (a node with primary node type sv:image)void update(Node anImageNode, String aDescription)
If anImageNode
is not a proper image, the image will be considered as null
, i.e.
the renderer will not have any image in subsequent render execution.
anImageNode
- the image (a node with primary node type sv:image)aDescription
- an image description, or null
to clear any previous descriptionboolean isImageLoaded()
true
if an image node is loaded, false
if not.void setUseAutoDescription(boolean useAutoDescription)
Default is false
.
useAutoDescription
- whether or not the renderer should try to get a description via metadata if no description is setvoid forceUseAutoDescription()
setUseAutoDescription(true)
setUseAutoDescription(boolean)
void clearUseAutoDescription()
setUseAutoDescription(false)
setUseAutoDescription(boolean)
void setSourceSetMode(SourceSetMode aSourceSetMode)
srcset
attribute rendering strategy.
Default is SourceSetMode.AUTO
.
aSourceSetMode
- the source set mode, determines whether or not a srcset
attribute should be renderedvoid forceSourceSetMode()
setSourceSetMode(SourceSetMode.ON
)
.setSourceSetMode(SourceSetMode)
void clearSourceSetMode()
setSourceSetMode(SourceSetMode.OFF
)
.setSourceSetMode(SourceSetMode)
void resetSourceSetMode()
setSourceSetMode(SourceSetMode.AUTO
)
.setSourceSetMode(SourceSetMode)
void setDimensionMode(DimensionMode aDimensionMode)
Default is DimensionMode.AUTO
.
aDimensionMode
- the dimension mode, determines how to render width/height css style propertiesvoid forceDimensionMode()
setDimensionMode(DimensionMode.ON
)
.void clearDimensionMode()
setDimensionMode(DimensionMode.OFF
)
.void resetDimensionMode()
setDimensionMode(DimensionMode.AUTO
)
.void setUseTitleRendering(boolean useTitleRendering)
Default is false
.
useTitleRendering
- whether or not a title attribute should be renderedsetUseAutoTitle(boolean)
void forceUseTitleRendering()
setUseTitleRendering(true)
setUseTitleRendering(boolean)
void clearUseTitleRendering()
setUseTitleRendering(false)
setUseTitleRendering(boolean)
void setUseAutoTitle(boolean useAutoTitle)
Default is false
.
Note!
This setting would typically be activated only if the title should be rendered (useTitleRendering
is true
) and the autoDescription is not activated (useAutoDescription
is false
).
Remember - the title value is always the description, so any other cases than previously stated won't actually add anything new
to your code/output...
useAutoTitle
- whether or not the renderer should try to get a description via metadata to use as title value if no description
is availablesetUseTitleRendering(boolean)
void forceUseAutoTitle()
setUseAutoTitle(true)
setUseAutoTitle(boolean)
void clearUseAutoTitle()
setUseAutoTitle(false)
setUseAutoTitle(boolean)
void setDescription(String aDescription)
null
) when the result is rendered, an empty alt attribute will be rendered
unless the useAutoDescription feature is active (see setUseAutoDescription(boolean)
).
Default is null
.
aDescription
- an alternative description of the imagevoid clearDescription()
setDescription(null)
setDescription(String)
void setStyle(String aStyle)
null
) when the result is rendered, no style attribute will be rendered
Default is border:none
.
aStyle
- the style of the rendered elementvoid clearStyle()
setStyle(null)
setStyle(String)
void setUseEncoding(boolean performEncoding)
Default is true
.
performEncoding
- whether descriptions should be encoded or not.void forceUseEncoding()
setUseEncoding(true)
setUseEncoding(boolean)
void clearUseEncoding()
setUseEncoding(false)
setUseEncoding(boolean)
void setLazyLoad(boolean aLazyLoad)
Note! Lazy loading depends on JavaScript being enabled.
Be sure to include an img
in a noscript
-tag for non JavaScript users.
Default is false
.
aLazyLoad
- whether the image should be lazy loaded.void forceUseLazyLoad()
setLazyLoad(true)
setLazyLoad(boolean)
void clearUseLazyLoad()
setLazyLoad(false)
setLazyLoad(boolean)
void addDataAttribute(String aName, String aValue)
There can only be one data attribute per name (i.e. when a data attribute is added it will always replace the possibly existing data attribute that already use that name).
Notes about names and values:
null
or whitespace-only will be completely ignored,
i.e. no data attribute will be rendered.
null
or whitespace-only will be rendered as a data attribute without value.
aName
- the name of the data attributeaValue
- the value of the data attributevoid clearDataAttributes()
void addAriaAttribute(String aName, String aValue)
There can only be one aria attribute per name (i.e. when an aria attribute is added it will always replace the possibly existing aria attribute that already use that name).
Notes about names and values:
null
or whitespace-only will be completely ignored,
i.e. no aria attribute will be rendered.
null
or whitespace-only will be rendered as an aria attribute without value.
aName
- the name of the aria attributeaValue
- the value of the aria attributevoid clearAriaAttributes()
void addCssClass(String aClassName)
Notes about css classes:
null
or whitespace-only will be completely ignored,
i.e. no css class will be added to the class attribute.
aClassName
- the name of the css classvoid clearCssClasses()
String render()
Note! The render method is not thread safe (see thread note above) and not all image types can be rendered when using an image scaler (see image support note above).
Sitevision - Portal and Content Management Made Easy
Sitevision is an advanced Java enterprise portal product and a portlet container (JSR 286) that implements Java Content Repository (JSR 283).
Copyright© 2008-2023 Sitevision AB, all rights reserved.