<?xml version="1.0"?>

<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<document>

 <properties>
  <title>VelocityOnlyLayout</title>
  <author email="quintonm@bellsouth.net">Quinton McCombs</author>
  <author email="seade@backstagetech.com.au">Scott Eade</author>
 </properties>

<body>

<section name="Introduction">
<p>
    <strong>The VelocityECSLayout was deprecated in Turbine 2.3 (and removed in
    2.3.3).</strong> This document is intended to help you convert your
    application to use the VelocityOnlyLayout.
</p>
<p>
    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.
</p>
<p>
    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.
</p>
</section>

<section name="Changes to make in TR.props">
<p>
    Changes the definition of the $page pull tool:
</p>
<source>
<![CDATA[
tool.request.page = org.apache.turbine.util.template.HtmlPageAttributes
]]>
</source>
<p>
	Change the default layout
</p>
<source>
<![CDATA[
services.VelocityService.default.layout = VelocityOnlyLayout
]]>
</source>

</section>

<section name="Changes to your code">
<p>
  <ul>
  	<li>$page.addAttribute(attribute,value) has been replaced with
  	    $page.addBodyAttribute(attribute,value)</li>
  	<li>$page.setScript(url) has been replaced with
  	    $page.addScript(url)</li>
  	<li>$page.setStyleSheet(url) has been replaced with
  	    $page.addStyleSheet(url)</li>
  	<li>$page.setStyle(styleText) has been replaced with
  	    $page.addStyle(styleText)</li>
  	<li>$page.setStyleSheet(url,media) has been replaced with
  	    $page.addStyleSheet(url,media,title,type)</li>
  </ul>
</p>
<p>
    <em>Use of any of the deprecated methods will generate a log message
    at the info level.</em>
</p>
<p>
    Add the line
</p>
<source>
<![CDATA[
$page.DefaultDoctype
]]>
</source>
<p>
    to your layout templates to pick up the default doctype definition from
    TurbineResources.properties thus:
</p>
<source>
<![CDATA[
# 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
]]>
</source>
<p>
    Add the line
</p>
<source>
<![CDATA[
services.VelocityService.velocimacro.library = macros/TurbineMacros.vm
]]>
</source>
<p>
    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.
</p>
<p>
    Here is a sample layout template that you can use:
</p>
<source>
<![CDATA[
    ## 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>
]]>
</source>
<p>
    This produces the same code as the following sample layout
    template that you can use:
</p>
	<source>
<![CDATA[
    ## 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( $linkTag in $page.Links )
        <link rel="$linkTag.Relation" href="$linkTag.Url"
          #if($!linkTag.Type)  type="$linkTag.Type"   #end
          #if($!linkTag.Media) media="$linkTag.Media" #end
          #if($!linkTag.Title) title="$linkTag.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>
]]>
</source>
</section>

<section name="Writing Directly To ServletOutputStream">
<p>
    See
	<a href="http://wiki.apache.org/turbine/Turbine2/VelocityOnlyLayout">
	VelocityOnlyLayout</a> on the Apache wiki for some information concerning
	writing directly to ServletOutputStream.
</p>
</section>

<section name="Updates to this document">
<p>
    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.
</p>
</section>

</body>
</document>
