S2Velocity

Project Documentation

Built by Maven

Usage

In this document, it is supposed that users can configure and use S2Container, Velocity, Velocity Tools properly, and Velocity template can be a part of view layer in user's web application already.

First of all, toolbox is a set of attributes referring some instance before rendering a Velocity template, so to speak. So, defining a toolbox is as well as defining following 3 points.

  • a name of attribute/reference in Velocity template
  • class of a tool
  • life-cycle of a tool instance

When using S2Velocity, users have to choose either of following two ways of definiton, of toolbox.

Velocity-Tools compatible XML way

In this case, users can use XML file as well as regular Velocity Tools.

Configuration of web.xml are following:

Note that a definition of S2ContainerServlet is not to be changed, only a change needed is from VelocityViewServlet to S2VelocityViewServlet.

web.xml

        <servlet>
                <servlet-name>velocity</servlet-name>
                <servlet-class>org.seasar.velocity.tools.S2VelocityViewServlet</servlet-class>
                <init-param>
                        <param-name>org.apache.velocity.toolbox</param-name>
                <param-value>/WEB-INF/toolbox.xml</param-value>
                </init-param>
                <init-param>
                        <param-name>org.apache.velocity.properties</param-name>
                        <param-value>/WEB-INF/velocity.properties</param-value>
                </init-param>
                <load-on-startup>10</load-on-startup>
        </servlet>

As an example shown above, /WEB-INF/toolbox.xml is toolbox definition file.

Then, prepare XML file such as following:

toolbox.xml

<?xml version="1.0"?>
<toolbox>
  <tool>
    <key>sampleTool</key>
    <scope>request</scope>
    <class>org.seasar.velocity.tools.examples.hello.SampleTool</class>
  </tool>
  .
  .
</toolbox>

See Velocity Tools document for more details about this XML notation.

  • key describes name of reference in Velocity template. As an example above it is $sampleTool within Velocity template.
  • scope must be one of request , session , application . it describes a life-cycle of a tool instance.
  • class describes FQCN class name for tool class.

Please note that there is incompatible behavior in S2Velocity than Velocity Tools 1.3.

  • parameter tag cannot be used
    It'll be fixed in next version of S2Velocity. If you want same functionality with Velocity Tools, it can be help to use S2Container namespace based configuration.

S2Container namespace way

In this case, all of components defined in a container having 'toolbox' namespace, are used as toolbox. All components of that container will be set to attributes by S2Velocity in each request, so, flexible definition of properties, life-cycle, for components can be used with toolbox.

Configuration of web.xml are following:

Note that a definition of S2ContainerServlet is not to be changed, only a change needed is from VelocityViewServlet to S2VelocityViewServlet.

web.xml

        <servlet>
                <servlet-name>velocity</servlet-name>
                <servlet-class>org.seasar.velocity.tools.S2VelocityViewServlet</servlet-class>
                <init-param>
                        <param-name>org.apache.velocity.toolbox</param-name>
                        <param-value>container</param-value>
                </init-param>
                <init-param>
                        <param-name>org.apache.velocity.properties</param-name>
                        <param-value>/WEB-INF/velocity.properties</param-value>
                </init-param>
                <load-on-startup>10</load-on-startup>
        </servlet>

As shown above, org.apache.velocity.toolbox init-param having container is the point.

For example, a .dicon file is shown below. This dicon assumes that the version of S2Container is 2.4.x.

toolbox.dicon

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR//DTD S2Container 2.4//EN"
        "http://www.seasar.org/dtd/components24.dtd">
<components namespace="toolbox">
    <include path="all_services.dicon" />

        <component name="sampleTool" instance="request" class="org.seasar.velocity.tools.examples.hello.SampleTool" />
        <component name="itemTool" instance="request" class="org.seasar.velocity.tools.examples.dao.ItemTool" />

        <component name="requestCountTool" instance="request" class="org.seasar.velocity.tools.examples.scope.CountTool" />
        <component name="sessionCountTool" instance="session" class="org.seasar.velocity.tools.examples.scope.CountTool" />
        <component name="appCountTool" instance="singleton" class="org.seasar.velocity.tools.examples.scope.CountTool" />
</components>

In addition to this example, (such as) app.dicon must have include tag references this file. Each component definition has name attribute and the value will be reference name in Velocity template (such as $appCountTool)

Please note that:

  • Incompatible "init" behavior with Velocity Tools (and application scoped toolbox) (Instead, S2Container can inject ServletContext in other ways.)