<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed 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>
 </properties>

<body>

<section name="Introduction">
<p>
    The VelocityECSLayout has been deprecated in Turbine 2.3. 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($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>
]]>
</source>
</section>

<section name="Writing Directly To ServletOutputStream">
<p>
    See
	<a href="http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaTurbine2/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>