howto/context-howto.html - turbine-core.git - Git at Google

 <!DOCTYPE html>


 <!--
  | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/howto/context-howto.xml at 17 Jun 2025
  | Rendered using Apache Maven Fluido Skin 2.1.0
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
     <title>Context Howto – Apache Turbine</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-2.1.0.min.css" />
     <link rel="stylesheet" href="../css/site.css" />
     <link rel="stylesheet" href="../css/print.css" media="print" />
     <script src="../js/apache-maven-fluido-2.1.0.min.js"></script>
 <link rel="icon" type="image/png" sizes="48x48" href="./images/favicon.ico">
       <link rel="icon" type="image/png" sizes="48x48" href="../images/favicon.ico">
       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
     <style>.github-fork-ribbon:before { background-color: orange; }</style>
   </head>
   <body>
     <a class="github-fork-ribbon right-top" href="https://github.com/apache/turbine-build" data-ribbon="Fork me on GitHub">Fork me on GitHub</a>
     <div class="container-fluid container-fluid-top">
       <header>
         <div id="banner">
           <div class="pull-left"><div id="bannerLeft"><h1><a href="https://turbine.apache.org/"><img src="../images/turbine-project-apache-separate.png" alt="Apache Turbine" /></a></h1></div></div>
           <div class="pull-right"><div id="bannerRight"><h1><a href="https://turbine.apache.org/"><img src="../images/logo.gif" /></a></h1></div></div>
           <div class="clear"><hr/></div>
         </div>

         <div id="breadcrumbs">
           <ul class="breadcrumb">
         <li id="publishDate">Last Published: 01 Apr 2025<span class="divider">|</span>
 </li>
           <li id="projectVersion">Version: 7.0</li>
         <li class="pull-right"><span class="divider">|</span>
 <a href="https://turbine.apache.org/fulcrum/">Fulcrum</a></li>
         <li class="pull-right"><span class="divider">|</span>
 <a href="https://turbine.apache.org/">Turbine</a></li>
         <li class="pull-right"><a href="https://www.apache.org">Apache</a></li>
           </ul>
         </div>
       </header>
       <div class="row-fluid">
         <header id="leftColumn" class="span2">
           <nav class="well sidebar-nav">
   <ul class="nav nav-list">
    <li class="nav-header">General Information</li>
     <li><a href="../index.html">Overview</a></li>
     <li><a href="../features.html">Features</a></li>
     <li><a href="../fsd.html">Specification</a></li>
     <li><a href="../getting-started.html">Getting Started</a></li>
     <li><a href="../how-to-build.html">Howto Build Turbine</a></li>
     <li><a href="../changes-report.html">Changes</a></li>
    <li class="nav-header">Documentation</li>
     <li><a href="../services/index.html"><span class="icon-chevron-right"></span>Services</a></li>
     <li><a href="../howto/index.html"><span class="icon-chevron-down"></span>Howtos</a>
      <ul class="nav nav-list">
       <li><a href="../howto/action-event-howto.html">Action Events Howto</a></li>
       <li><a href="../howto/annotations.html">Annotations Howto</a></li>
       <li><a href="../howto/configuration-howto.html">Configuration Howto</a></li>
       <li><a href="../howto/extend-user-howto.html">Extend User Howto</a></li>
       <li><a href="../howto/hibernate-howto.html">Hibernate OM Howto</a></li>
       <li><a href="../howto/intake-howto.html">Intake Howto</a></li>
       <li><a href="../howto/jsp-howto.html">JSP Howto</a></li>
       <li><a href="../howto/migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li>
       <li><a href="../howto/migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li>
       <li><a href="../howto/migrate-from-2_3-howto.html">Migrating from 2.3 to 4.0</a></li>
       <li><a href="../howto/migrate-from-4_0-howto.html">Migrating from 4.0 to 5.0</a></li>
       <li><a href="../howto/pullmodel-howto.html">Pull Model Howto</a></li>
       <li><a href="../howto/python-howto.html">Python Howto</a></li>
       <li><a href="../howto/security-howto.html">Security Howto</a></li>
       <li><a href="../howto/services-howto.html">Services Howto</a></li>
       <li><a href="../howto/url-mapper-howto.html">URL Mapper Howto</a></li>
       <li><a href="../howto/url-rewriting-howto.html">URL Rewriting Howto</a></li>
       <li class="active"><a>Velocity Context Howto</a></li>
       <li><a href="../howto/velocity-site-howto.html">Velocity Site Howto</a></li>
       <li><a href="../howto/velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a></li>
      </ul></li>
     <li><a href="https://cwiki.apache.org/confluence/display/TURBINE">Wiki</a></li>
     <li><a href="../apidocs/index.html">JavaDocs</a></li>
    <li class="nav-header">Development</li>
     <li><a href="../proposals.html">Proposals</a></li>
     <li><a href="../how-to-help.html">How To Help</a></li>
     <li><a href="../todo.html">Todo</a></li>
    <li class="nav-header">Project Documentation</li>
     <li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
     <li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
    <li class="nav-header">Apache</li>
     <li><a href="https://www.apache.org/">Apache Website</a></li>
     <li><a href="https://www.apache.org/licenses/">License</a></li>
     <li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li>
     <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
     <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
     <li><a href="https://www.apache.org/security/">Security</a></li>
   </ul>
           </nav>
           <div class="well sidebar-nav">
 <form id="search-form" action="https://www.google.com/search" method="get" >
   <input value="http://turbine.apache.org/turbine/turbine-7-0" name="sitesearch" type="hidden" />
   <input class="search-query" name="q" id="query" type="text" placeholder="Search with Google..." />
 </form>
             <div id="poweredBy">
               <div class="clear"></div>
               <div class="clear"></div>
 <a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
             </div>
           </div>
         </header>
         <main id="bodyColumn" class="span10">


 <section><a id="Using_the_Turbine_Context"></a>
 <h1>Using the Turbine Context</h1>

 <p>
 The Turbine Templating Services attach references to default Objects in the
 Turbine Context as part of their initialization. In the case of the
 TurbineVelocityService these references point to RunData, TemplateLink and
 TemplatePageAttributes. These three are put into the Context in the
 TurbineVelocityService class. The Context stores the Objects in a Hashtable
 with a key and the Object.
 </p>
 </section>

 <section><a id="Using_the_RunData_Object"></a>
 <h1>Using the RunData Object</h1>

 <p>
 The RunData Object is referenced by the &quot;data&quot; keyword, which when using this
 in the templating system is referenced by $data. As the Context contains a link
 to the RunData object all the public methods in the RunData Object are made
 available to the template. For example, typing $data.getMessage() will access
 the message String being stored in the RunData Object and print that as part
 of the templates output.
 </p>


 <p>
 RunData exposes an extremely rich series of methods and fields, for a full list
 of these methods refer to the Javadocs for RunData. Some of the useful methods
 exposed in RunData include;
 </p>


 <p>
 </p>
 <ul>
     addMessage(String msg) <br />
     getMessage() <br />
     getParameters() <br />
     getServerName() <br />
     getTitle() <br />
     getUser() <br />
     removeUserFromSession() <br />
     setMessage(String message) <br />
     setRedirectUri(String ruri) <br />
     setTitle(String title) <br />
     setLayoutTemplate(String title) <br />
 </ul>


 <p>
 The RunData also allows for access to the TemplateInfo Object via
 getTemplateInfo() and several convenience methods. This allows for properties
 of the Templates to be modified for a Request when using templating systems like
 Velocity, WebMacro or Freemarker.
 </p>


 <p>
 As an example assume we want a printable page that contains only the Templating
 Screen and not all the navigational components. To achieve this we can strip
 out all the non screen templating components by describing a new Layout Template
 called PrintableLayout.vm in the templates/layouts directory. All the
 PrintableLayout needs contain is;
 </p>


 <pre class="prettyprint"><code>
     $screen_placeholder
 </code></pre>


 <p>
 Without the references to the $navigation.setTemplate() methods in the template
 no navigational screen will be called. In the Screen Template that wants to take
 advantage of the PrintableLayout Template add to the Template;
 </p>


 <pre class="prettyprint"><code>
     $data.setLayoutTemplate(&quot;/PrintableLayout.vm&quot;)
 </code></pre>


 <p>
 This will strip the Screen Template of its Navigational components. These
 convenience methods can also be used to expose and to set the Layout when the
 Template is processed. Through this a User can potentially choose how they would
 like their webpage to appear by choosing one of many differant Layouts or
 choices you, the webdesigner provide.
 </p>
 </section>

 <section><a id="Using_the_TemplateLink_Object"></a>
 <h1>Using the TemplateLink Object</h1>

 <p>
 The TemplateLink is an extended version of DynamicURI customised to be used in
 the templates. The TemplateLink is referenced in the templates via $link and
 exposes convenience methods for building URI's on the fly. For example in a
 template to build the URI to another template, TemplateLink would be referenced
 via;
 </p>


 <pre class="prettyprint"><code>
     $link.setPage(&quot;newpage.vm&quot;)
 </code></pre>


 <p>
 which when added to a Velocity template would (depending on the servlet
 configuration) return;
 </p>


 <p>

 <blockquote>
     http://127.0.0.1:8080/newapp/servlet/newapp/template/index.vm
 </blockquote>
 </p>


 <p>
 where &quot;newapp&quot; is the chosen webapp deployment name.
 </p>


 <p>
 This same mechanism can also be used to link to static html;
 </p>


 <pre class="prettyprint"><code>
     $link.setPage(&quot;/path/to/static.html&quot;)
 </code></pre>


 <p>
 However the HTML page will load itself into a screen and not be embedded withint the Layouts and Navigations. If you still wish static content to be embedded within the specified layouts and navigations it is easier to add the static content as a velocity template and not take advantage of any of the dynamic content addition the Velocity Context allows.
 </p>


 <p>
 TemplateLink and DynamicURI again expose a rich set of methods and fields to
 the link reference, for a full list of fields and methods please refer to
 TemplateLink and DynamicURI in the javadocs. Some of the useful methods
 exposed are;
 </p>


 <p>
 </p>
 <ul>
     setPage(String templatename) <br />
     addPathInfo(ParameterParser pp) <br />
     addPathInfo(String name, String value) <br />
     addQueryData(ParameterParser pp) <br />
     addQueryData(String name, String value) <br />
     getScriptName() <br />
     getServerData() <br />
     getServerPort() <br />
     setAction(String action) <br />
     setScreen(String screen) <br />
     setSecure() <br />
 </ul>

 </section>

 <section><a id="Using_the_TemplatePageAttributes_Object"></a>
 <h1>Using the TemplatePageAttributes Object</h1>

 <p>
 The TemplatePageAttributes is accessed from within the context by the keyword
 &quot;page&quot; and provides methods to modify the various HTML attributes of the
 templating system. The Template context can be used to dictate the style of
 the HTML page in the navigation and layout templates as well as modify these
 attributes from within a screen.
 </p>


 <p>
 As an example in the default.vm the page can be set to a maroon background with;
 </p>


 <pre class="prettyprint"><code>
     $page.setBgColor(&quot;#800000&quot;)
 </code></pre>


 <p>
 the screen template may need to set a new title to the page being displayed in
 the browser, this can be done in the screen template via;
 </p>


 <pre class="prettyprint"><code>
     $page.setTitle(&quot;New Title to Page&quot;)
 </code></pre>


 <p>
 Non standard attributes can be added to the Body tag, for instance the
 leftmargin or topmargin attributes via;
 </p>


 <pre class="prettyprint"><code>
     $page.addAttribute(&quot;topmargin&quot;, 0)
 </code></pre>


 <p>
 Note though that the addAttribute method only adds attributes to the Body tag.
 For a full list of methods exposed to the page reference view the Javadocs for
 TemplatePageAttributes. Other methods exposed to the page reference are;
 </p>


 <p>
 </p>
 <ul>
     addAttribute(String name, String value) <br />
     getTitle() <br />
     setBackground(String url) <br />
     setBgColor(String color) <br />
     setDescription(String description) <br />
     setKeywords(String description) <br />
     setLinkColor(String color) <br />
     setStyleSheet(String url) <br />
     setTextColor(String color) <br />
     setTitle(String title) <br />
     setVLinkColor(String color) <br />
 </ul>

 </section>

 <section><a id="Adding_your_own_Objects_to_the_Context"></a>
 <h1>Adding your own Objects to the Context</h1>

 <p>
 As the Context is stored as a Hashtable any Object can be placed inside
 it and be accessed from a template. For instance, in a Velocity Screen
 in the doBuildTemplate() method, a String could be added to the Context.
 Please refer to the <a href="../getting-started.html">Getting
 Started</a> documentation for more examples of using the Velocity
 Context with screens and events.
 </p>


 <pre class="prettyprint"><code>
     context.put(&quot;hello&quot;,new String(&quot;testing&quot;));
 </code></pre>


 <p>
 This can be referenced from within the template via;
 </p>


 <pre class="prettyprint"><code>
     $hello the hello reference
 </code></pre>


 <p>
 which would be output as;
 </p>


 <pre class="prettyprint"><code>
     testing the hello reference
 </code></pre>
 </section>

 <section><a id="Using_an_Image_Object_in_the_Context"></a>
 <h1>Using an Image Object in the Context</h1>

 <p>
 Creating an HTML link to an image from a template could be done by;
 </p>


 <pre class="prettyprint"><code>
    $link.getServerScheme()
    ://
    $link.getServerName()
    :
    $link.getServerPort()
    /context/imagename.jpg
 </code></pre>


 <p>
 This has been split up into multiple lines for clarity. Doing this once is a
 pain, doing it twice stinks, if the screen requires several images .... and
 there are many screens .... it is a productivity killer. The Velocity Context
 can be used to store this information and expose it to all the Screens
 requiring it. To do this we can create an Image Object which extends the Turbine
 DynamicURI Object. The following class is Jakarta Tomcat specific;
 </p>


 <pre class="prettyprint"><code>
 //Turbine
 import org.apache.turbine.util.DynamicURI;
 import org.apache.turbine.util.RunData;


 public class Image extends DynamicURI
 {

     /** The images directory */
     public static final String DIR = &quot;images&quot;;

     /** tomcat specific - tomcat context */
     private String contextpath;

     /** Constructor */
     public Image (RunData data)
     {
         super(data);

         //the Tomcat context
         contextpath = data.getRequest().getContextPath();
     }

     /** set the image and URI */
     public String setImage(String imagename)
     {
         return (
         getServerScheme() + //http
         &quot;://&quot; +
         getServerName()  + //www.foo.com
         &quot;:&quot; +
         getServerPort() + //port webserver running on

         //the context for tomcat adds a / so no need to add another

         contextpath  +  //the tomcat context
         &quot;/&quot; +
         Images.DIR +
         &quot;/&quot; +
         imagename);
     }
 }
 </code></pre>


 <p>
 This can be instantiated from within the doBuildTemplate method in a Velocity
 Screen and added to the context from there;
 </p>


 <pre class="prettyprint"><code>
     public void doBuildTemplate(RunData data, Context context) throws Exception
     {
         Image image = new Image(data);
         context.put(&quot;image&quot;,image);
     }
 </code></pre>


 <p>
 from this the Image Object is accessible from within the corresponding screen
 template and can be accessed by;
 </p>


 <pre class="prettyprint"><code>
     $image.setImage(&quot;imagename.jpg&quot;);
 </code></pre>


 <p>
 Which is much simpler than the original attempt at dynamically creating an image
 URL. To make this Image object accessible across all Screens, sublass the
 VelocityScreen Object with one that overrides the doBuildTemplate() method by
 adding the Image object to the Velocity Context. Then use this class as the
 parent class for the Screens that need access to the Image Object. For more
 detail on taking advantage and extending the VelocityScreen Object, please view
 the <a href="../getting-started.html">Getting Started</a> Document.
 </p>


 <p>
 The above Image Object can also be modified to include any static data required
 by the templates. For instance CSS files, JavaScript files etc. Instead of an
 Image Object, it can be rewritten as a StaticLink Object;
 </p>


 <pre class="prettyprint"><code>
 //Turbine
 import org.apache.turbine.util.DynamicURI;
 import org.apache.turbine.util.RunData;


 public class StaticLink extends DynamicURI
 {

     /** the images directory */
     public static final String IMAGES = &quot;images&quot;;

     /** the css directory */
     public static final String CSS = &quot;css&quot;;

     // etc

     /** tomcat specific - tomcat context */
     private String contextpath;

     /** Constructor */
     public Image (RunData data)
     {
         super(data);

         //the Tomcat context
         contextpath = data.getRequest().getContextPath();
     }

     /** set the image and URI */
     public String setImage(String imagename)
     {
         //URI Logic
     }

     /** set the CSS style and URI*/
     public String setCss(String stylesheet)
     {
         //URI Logic
     }

     /** general set method, input as string
      *  ie can be set as $staticlink.setStaticLink(&quot;images/imagename&quot;)
      */
     public String setStaticLink(String staticlink)
     {
         //URI Logic
     }

 }

 </code></pre>
 </section>

 <section><a id="Using_the_Context_Object_with_the_Base.2FPeer_OM"></a>
 <h1>Using the Context Object with the Base/Peer OM</h1>

 <p>
 As a more complex example, assume we are building a book archive system,
 where users can search for books by author and title. If we search on author
 &quot;Greg Egan&quot; and title &quot;Permutation City&quot;, we can query the database through the
 base\peer system and return a Book Object that contains the information on the
 book &quot;Permutation City&quot;. The Book Object would be placed in the context via;
 </p>


 <pre class="prettyprint"><code>
     Book book = new Book();

     //add the data to the Book Object
     //from the Base/Peer Objects for Book

     context.put(&quot;book&quot;, book);

 </code></pre>


 <p>
 and then accessed in the velocity template by;
 </p>


 <pre class="prettyprint"><code>
     $book.getAuthor()
     $book.getTitle()
 </code></pre>


 <p>
 where the two methods are public methods in the Book Object, in this case built
 by the <a href="torque.html">Torque Tool</a>. These methods would return;
 </p>


 <pre class="prettyprint"><code>
     Greg Egan
     Permutation City
 </code></pre>


 <p>
 It is important not to try and put Objects with value null into the Context.
 A NullPointerException will be returned. This above example is intended to get
 across how the Velocity Context can be used to store data from the Base/Peer
 system that can be accessed from the Templates.
 </p>
 </section>


         </main>
       </div>
     </div>
     <hr/>
     <footer>
       <div class="container-fluid">
         <div class="row-fluid">
             <p>©      2000–2025
 <a href="https://www.apache.org/">The Apache Software Foundation</a>
 </p>
         </div>
       </div>
     </footer>
   </body>
 </html>
	<!DOCTYPE html>


	<!--
	\| Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/howto/context-howto.xml at 17 Jun 2025
	\| Rendered using Apache Maven Fluido Skin 2.1.0
	-->
	<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
	<head>
	<meta charset="UTF-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
	<title>Context Howto – Apache Turbine</title>
	<link rel="stylesheet" href="../css/apache-maven-fluido-2.1.0.min.css" />
	<link rel="stylesheet" href="../css/site.css" />
	<link rel="stylesheet" href="../css/print.css" media="print" />
	<script src="../js/apache-maven-fluido-2.1.0.min.js"></script>
	<link rel="icon" type="image/png" sizes="48x48" href="./images/favicon.ico">
	<link rel="icon" type="image/png" sizes="48x48" href="../images/favicon.ico">
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<style>.github-fork-ribbon:before { background-color: orange; }</style>
	</head>
	<body>
	<a class="github-fork-ribbon right-top" href="https://github.com/apache/turbine-build" data-ribbon="Fork me on GitHub">Fork me on GitHub</a>
	<div class="container-fluid container-fluid-top">
	<header>
	<div id="banner">
	<div class="pull-left"><div id="bannerLeft"><h1><a href="https://turbine.apache.org/"><img src="../images/turbine-project-apache-separate.png" alt="Apache Turbine" /></a></h1></div></div>
	<div class="pull-right"><div id="bannerRight"><h1><a href="https://turbine.apache.org/"><img src="../images/logo.gif" /></a></h1></div></div>
	<div class="clear"><hr/></div>
	</div>

	<div id="breadcrumbs">
	<ul class="breadcrumb">
	<li id="publishDate">Last Published: 01 Apr 2025<span class="divider">\|</span>
	</li>
	<li id="projectVersion">Version: 7.0</li>
	<li class="pull-right"><span class="divider">\|</span>
	<a href="https://turbine.apache.org/fulcrum/">Fulcrum</a></li>
	<li class="pull-right"><span class="divider">\|</span>
	<a href="https://turbine.apache.org/">Turbine</a></li>
	<li class="pull-right"><a href="https://www.apache.org">Apache</a></li>
	</ul>
	</div>
	</header>
	<div class="row-fluid">
	<header id="leftColumn" class="span2">
	<nav class="well sidebar-nav">
	<ul class="nav nav-list">
	<li class="nav-header">General Information</li>
	<li><a href="../index.html">Overview</a></li>
	<li><a href="../features.html">Features</a></li>
	<li><a href="../fsd.html">Specification</a></li>
	<li><a href="../getting-started.html">Getting Started</a></li>
	<li><a href="../how-to-build.html">Howto Build Turbine</a></li>
	<li><a href="../changes-report.html">Changes</a></li>
	<li class="nav-header">Documentation</li>
	<li><a href="../services/index.html"><span class="icon-chevron-right"></span>Services</a></li>
	<li><a href="../howto/index.html"><span class="icon-chevron-down"></span>Howtos</a>
	<ul class="nav nav-list">
	<li><a href="../howto/action-event-howto.html">Action Events Howto</a></li>
	<li><a href="../howto/annotations.html">Annotations Howto</a></li>
	<li><a href="../howto/configuration-howto.html">Configuration Howto</a></li>
	<li><a href="../howto/extend-user-howto.html">Extend User Howto</a></li>
	<li><a href="../howto/hibernate-howto.html">Hibernate OM Howto</a></li>
	<li><a href="../howto/intake-howto.html">Intake Howto</a></li>
	<li><a href="../howto/jsp-howto.html">JSP Howto</a></li>
	<li><a href="../howto/migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li>
	<li><a href="../howto/migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li>
	<li><a href="../howto/migrate-from-2_3-howto.html">Migrating from 2.3 to 4.0</a></li>
	<li><a href="../howto/migrate-from-4_0-howto.html">Migrating from 4.0 to 5.0</a></li>
	<li><a href="../howto/pullmodel-howto.html">Pull Model Howto</a></li>
	<li><a href="../howto/python-howto.html">Python Howto</a></li>
	<li><a href="../howto/security-howto.html">Security Howto</a></li>
	<li><a href="../howto/services-howto.html">Services Howto</a></li>
	<li><a href="../howto/url-mapper-howto.html">URL Mapper Howto</a></li>
	<li><a href="../howto/url-rewriting-howto.html">URL Rewriting Howto</a></li>
	<li class="active"><a>Velocity Context Howto</a></li>
	<li><a href="../howto/velocity-site-howto.html">Velocity Site Howto</a></li>
	<li><a href="../howto/velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a></li>
	</ul></li>
	<li><a href="https://cwiki.apache.org/confluence/display/TURBINE">Wiki</a></li>
	<li><a href="../apidocs/index.html">JavaDocs</a></li>
	<li class="nav-header">Development</li>
	<li><a href="../proposals.html">Proposals</a></li>
	<li><a href="../how-to-help.html">How To Help</a></li>
	<li><a href="../todo.html">Todo</a></li>
	<li class="nav-header">Project Documentation</li>
	<li><a href="../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li>
	<li><a href="../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li>
	<li class="nav-header">Apache</li>
	<li><a href="https://www.apache.org/">Apache Website</a></li>
	<li><a href="https://www.apache.org/licenses/">License</a></li>
	<li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li>
	<li><a href="https://www.apache.org/security/">Security</a></li>
	</ul>
	</nav>
	<div class="well sidebar-nav">
	<form id="search-form" action="https://www.google.com/search" method="get" >
	<input value="http://turbine.apache.org/turbine/turbine-7-0" name="sitesearch" type="hidden" />
	<input class="search-query" name="q" id="query" type="text" placeholder="Search with Google..." />
	</form>
	<div id="poweredBy">
	<div class="clear"></div>
	<div class="clear"></div>
	<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
	</div>
	</div>
	</header>
	<main id="bodyColumn" class="span10">




	<section><a id="Using_the_Turbine_Context"></a>
	<h1>Using the Turbine Context</h1>

	<p>
	The Turbine Templating Services attach references to default Objects in the
	Turbine Context as part of their initialization. In the case of the
	TurbineVelocityService these references point to RunData, TemplateLink and
	TemplatePageAttributes. These three are put into the Context in the
	TurbineVelocityService class. The Context stores the Objects in a Hashtable
	with a key and the Object.
	</p>
	</section>

	<section><a id="Using_the_RunData_Object"></a>
	<h1>Using the RunData Object</h1>

	<p>
	The RunData Object is referenced by the "data" keyword, which when using this
	in the templating system is referenced by $data. As the Context contains a link
	to the RunData object all the public methods in the RunData Object are made
	available to the template. For example, typing $data.getMessage() will access
	the message String being stored in the RunData Object and print that as part
	of the templates output.
	</p>


	<p>
	RunData exposes an extremely rich series of methods and fields, for a full list
	of these methods refer to the Javadocs for RunData. Some of the useful methods
	exposed in RunData include;
	</p>


	<p>
	</p>
	<ul>
	addMessage(String msg) <br />
	getMessage() <br />
	getParameters() <br />
	getServerName() <br />
	getTitle() <br />
	getUser() <br />
	removeUserFromSession() <br />
	setMessage(String message) <br />
	setRedirectUri(String ruri) <br />
	setTitle(String title) <br />
	setLayoutTemplate(String title) <br />
	</ul>



	<p>
	The RunData also allows for access to the TemplateInfo Object via
	getTemplateInfo() and several convenience methods. This allows for properties
	of the Templates to be modified for a Request when using templating systems like
	Velocity, WebMacro or Freemarker.
	</p>


	<p>
	As an example assume we want a printable page that contains only the Templating
	Screen and not all the navigational components. To achieve this we can strip
	out all the non screen templating components by describing a new Layout Template
	called PrintableLayout.vm in the templates/layouts directory. All the
	PrintableLayout needs contain is;
	</p>


	<pre class="prettyprint"><code>
	$screen_placeholder
	</code></pre>


	<p>
	Without the references to the $navigation.setTemplate() methods in the template
	no navigational screen will be called. In the Screen Template that wants to take
	advantage of the PrintableLayout Template add to the Template;
	</p>


	<pre class="prettyprint"><code>
	$data.setLayoutTemplate("/PrintableLayout.vm")
	</code></pre>


	<p>
	This will strip the Screen Template of its Navigational components. These
	convenience methods can also be used to expose and to set the Layout when the
	Template is processed. Through this a User can potentially choose how they would
	like their webpage to appear by choosing one of many differant Layouts or
	choices you, the webdesigner provide.
	</p>
	</section>

	<section><a id="Using_the_TemplateLink_Object"></a>
	<h1>Using the TemplateLink Object</h1>

	<p>
	The TemplateLink is an extended version of DynamicURI customised to be used in
	the templates. The TemplateLink is referenced in the templates via $link and
	exposes convenience methods for building URI's on the fly. For example in a
	template to build the URI to another template, TemplateLink would be referenced
	via;
	</p>


	<pre class="prettyprint"><code>
	$link.setPage("newpage.vm")
	</code></pre>


	<p>
	which when added to a Velocity template would (depending on the servlet
	configuration) return;
	</p>


	<p>

	<blockquote>
	http://127.0.0.1:8080/newapp/servlet/newapp/template/index.vm
	</blockquote>
	</p>


	<p>
	where "newapp" is the chosen webapp deployment name.
	</p>


	<p>
	This same mechanism can also be used to link to static html;
	</p>


	<pre class="prettyprint"><code>
	$link.setPage("/path/to/static.html")
	</code></pre>


	<p>
	However the HTML page will load itself into a screen and not be embedded withint the Layouts and Navigations. If you still wish static content to be embedded within the specified layouts and navigations it is easier to add the static content as a velocity template and not take advantage of any of the dynamic content addition the Velocity Context allows.
	</p>



	<p>
	TemplateLink and DynamicURI again expose a rich set of methods and fields to
	the link reference, for a full list of fields and methods please refer to
	TemplateLink and DynamicURI in the javadocs. Some of the useful methods
	exposed are;
	</p>


	<p>
	</p>
	<ul>
	setPage(String templatename) <br />
	addPathInfo(ParameterParser pp) <br />
	addPathInfo(String name, String value) <br />
	addQueryData(ParameterParser pp) <br />
	addQueryData(String name, String value) <br />
	getScriptName() <br />
	getServerData() <br />
	getServerPort() <br />
	setAction(String action) <br />
	setScreen(String screen) <br />
	setSecure() <br />
	</ul>

	</section>

	<section><a id="Using_the_TemplatePageAttributes_Object"></a>
	<h1>Using the TemplatePageAttributes Object</h1>

	<p>
	The TemplatePageAttributes is accessed from within the context by the keyword
	"page" and provides methods to modify the various HTML attributes of the
	templating system. The Template context can be used to dictate the style of
	the HTML page in the navigation and layout templates as well as modify these
	attributes from within a screen.
	</p>


	<p>
	As an example in the default.vm the page can be set to a maroon background with;
	</p>


	<pre class="prettyprint"><code>
	$page.setBgColor("#800000")
	</code></pre>


	<p>
	the screen template may need to set a new title to the page being displayed in
	the browser, this can be done in the screen template via;
	</p>


	<pre class="prettyprint"><code>
	$page.setTitle("New Title to Page")
	</code></pre>


	<p>
	Non standard attributes can be added to the Body tag, for instance the
	leftmargin or topmargin attributes via;
	</p>


	<pre class="prettyprint"><code>
	$page.addAttribute("topmargin", 0)
	</code></pre>


	<p>
	Note though that the addAttribute method only adds attributes to the Body tag.
	For a full list of methods exposed to the page reference view the Javadocs for
	TemplatePageAttributes. Other methods exposed to the page reference are;
	</p>


	<p>
	</p>
	<ul>
	addAttribute(String name, String value) <br />
	getTitle() <br />
	setBackground(String url) <br />
	setBgColor(String color) <br />
	setDescription(String description) <br />
	setKeywords(String description) <br />
	setLinkColor(String color) <br />
	setStyleSheet(String url) <br />
	setTextColor(String color) <br />
	setTitle(String title) <br />
	setVLinkColor(String color) <br />
	</ul>

	</section>

	<section><a id="Adding_your_own_Objects_to_the_Context"></a>
	<h1>Adding your own Objects to the Context</h1>

	<p>
	As the Context is stored as a Hashtable any Object can be placed inside
	it and be accessed from a template. For instance, in a Velocity Screen
	in the doBuildTemplate() method, a String could be added to the Context.
	Please refer to the <a href="../getting-started.html">Getting
	Started</a> documentation for more examples of using the Velocity
	Context with screens and events.
	</p>


	<pre class="prettyprint"><code>
	context.put("hello",new String("testing"));
	</code></pre>


	<p>
	This can be referenced from within the template via;
	</p>


	<pre class="prettyprint"><code>
	$hello the hello reference
	</code></pre>


	<p>
	which would be output as;
	</p>


	<pre class="prettyprint"><code>
	testing the hello reference
	</code></pre>
	</section>

	<section><a id="Using_an_Image_Object_in_the_Context"></a>
	<h1>Using an Image Object in the Context</h1>

	<p>
	Creating an HTML link to an image from a template could be done by;
	</p>


	<pre class="prettyprint"><code>
	$link.getServerScheme()
	://
	$link.getServerName()
	:
	$link.getServerPort()
	/context/imagename.jpg
	</code></pre>


	<p>
	This has been split up into multiple lines for clarity. Doing this once is a
	pain, doing it twice stinks, if the screen requires several images .... and
	there are many screens .... it is a productivity killer. The Velocity Context
	can be used to store this information and expose it to all the Screens
	requiring it. To do this we can create an Image Object which extends the Turbine
	DynamicURI Object. The following class is Jakarta Tomcat specific;
	</p>



	<pre class="prettyprint"><code>
	//Turbine
	import org.apache.turbine.util.DynamicURI;
	import org.apache.turbine.util.RunData;


	public class Image extends DynamicURI
	{

	/** The images directory */
	public static final String DIR = "images";

	/** tomcat specific - tomcat context */
	private String contextpath;

	/** Constructor */
	public Image (RunData data)
	{
	super(data);

	//the Tomcat context
	contextpath = data.getRequest().getContextPath();
	}

	/** set the image and URI */
	public String setImage(String imagename)
	{
	return (
	getServerScheme() + //http
	"://" +
	getServerName() + //www.foo.com
	":" +
	getServerPort() + //port webserver running on

	//the context for tomcat adds a / so no need to add another

	contextpath + //the tomcat context
	"/" +
	Images.DIR +
	"/" +
	imagename);
	}
	}
	</code></pre>


	<p>
	This can be instantiated from within the doBuildTemplate method in a Velocity
	Screen and added to the context from there;
	</p>


	<pre class="prettyprint"><code>
	public void doBuildTemplate(RunData data, Context context) throws Exception
	{
	Image image = new Image(data);
	context.put("image",image);
	}
	</code></pre>


	<p>
	from this the Image Object is accessible from within the corresponding screen
	template and can be accessed by;
	</p>


	<pre class="prettyprint"><code>
	$image.setImage("imagename.jpg");
	</code></pre>


	<p>
	Which is much simpler than the original attempt at dynamically creating an image
	URL. To make this Image object accessible across all Screens, sublass the
	VelocityScreen Object with one that overrides the doBuildTemplate() method by
	adding the Image object to the Velocity Context. Then use this class as the
	parent class for the Screens that need access to the Image Object. For more
	detail on taking advantage and extending the VelocityScreen Object, please view
	the <a href="../getting-started.html">Getting Started</a> Document.
	</p>


	<p>
	The above Image Object can also be modified to include any static data required
	by the templates. For instance CSS files, JavaScript files etc. Instead of an
	Image Object, it can be rewritten as a StaticLink Object;
	</p>


	<pre class="prettyprint"><code>
	//Turbine
	import org.apache.turbine.util.DynamicURI;
	import org.apache.turbine.util.RunData;


	public class StaticLink extends DynamicURI
	{

	/** the images directory */
	public static final String IMAGES = "images";

	/** the css directory */
	public static final String CSS = "css";

	// etc

	/** tomcat specific - tomcat context */
	private String contextpath;

	/** Constructor */
	public Image (RunData data)
	{
	super(data);

	//the Tomcat context
	contextpath = data.getRequest().getContextPath();
	}

	/** set the image and URI */
	public String setImage(String imagename)
	{
	//URI Logic
	}

	/** set the CSS style and URI*/
	public String setCss(String stylesheet)
	{
	//URI Logic
	}

	/** general set method, input as string
	* ie can be set as $staticlink.setStaticLink("images/imagename")
	*/
	public String setStaticLink(String staticlink)
	{
	//URI Logic
	}

	}

	</code></pre>
	</section>

	<section><a id="Using_the_Context_Object_with_the_Base.2FPeer_OM"></a>
	<h1>Using the Context Object with the Base/Peer OM</h1>

	<p>
	As a more complex example, assume we are building a book archive system,
	where users can search for books by author and title. If we search on author
	"Greg Egan" and title "Permutation City", we can query the database through the
	base\peer system and return a Book Object that contains the information on the
	book "Permutation City". The Book Object would be placed in the context via;
	</p>


	<pre class="prettyprint"><code>
	Book book = new Book();

	//add the data to the Book Object
	//from the Base/Peer Objects for Book

	context.put("book", book);

	</code></pre>


	<p>
	and then accessed in the velocity template by;
	</p>


	<pre class="prettyprint"><code>
	$book.getAuthor()
	$book.getTitle()
	</code></pre>


	<p>
	where the two methods are public methods in the Book Object, in this case built
	by the <a href="torque.html">Torque Tool</a>. These methods would return;
	</p>


	<pre class="prettyprint"><code>
	Greg Egan
	Permutation City
	</code></pre>


	<p>
	It is important not to try and put Objects with value null into the Context.
	A NullPointerException will be returned. This above example is intended to get
	across how the Velocity Context can be used to store data from the Base/Peer
	system that can be accessed from the Templates.
	</p>
	</section>


	</main>
	</div>
	</div>
	<hr/>
	<footer>
	<div class="container-fluid">
	<div class="row-fluid">
	<p>© 2000–2025
	<a href="https://www.apache.org/">The Apache Software Foundation</a>
	</p>
	</div>
	</div>
	</footer>
	</body>
	</html>