Apache Turbine – VelocityOnlyLayout

Introduction

The VelocityECSLayout has been deprecated in Turbine 2.3. This document is intended to help you convert your application to use the VelocityOnlyLayout.

The VelocityOnlyLayout does not use ECS to generate the HTML page for you. This also means that the current $page pull tool will not work with the VelocityOnlyLayout. You will be responsible for constructing the HTML, HEAD, BODY, etc. tags using Velocity.

Although this seems like a lot of trouble, it really isn't. All that you really need to do is modify your layout templates. You will still use the $page pull tool just like before. Your layout templates will also use the $page pull tool to extract the data needed to build the HEAD and BODY tags.

Changes to make in TR.props

Changes the definition of the $page pull tool:


tool.request.page = org.apache.turbine.util.template.HtmlPageAttributes

Change the default layout


services.VelocityService.default.layout = VelocityOnlyLayout

Changes to your code

$page.addAttribute(attribute,value) has been replaced with $page.addBodyAttribute(attribute,value)
$page.setScript(url) has been replaced with $page.addScript(url)
$page.setStyleSheet(url) has been replaced with $page.addStyleSheet(url)
$page.setStyle(styleText) has been replaced with $page.addStyle(styleText)
$page.setStyleSheet(url,media) has been replaced with $page.addStyleSheet(url,media,title,type)

Use of any of the deprecated methods will generate a log message at the info level.

Add the line


$page.DefaultDoctype

to your layout templates to pick up the default doctype definition from TurbineResources.properties thus:


# Set the components of the default Doctype for use in html documents.
#
# Defaults: There are no defaults - if default.html.doctype.root.element is not
#           set then no default doctype will be available.

default.html.doctype.root.element=HTML
default.html.doctype.identifier=-//W3C//DTD HTML 4.01 Transitional//EN
default.html.doctype.url=http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd

Add the line


services.VelocityService.velocimacro.library = macros/TurbineMacros.vm

to your TurbineResources.properties and it will pick up the TurbineMacros.vm in your Turbine jar. An example of how to use these macros follows.

Here is a sample layout template that you can use:


    ## Set defaults for all pages using this layout.  Anything set here can
    ## be overridden in the screen template.
    $page.setTitle("My default page title");
    $page.setHttpEquiv("Content-Style-Type","text/css")
    $page.addStyleSheet($content.getURI("myStyleSheet.css"))
    $page.addScript($content.getURI("globalJavascriptCode.js"))
    ## build the HTML, HEAD, and BODY tags dynamically

    $page.DefaultDoctype
    <html>
      #TurbineHtmlHead()
      <body #TurbineHtmlBodyAttributes() >
      $navigation.setTemplate("default_header.vm")
      $screen_placeholder
      $navigation.setTemplate("default_footer.vm")

      </body>
    </html>

This produces the same code as the following sample layout template that you can use:


    ## Set defaults for all pages using this layout.  Anything set here can
    ## be overridden in the screen template.
    $page.setTitle("My default page title");
    $page.setHttpEquiv("Content-Style-Type","text/css")
    $page.addStyleSheet($content.getURI("myStyleSheet.css"))
    $page.addScript($content.getURI("globalJavascriptCode.js"))
    ## build the HTML, HEAD, and BODY tags dynamically

    $page.DefaultDoctype
    <html>
      <head>
        #if($page.Title != "")
        <title>$page.Title</title>
        #end
        #foreach($metaTag in $page.MetaTags.keySet())
        <meta name="$metaTag" content="$page.MetaTags.get($metaTag)">
        #end
        #foreach($httpEquiv in $page.HttpEquivs.keySet())
        <meta http-equiv="$httpEquiv" content="$page.HttpEquivs.get($httpEquiv)">
        #end
        #foreach($styleSheet in $page.StyleSheets)
          <link rel="stylesheet" href="$styleSheet.Url"
            #if($styleSheet.Type != "" ) type="$styleSheet.Type" #end
            #if($styleSheet.Media != "") media="$styleSheet.Media" #end
            #if($styleSheet.Title != "") title="$styleSheet.Title" #end
          >
        #end
        #if ($page.Styles.size() > 0)
          <style type="text/css">
          #foreach( $style in $page.Styles )
            $!style
          #end
          </style>
        #end
        #foreach($script in $page.Scripts)
          <script type="text/javascript" src="$script" language="JavaScript"></script>
        #end
      </head>

      ## Construct the body tag.  Iterate through the body attributes to build the opening tag
      <body
        #foreach($attributeName in $page.BodyAttributes.keySet())
          $attributeName = "$page.BodyAttributes.get($attributeName)"
        #end
      >

      $navigation.setTemplate("default_header.vm")
      $screen_placeholder
      $navigation.setTemplate("default_footer.vm")

      </body>
    </html>

Writing Directly To ServletOutputStream

See VelocityOnlyLayout on the Turbine wiki for some information concerning writing directly to ServletOutputStream.

Updates to this document

This document is by no means complete or totally accurate. We welcome suggestions as to how it might be improved, particularly if you have just completed updating an application by following this howto.