senselogic.sitevision.api.render.velocity

Interface VelocityRenderer

Deprecated.

portlet applications are the legacy way of extending Sitevision. WebApp/RESTApp technique should be used instead as of Sitevision 5. This class will be removed in a future version of Sitevision.

@Requireable(value="VelocityRenderer")
 @Deprecated
public interface VelocityRenderer

A renderer that can be used in custom portlets for rendering Velocity templates.

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

Note! This renderer relies heavily on the internal Sitevision Velocity rendering facilities!

The upside of this is that you get caching and such "for free" and you don't have to include or use any Velocity jar when creating your portlet application (war file). You will also avoid possible Velocity.init() caveats and such. The possible downside is that the Velocity engine and its features potentially can be replaced at any time (i.e. whenever Sitevision is updated).

⇒ Ensure your Velocity template(-s) doesn't contain really "edgy" stuff or relies on bugs in currently used Velocity version. If so, your code might potentially break in a future Sitevision update!

Below is a simple example of how the VelocityRenderer can be used in a custom portlet:

 import senselogic.sitevision.api.Utils;
 import senselogic.sitevision.api.portlet.GenericSiteVisionPortlet;
 import senselogic.sitevision.api.render.velocity.VelocityContext;
 import senselogic.sitevision.api.render.velocity.VelocityException;
 import senselogic.sitevision.api.render.velocity.VelocityRenderer;

 import javax.portlet.*;
 import java.io.IOException;
 import java.io.PrintWriter;

 public class HelloVelocityPortlet extends GenericSiteVisionPortlet {
    private String template;    // Never reassigned after init, ok to use as field
    private String subTemplate; // Never reassigned after init, ok to use as field

    @Override
    public void init(PortletConfig portletConfig) throws PortletException {
       super.init(portletConfig);

       template =
          " Current request is: $request <br>                  " +
          " Utils is: $sitevisionUtils <br>                    " +
          " Session is: $jcrSession <br>                       " +
          " VelocityEvaluator is: $velocityEvaluator <br>      " +
          " <br>                                               " +
          " #set($count = 1)                                   " +
          " This is written with the VelocityEvaluator: <br>   " +
          " <div style=\"margin:0 20px\">                      " +
          "    $velocityEvaluator.evaluate($evaluateThis)      " +
          " </div>                                             ";

       subTemplate =
          " #if ($count)                                                           " +
          "    count exists and is: $count                                         " +
          " #else                                                                  " +
          "    The 'count' reference is missing in the context I'm rendering in... " +
          " #end                                                                   ";
    }

    @Override
    protected void doView(RenderRequest renderRequest, RenderResponse renderResponse) throws PortletException, IOException {
       PrintWriter writer = getWriter(renderResponse);

       // Get the Velocity renderer
       Utils utils = getUtils(renderRequest);
       VelocityRenderer velocityRenderer = utils.getVelocityRenderer();

       // Create a Sitevision API rendering context (i.e. $request, $sitevisionUtils, $jcrSession and $velocityEvaluator are added)
       VelocityContext context = velocityRenderer.getVelocityContext(renderRequest, writer);
       context.put("evaluateThis", subTemplate); // Add a 'evaluateThis' reference used by the $velocityEvaluator, see templates above

       // Render!
       try {
          velocityRenderer.render(context, template);
       } catch (VelocityException e) {
          utils.getLogUtil().debug("Exception occurred while rendering 'Hello Velocity' portlet template", e);
       }
    }

    @Override
    public void destroy() {
       template = null;
       subTemplate = null;
       super.destroy();
    }
 }

The portlet code above demonstrates the actual Java portlet code, but also gives some Velocity code examples. Though, this example is probably somewhat non-realistic in the real world. When implementing a proper variant of this portlet, you would typically put all of your Velocity code in separate .vm files instead of building massive concatenated Java strings...

Since:

Sitevision 3.0

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
VelocityContext	getVelocityContext(PortletRequest aPortletRequest, Writer aWriter) Deprecated. Creates and returns a VelocityContext instance with the default Sitevision API mappings.
VelocityContext	getVelocityContext(javax.servlet.ServletRequest aServletRequest, Writer aWriter) Deprecated. Creates and returns a VelocityContext instance with the default Sitevision API mappings.
VelocityContext	getVelocityContext(Writer aWriter) Deprecated. Creates and returns an empty VelocityContext instance.
void	render(VelocityContext aContext, String aTemplate) Deprecated. Renders a Velocity template string.

Method Detail

getVelocityContext

VelocityContext getVelocityContext(Writer aWriter)
                            throws IllegalArgumentException

Deprecated.

Creates and returns an empty VelocityContext instance.

Parameters:

aWriter - the rendering output (typically RenderResponse.getWriter()), not null

Returns:

a VelocityContext instance that can be used in the render method

Throws:

IllegalArgumentException - if aWriter is null

getVelocityContext

VelocityContext getVelocityContext(PortletRequest aPortletRequest,
                                   Writer aWriter)
                            throws IllegalArgumentException

Deprecated.

Creates and returns a VelocityContext instance with the default Sitevision API mappings.

Pre-added mappings in VelocityContext (if aPortletRequest is non-null)

Name (available via $)	Value (an object instance)
request	the PortletRequest instance
sitevisionUtils	an instance of Utils
jcrSession	an instance of Session
velocityEvaluator	an instance of VelocityEvaluator

Parameters:

aPortletRequest - the request to use as base for adding the default Sitevision API mappings. No mappings will be added if null.

aWriter - the rendering output (typically RenderResponse.getWriter()), not null

Returns:

a VelocityContext instance that can be used in the render method

Throws:

IllegalArgumentException - if aWriter is null

getVelocityContext

VelocityContext getVelocityContext(javax.servlet.ServletRequest aServletRequest,
                                   Writer aWriter)
                            throws IllegalArgumentException

Deprecated.

Creates and returns a VelocityContext instance with the default Sitevision API mappings.

Pre-added mappings in VelocityContext (if aServletRequest is non-null)

Name (available via $)	Value (an object instance)
request	the ServletRequest instance
sitevisionUtils	an instance of Utils
jcrSession	an instance of Session
velocityEvaluator	an instance of VelocityEvaluator

Parameters:

aServletRequest - the request to use as base for adding the default Sitevision API mappings. No mappings will be added if null.

aWriter - the rendering output (typically HttpServletResponse.getWriter()), not null

Returns:

a VelocityContext instance that can be used in the render method

Throws:

IllegalArgumentException - if aWriter is null

render

void render(VelocityContext aContext,
            String aTemplate)
     throws IllegalArgumentException,
            VelocityException,
            IOException

Deprecated.

Renders a Velocity template string.

Parameters:

aContext - a context with mappings needed by aTemplate (Note! this must be an instance created via any of the methods above, a custom VelocityContext implementation is not allowed).

aTemplate - a String containing the Velocity code to be evaluated

Throws:

IllegalArgumentException - if aTemplate is null, if aContext is null or not created via VelocityRenderer

VelocityException - if parsing/evaluation of aTemplate fails

IOException - if an I/O exception occurs during the rendering process