| <?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> |
| </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://wiki.apache.org/turbine/Turbine2/VelocityOnlyLayout"> |
| VelocityOnlyLayout</a> on the Turbine 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> |