senselogic.sitevision.api.render

Interface UserFieldRenderer

@Requireable(value="UserFieldRenderer")
public interface UserFieldRenderer

UserFieldRenderer is a stateful utility interface for rendering user field values for user identities.

An instance of the SiteVision class implementing this interface can be obtained via Utils.getUserFieldRenderer(). See Utils for how to obtain an instance of the Utils interface.

Using the UserFieldRenderer is pretty straightforward, if you remember that it is stateful and that the previously loaded user identity node will be cleared whenever you try to load a new one. Conceptually you would typically use it like this:

1. Get the UserFieldRenderer
2. Set a user identity node
3. Do render of a named user field
4. Do render of another named user field
5. ...

You can then re-use the UserFieldRenderer for another user identity until you are done. Something like:

1. Update the user identity node
2. Do render of a named user field
3. Do render of another named user field
4. ...

Example of how this strategy could be implemented in Velocity:
(You want to do a simple listing of the user fields "Namn" and "E-postadress" for some user identities or users in $myList)

   ## Get UserFieldRenderer
   #set ($userFieldRenderer = $sitevisionUtils.userFieldRenderer)

   ## Ensure at least one of the fields actually exist
   #if ($userFieldRenderer.isValidFieldName('Namn') || $userFieldRenderer.isValidFieldName('E-postadress'))
     ## Iterate through the list and render fields for all valid nodes
     <ul class="sv-no-list-style">
     #foreach ($item in $myList)
       ## Check if this node can be rendered
       #if ($userFieldRenderer.isRenderable($item))
         ## Update the renderer and render
         $userFieldRenderer.update($item)
         <li>
           $userFieldRenderer.render('Namn')
           $userFieldRenderer.render('E-postadress')
         </li>
       #end
     #end
     </ul>
   #end
 

Important rendering note! When rendering a user field value, you must specify the name of the user field. See isValidFieldName(String) for more information about how names are matched to user fields.

Since:

SiteVision 3.5.3

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
String	getPlainUserFieldValueAsHtml(String aPlainUserFieldValue) Returns a plain text user field value as html.
boolean	isLoaded() Whether or not this renderer contains a user identity.
boolean	isRenderable(Node aNode) Helper method to check if a certain node can be rendered.
boolean	isValidFieldName(String aUserFieldName) Helper method to check if a named user field is available.
String	render(String aUserFieldName) Returns the value as html for a named user field for currently loaded user identity.
String	renderPlain(String aUserFieldName) Returns the value as plain text for a named user field for currently loaded user identity.
void	update(Node aUserIdentity) Updates the renderer with a new user identity node.

Method Detail

update

void update(Node aUserIdentity)

Updates the renderer with a new user identity node.

If aUserIdentity is not a renderable node, the argument will be considered as null, i.e. the renderer will not have any renderable node in subsequent render execution.

Parameters:

aUserIdentity - a user identity node, or a user that has an identity on current site

isLoaded

boolean isLoaded()

Whether or not this renderer contains a user identity.

Returns:

true if a renderable node is loaded, false if not.

isRenderable

boolean isRenderable(Node aNode)

Helper method to check if a certain node can be rendered.

Nodes with the following primary node types are potentially renderable:

• sv:userIdentity
• sv:user (non-anonymous) » will be renderable if a sv:userIdentity can be extracted
• sv:simpleUser » will be renderable if a sv:userIdentity can be extracted
• sv:systemUser » will be renderable if a sv:userIdentity can be extracted

Parameters:

aNode - the node to check

Returns:

true if aNode is supported by this renderer, false if not

isValidFieldName

boolean isValidFieldName(String aUserFieldName)

Helper method to check if a named user field is available.

An important note about field names and user field lookup! A specific user field can be found via multiple names:

1. Primarily user fields are found via their UI name.
2. Secondary user fields are found via their Ldap name (ldap-read fields only).
3. As last resort user fields are found via their Index name.

First found match is used!

This is a convenience to make user fields easier to find, but beware of colliding names! For instance, if field A has Ldap name "X" and field B has UI name "X" - field B will be used.

Parameters:

aUserFieldName - the name of the user field

Returns:

true if current site has a user field that can be found via aUserFieldName, false if not

render

String render(String aUserFieldName)

Returns the value as html for a named user field for currently loaded user identity.

The rendered output of the user field value is handled as:

• The value is XML escaped (see: EndecUtil.escapeXML(String))
• Line breaks are converted to <br> (see: EndecUtil.br(String))
• Potential links are converted to anchors (see: OutputUtil.getHyperlinkedText(String))

Note! The result of this method is equivalent with calling getPlainUserFieldValueAsHtml(String) with the result of the renderPlain(String) method, but this method is more efficient and should always be preferred.

Parameters:

aUserFieldName - the name of the user field, see: isValidFieldName(String)

Returns:

a html string, ready to print out on a page. Might be empty but never null.

renderPlain

String renderPlain(String aUserFieldName)

Returns the value as plain text for a named user field for currently loaded user identity.

Note! The rendered output is plain text and must be escaped if it should be part of the html output of a page!

Parameters:

aUserFieldName - the name of the user field, see: isValidFieldName(String)

Returns:

a plain string. Might be empty but never null.

Since:

SiteVision 3.6

See Also:

render(String)

getPlainUserFieldValueAsHtml

String getPlainUserFieldValueAsHtml(String aPlainUserFieldValue)

Returns a plain text user field value as html.

Note! This method is stateless, i.e. you don't have to have a user identity loaded to call this method. Typically you would always use the render(String) whenever possible. This method should only be used when you have a plain text user field value, but no user identity (e.g. in large search results where you want to avoid loading lots of user identity objects).

The rendered output of the plain text user field value is handled as:

• The value is XML escaped (see: EndecUtil.escapeXML(String))
• Line breaks are converted to <br> (see: EndecUtil.br(String))
• Potential links are converted to anchors (see: OutputUtil.getHyperlinkedText(String))

Parameters:

aPlainUserFieldValue - the plain text user field value

Returns:

a html string, ready to print out on a page. Might be empty but never null.

Since:

SiteVision 3.6