Copyright© 2008-2022 Sitevision AB, all rights reserved.
@Requireable(value="LinkRenderer") public interface LinkRenderer
An instance of the Sitevision class implementing this interface can be obtained via Utils.getLinkRenderer()
.
See Utils
for how to obtain an instance of the Utils
interface.
LinkRenderer is very suitable when rendering more than one link (for instance when rendering a menu) or if you don't want to bother whether or not the site prescribes your link(s) should use link icons or file icons.
LinkRenderer attributes comes in different flavors:
String
or a renderable Node
.<a class="xyz" href="xyz" title="xyz">Linked text</a>
<a class="xyz" href="xyz" title="xyz">Linked text</a>
<a class="xyz" href="xyz" title="xyz">Linked text</a>
<a class="xyz" href="xyz" title="xyz">Linked text</a>
null
<a class="xyz" href="xyz" title="xyz" style="xyz">Linked text</a>
null
<a class="xyz" href="xyz" title="xyz" onclick="xyz"
onkeypress="xyz>Linked text</a>
null
<a class="xyz" href="xyz" title="xyz" id="xyz">Linked text</a>
null
<a class="xyz" href="xyz?a=b&c=d" title="xyz">Linked text</a>
<a class="xyz" href="xyz" title="xyz" rel="xyz">Linked text</a>
null
<a class="xyz" href="xyz" title="xyz" accesskey="xyz">Linked text</a>
null
false
false
<a class="xyz" href="xyz" title="xyz" lang="en">Linked text</a>
null
<a class="xyz" href="xyz" title="xyz" hreflang="en">Linked text</a>
null
false
.
true
.
true
.
true
.
true
.
false
.
----------------------------------------------------------------------------------------------------
Using the LinkRenderer is pretty straightforward, if you remember that it is stateful.
Conceptually you would typically use it like this:
When you have rendered once, you can re-use the LinkRenderer until you are done. Something like:
Example of how this strategy could be implemented in Velocity:
(You want to do a simple menu, i.e. iterate the nodes in a collection/iterator "$pages", and use LinkRenderer to render links to them
as a html list)
## Get PropertyUtil to ease Node property fetching
#set ($propertyUtil = $sitevisionUtils.propertyUtil)
## Use font class 'normal' for all links
#set ($font = 'normal')
## Get LinkRenderer
#set ($linkRenderer = $sitevisionUtils.linkRenderer)
## Iterate through pages and render links to them
<ul style="list-style:none">
#foreach ($page in $pages)
## Fetch the name of the node
#set ($pageName = $propertyUtil.getString($page, 'displayName', $page.toString()))
## Update the renderer and render
$linkRenderer.update($page, $font, $pageName)
<li>
$linkRenderer.render()
</li>
#end
</ul>
----------------------------------------------------------------------------------------------------
Since LinkRenderer is stateful and likely will be used in Velocity frequently, there are some "shortcuts" that might be useful:
update(...)
methods.
If you at the same time want to clear all optional attributes, use one of the updateClean(...)
methods instead.
clearAllOptional()
method
forceOpenNewWindow()
results in an execution of setOpenNewWindow(true)
clearOpenNewWindow()
results in an execution of setOpenNewWindow(false)
null
.
For example: clearAccessKey()
results in an execution of setAccessKey(null)
Thread Note! The render method is NOT thread safe! If two threads simultaneously executes
the render method on the SAME LinkRenderer 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 LinkRenderer instance!
Note/Tip! This interface helps rendering textual links. If you want to render image links, you would typically
use the ImageLinkRenderer
instead.
Modifier and Type | Method and Description |
---|---|
void |
addDataAttribute(String aName,
String aValue)
Adds an HTML5 data-* attribute to the link element.
|
void |
addTargetParameter(String key,
String value)
Adds target parameters (key=value) to the link target (href attribute on the a element).
|
void |
clearAccessKey()
Removes the accesskey, i.e. executes
setAccessKey(null) |
void |
clearAllOptional()
Removes all optional settings.
|
void |
clearDataAttributes()
Removes all existing data attributes
|
void |
clearHrefLang()
Removes the hreflang, i.e executes
setHrefLang(null) |
void |
clearId()
Removes the id value, i.e executes
setId(null) |
void |
clearLang()
Removes the lang, i.e executes
setLang(null) |
void |
clearOnclick()
Removes the onclick value, i.e executes
setOnclick(null) |
void |
clearOpenNewWindow()
Utility method for executing
setOpenNewWindow(false) |
void |
clearRel()
Removes the rel value, i.e executes
setRel(null) |
void |
clearStyle()
Removes the style, i.e executes
setStyle(null) |
void |
clearTargetParameters()
Removes all existing target parameters
|
void |
clearUseAutoTitle()
Utility method for executing
setUseAutoTitle(false) |
void |
clearUseCrossSiteTargetChecking()
Utility method for executing
seUseCrossSiteTargetChecking(false) |
void |
clearUseDownload()
Utility method for executing
setUseDownload(false) |
void |
clearUseEncoding()
Utility method for executing
setUseEncoding(false) |
void |
clearUseLinkDecorationSettings()
Utility method for executing
setUseLinkDecorationSettings(false) |
void |
clearUseParameterEncoding()
Utility method for executing
setUseParameterEncoding(false) |
void |
clearUseResourceDecorationSettings()
Utility method for executing
setUseResourceDecorationSettings(false) |
void |
forceOpenNewWindow()
Utility method for executing
setOpenNewWindow(true) |
void |
forceUseAutoTitle()
Utility method for executing
setUseAutoTitle(true) |
void |
forceUseCrossSiteTargetChecking()
Utility method for executing
setUseCrossSiteTargetChecking(true) |
void |
forceUseDownload()
Utility method for executing
setUseDownload(true) |
void |
forceUseEncoding()
Utility method for executing
setUseEncoding(true) |
void |
forceUseLinkDecorationSettings()
Utility method for executing
setUseLinkDecorationSettings(true) |
void |
forceUseParameterEncoding()
Utility method for executing
setUseParameterEncoding(true) |
void |
forceUseResourceDecorationSettings()
Utility method for executing
setUseResourceDecorationSettings(true) |
boolean |
isRenderableTarget(Node aNode)
Checks if a Node is a renderable target or not (node type accepted).
|
boolean |
isValidTarget(Node aNode)
Checks if a Node is a valid target or not (node type accepted and target is valid).
|
void |
removeTitle()
Removes the title, i.e. executes
setTitle(null) |
String |
render()
Builds a html link based on current state.
|
void |
setAccessKey(String anAccessKey)
Sets what access key the link should have (accesskey attribute on the a element)
The accesskey attribute is optional when the result is rendered.
|
void |
setFont(Node aFontNode)
Sets the class name the link should use (class attribute on an a element) based on a given font node.
|
void |
setFontClass(String aFontClass)
Sets the class name the link should use (class attribute on the a element).
|
void |
setHrefLang(String aHrefLang)
Sets the hreflang attribute on the a element (hints at the language of the linked resource).
|
void |
setId(String anId)
Sets the id value (id attribute on the a element), most likely only needed if some kind of javascript/ajax code needs to access the
rendered link via its id.
|
void |
setLang(String aLang)
Sets the lang attribute on the a element (defines the language of the element).
|
void |
setOnclick(String anOnclick)
Sets the onclick value (onclick attribute and onkeypress attribute on the a element), typically some kind of Javascript
The onclick attribute is optional when the result is rendered.
|
void |
setOpenNewWindow(boolean openNewWindow)
Should the link target be opened in a new window or not?
|
void |
setRel(String aRel)
Sets the rel that should be used (rel attribute on the a element)
The rel attribute is optional when the result is rendered.
|
void |
setStringTarget(String aTarget)
Sets what the link target is, i.e "what the link links to" (href attribute on the a element).
|
void |
setStyle(String aStyle)
Sets the css style the link should have (style attribute on the a element).
|
void |
setTarget(Node aTarget)
Sets what the link target is, i.e "what the link links to" (href attribute on the a element).
|
void |
setText(String aText)
Sets the text that the link should display, i.e.
|
void |
setTitle(String aTitle)
Sets the title the link should have (title attribute on the a element).
|
void |
setUseAutoTitle(boolean useAutoTitle)
Ensures title always will have a value.
|
void |
setUseCrossSiteTargetChecking(boolean useCrossSiteTargetChecking)
Should cross-site internal Node links be handled or not?
|
void |
setUseDownload(boolean useDownload)
Should the browser download the link target instead of navigating to it?
|
void |
setUseEncoding(boolean performEncoding)
Should text and attributes be properly encoded or not?
|
void |
setUseLinkDecorationSettings(boolean useLinkDecorationSettings)
Use icons for "external", "new window" and "new window, external" according to Site's settings or not.
|
void |
setUseParameterEncoding(boolean performParameterEncoding)
Should target parameters be URL encoded or not?
|
void |
setUseResourceDecorationSettings(boolean useResourceDecorationSettings)
Use icons/descriptions for known file types according to Site's settings or not.
|
void |
update(Node aTarget)
Updates current state and removes previous title and text.
|
void |
update(Node aTarget,
String aText)
Updates current state and removes previous title.
|
void |
update(Node aTarget,
String aFontClass,
String aText)
Updates current state and removes previous title.
|
void |
update(Node aTarget,
String aFontClass,
String aText,
String aTitle)
Updates current state.
|
void |
updateClean(Node aTarget)
Updates current state and removes all optional attributes, title and text.
|
void |
updateClean(Node aTarget,
String aText)
Updates current state and removes all optional attributes and title.
|
void |
updateClean(Node aTarget,
String aFontClass,
String aText)
Updates current state and removes all optional attributes and title.
|
void |
updateClean(Node aTarget,
String aFontClass,
String aText,
String aTitle)
Updates current state and removes all optional attributes.
|
void update(Node aTarget, String aFontClass, String aText, String aTitle)
aTarget
- the target of the link (href attribute for the a element)aFontClass
- the class name the link should use (class attribute for the a element)aText
- the link textaTitle
- the title of the link (title attribute for the a element)isValidTarget(javax.jcr.Node)
void update(Node aTarget, String aFontClass, String aText)
aTarget
- the target of the link (href attribute for the a element)aFontClass
- the class name the link should use (class attribute for the a element)aText
- the link textisValidTarget(javax.jcr.Node)
void update(Node aTarget, String aText)
aTarget
- the target of the link (href attribute for the a element)aText
- the link textisValidTarget(javax.jcr.Node)
void update(Node aTarget)
Note. If no text exists when rendering, the target Node will be used to determine an appropriate text (e.g. the display name if the node is a page).
aTarget
- the target of the link (href attribute for the a element)isValidTarget(javax.jcr.Node)
void updateClean(Node aTarget, String aFontClass, String aText, String aTitle)
aTarget
- the target of the link (href attribute for the a element)aFontClass
- the class name the link should use (class attribute for the a element)aText
- the link textaTitle
- the title of the link (title attribute for the a element)clearAllOptional()
,
isValidTarget(javax.jcr.Node)
void updateClean(Node aTarget, String aFontClass, String aText)
aTarget
- the target of the link (href attribute for the a element)aFontClass
- the class name the link should use (class attribute for the a element)aText
- the link textclearAllOptional()
,
isValidTarget(javax.jcr.Node)
void updateClean(Node aTarget, String aText)
aTarget
- the target of the link (href attribute for the a element)aText
- the link textclearAllOptional()
,
isValidTarget(javax.jcr.Node)
void updateClean(Node aTarget)
Note. If no text exists when rendering, the target Node will be used to determine an appropriate text (e.g. the display name if the node is a page).
aTarget
- the target of the link (href attribute for the a element)clearAllOptional()
,
isValidTarget(javax.jcr.Node)
void clearAllOptional()
clearStyle()
clearOnclick()
clearId()
clearTargetParameters()
clearRel()
clearAccessKey()
clearOpenNewWindow()
clearDataAttributes()
clearUseDownload()
clearLang()
clearHrefLang()
String render()
Note! The render method is not thread safe, see thread note above.
void setTarget(Node aTarget)
aTarget
- a Node identifying the targetisValidTarget(javax.jcr.Node)
void setStringTarget(String aTarget)
aTarget
- a String identifying the target (i.e "http://xyz.com", "?name=a&value=b", "/images/a.gif", "#anchor")boolean isRenderableTarget(Node aNode)
This method can be used to avoid updating this renderer with nodes that can't be rendered. Since nodes that aren't renderable will be ignored, updating the renderer with such nodes will result in rendering of previous target.
LinkRenderer
will accept nodes with the following primary node type as targets
(i.e. this method will return true
for such nodes):
sv:article
sv:collaborationGroup
sv:collaborationGroupPage
sv:collaborationGroupTemplate
sv:file
sv:image
sv:link
(the actual target of the link must also be a valid target)sv:page
sv:sitePage
sv:structureLink
(the actual target of the structure link must also be a valid target)sv:structurePage
sv:systemUser
(the system user must have a mail address)sv:template
sv:user
(the user must have a mail address)sv:userIdentity
(the site must have a profile page, or backing user must have a mail address)Always use this method if you are not sure all nodes you are rendering will be accepted as targets.
Example:
Velocity code like this:
<ul style="list-style:none">
#foreach ($node in $myNodes)
## Update the renderer and render
$linkRenderer.update($node)
<li>$linkRenderer.render()</li>
#end
</ul>
could be replaced with Velocity code like this:<ul style="list-style:none">
#foreach ($node in $myNodes)
## Ensure node actually can be rendered
#if ($linkRenderer.isRenderableTarget($node))
## Update the renderer and render
$linkRenderer.update($node)
<li>$linkRenderer.render()</li>
#end
#end
</ul>
Performance note! Calling this method prior to calling an update
method (or the setTarget
method)
will not have any noticeable negative performance impact. The result of this method is internally cached and the update
methods (and the setTarget
method) will re-use that cached data.
aNode
- the node to checktrue
if aNode
is a target that can be rendered, false
if notisValidTarget(javax.jcr.Node)
boolean isValidTarget(Node aNode)
This method is similar to the isRenderableTarget(javax.jcr.Node)
method,
but this method does more extensive checking to ensure rendered links will be ok. Note! "External" link targets (e.g.
a link to "www.whatever.com") of a sv:link Node will NOT be checked.
This method can be used to avoid updating this renderer with nodes that can't be rendered or nodes that have invalid targets. An invalid target is typically an existing link that has an empty or trashed target (i.e. target is in trashcan).
Example:
Velocity code like this:
<ul style="list-style:none">
#foreach ($node in $myNodes)
## Update the renderer and render
$linkRenderer.update($node)
<li>$linkRenderer.render()</li>
#end
</ul>
could be replaced with Velocity code like this:<ul style="list-style:none">
#foreach ($node in $myNodes)
## Ensure node actually can be rendered
#if ($linkRenderer.isValidTarget($node))
## Update the renderer and render
$linkRenderer.update($node)
<li>$linkRenderer.render()</li>
#end
#end
</ul>
Performance note! Avoid subsequent calls to this method for same Node
. If performance is a top
priority, consider using isRenderableTarget(javax.jcr.Node)
instead.
aNode
- the node to checktrue
if aNode
is a target that can be rendered as a functional link, false
if notisRenderableTarget(javax.jcr.Node)
void setFontClass(String aFontClass)
aFontClass
- the class name of the font to usevoid setFont(Node aFontNode)
The actual font class is extracted from aFontNode and if aFontNode is null
or not a valid font node the
font class will not be set.
When subsequently setting the font class, use the setFontClass(String)
method instead for best performance.
aFontNode
- the font node that has a font class that can be extractedsetFontClass(String)
void setText(String aText)
aText
- a link textvoid setTitle(String aTitle)
If there are no title (i.e. it is null
) when the result is rendered, it will get the same
value as text attribute if autoTitle is activated, otherwise it will be empty. Default is null
.
aTitle
- a title describing the linkvoid removeTitle()
setTitle(null)
setTitle(String)
void setStyle(String aStyle)
null
.aStyle
- the style of the linkvoid clearStyle()
setStyle(null)
setStyle(String)
void setLang(String aLang)
aLang
- a single language codevoid clearLang()
setLang(null)
setLang(String)
void setHrefLang(String aHrefLang)
aHrefLang
- a single language codevoid clearHrefLang()
setHrefLang(null)
setHrefLang(String)
void addTargetParameter(String key, String value)
Target parameters is optional when the result is rendered. Default is no target parameters.
There can only be one target parameter per key (i.e. when a target parameter is added it will always replace the possibly existing target parameter that already use that key).
key
- the key of the target parametervalue
- the value of the target parametervoid clearTargetParameters()
void setUseParameterEncoding(boolean performParameterEncoding)
true
.performParameterEncoding
- whether parameters should be URL encoded or not.EndecUtil.encodeURL(String)
void forceUseParameterEncoding()
setUseParameterEncoding(true)
setUseParameterEncoding(boolean)
void clearUseParameterEncoding()
setUseParameterEncoding(false)
setUseParameterEncoding(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 setAccessKey(String anAccessKey)
null
.anAccessKey
- the access key that should be usedvoid clearAccessKey()
setAccessKey(null)
setAccessKey(String)
void setRel(String aRel)
null
.aRel
- the rel that should be used. Note! If "external" is used, the rendered link will be opened in a new window via JavaScriptvoid clearRel()
setRel(null)
setRel(String)
void setOnclick(String anOnclick)
null
.
Note! The events (onclick, onkeypress) will be added with non-obtrusive javascript when render() is called.
anOnclick
- the onClick value that should be usedvoid clearOnclick()
setOnclick(null)
setOnclick(String)
void setId(String anId)
The id attribute is optional when the result is rendered. Default is null
.
This method does not perform any checks of the id. All values will be accepted. (Note! A valid id should be unique - i.e. should not appear more than once in a html/xhtml document - and not all characters are allowed. See W3C 3.3.1 Attribute types.)
anId
- the id value that should be usedvoid clearId()
setId(null)
setId(String)
void setUseLinkDecorationSettings(boolean useLinkDecorationSettings)
true
.useLinkDecorationSettings
- whether or not Site's settings for link type icons should be usedvoid forceUseLinkDecorationSettings()
setUseLinkDecorationSettings(true)
setUseLinkDecorationSettings(boolean)
void clearUseLinkDecorationSettings()
setUseLinkDecorationSettings(false)
setUseLinkDecorationSettings(boolean)
void setUseResourceDecorationSettings(boolean useResourceDecorationSettings)
true
.useResourceDecorationSettings
- whether or not Site's settings for icons/descriptions for known file types should be usedvoid forceUseResourceDecorationSettings()
setUseResourceDecorationSettings(true)
void clearUseResourceDecorationSettings()
setUseResourceDecorationSettings(false)
void setOpenNewWindow(boolean openNewWindow)
false
.openNewWindow
- whether or not the link target should be opened in a new windowvoid forceOpenNewWindow()
setOpenNewWindow(true)
setOpenNewWindow(boolean)
void clearOpenNewWindow()
setOpenNewWindow(false)
setOpenNewWindow(boolean)
void setUseDownload(boolean useDownload)
false
.useDownload
- whether a browser is suggested to download the link target directlyvoid forceUseDownload()
setUseDownload(true)
setUseDownload(boolean)
void clearUseDownload()
setUseDownload(false)
setUseDownload(boolean)
void setUseEncoding(boolean performEncoding)
true
.performEncoding
- whether text should be encoded or not.void forceUseEncoding()
setUseEncoding(true)
setUseEncoding(boolean)
void clearUseEncoding()
setUseEncoding(false)
setUseEncoding(boolean)
void setUseAutoTitle(boolean useAutoTitle)
false
.useAutoTitle
- whether or not the link always should get the title automatically if title is missingvoid forceUseAutoTitle()
setUseAutoTitle(true)
setUseAutoTitle(boolean)
void clearUseAutoTitle()
setUseAutoTitle(false)
setUseAutoTitle(boolean)
void setUseCrossSiteTargetChecking(boolean useCrossSiteTargetChecking)
Default is false
.
Note! For best performance: enable only if your site actually contains internal links to pages on other sites (e.g. The System user creates an internal link and selects a page on another site in the target browse tree).
useCrossSiteTargetChecking
- whether or not to check for cross-site Node targetsvoid forceUseCrossSiteTargetChecking()
setUseCrossSiteTargetChecking(true)
setUseCrossSiteTargetChecking(boolean)
void clearUseCrossSiteTargetChecking()
seUseCrossSiteTargetChecking(false)
setUseCrossSiteTargetChecking(boolean)
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-2022 Sitevision AB, all rights reserved.