xdocs/howto/velocityonlylayout-howto.xml - turbine-core - Git at Google

 <?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>
	<?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>