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

 <?xml version="1.0"?>
 <!--
 /*
  * Copyright 2001-2006 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>Pull Model Howto</title>
  </properties>

 <body>

 <section name="Using the pull model with Turbine 2">

 <p>
 Turbine 2 can be used with two different programming models - the push model
 and the pull model.  The difference is in how the Context is built up.  The
 Context is used by the Velocity or WebMacro template files to "fill in the
 blanks" and introduce dynamic data into a static HTML-based template.  This
 programming concept is incredibly powerful - because it allows the web
 designer, who may be experienced with HTML, CSS, and Javascript but not
 Java, to put data fields wherever they want on a page without having to ask
 the Java programmers to change a Java class and recompile.  For more
 information on which to choose for your Turbine application, read Jon
 Stevens' informative commentary <a href="../pullmodel.html">Push vs
 Pull</a>.
 </p>

 <p>
 Also see the <a href="../services/pull-service.html">Pull Service</a>
 Documentation
 for another explanation of how the Pull Service works with Tools.
 </p>

 <p>
 The push model is based on a one-to-one mapping of Java Screen
 classes and Velocity template files.  The Screen class puts key/value pairs
 into the Context.  The <a href="context-howto.html">Context Howto</a>
 explains this approach.
 </p>

 <p>
 The pull model allows the web designer even more freedom than the push
 model. Java programmers can create globally accessible Java classes known as
 Tools.   These Tools are going to be useful for getting data out of a
 service and bringing it to the presentation layer, authenticating users, or
 creating links (see the TemplateLink tool that is built into Turbine).
 </p>
 </section>

 <section name="Pull Tool Implementation">
 <p>
 Your SimpleSecurityTool should implement ApplicationTool, which is a simple
 interface with two methods, init(Object data) and refresh.  It could be a
 facade class that calls other classes, or it could have its own business
 logic.
 </p>
 </section>

 <section name="Entries in TurbineResources.properties">
 <p>
 To make the Tool available to Turbine, you need to define your Tools in the
 TurbineResources.properties file.  The "Pull Service" section of the
 properties file is where the tools are listed.  You can use the following
 syntax (all explained in the TurbineResources.properties):
 </p>


 <source><![CDATA[
 tool.<Scope>.<Id> = <Classname>

 tool.request.formsTool = com.yourcompany.turbine.tools.SimpleFormsTool
 ]]></source>

 <p>
 Classname is your java classname -
 com.yourcompany.turbine.tools.SimpleFormsTool
 </p>

 <p>
 Id is a unique identifier that you will use in your Velocity templates -
 formsTool, for instance.
 </p>

 <p>
 Scope defines the life cycle of the Tool.  There are four, global, request,
 session, and persistent.
 </p>

 <p>
 Global: The tool is instantiated once and is available to all templates for
 all requests. Must be threadsafe.
 </p>

 <p>
 Request: The tool is instantiated once for every request to Turbine.
 Doesn't need to be threadsafe.  The link, page, and flux tools are all
 defined as request scope.
 </p>

 <p>
 Session: The tool is instantiated once for each user session. Should be
 threadsafe.  Useful for tools that might hold user profiles, or items in a
 shopping cart.
 </p>

 <p>
 Persistent: Tool is instantiated once for each user session, and is stored
 along with the user information.  Must be threadsafe and implement
 Serializable.  An example of how this scope would be used would be great!
 </p>

 <p>
 Additional tool-defined properties can be configured in the
 TurbineResources.properties. The syntax is defined under the "Pull Service"
 section.
 </p>

 </section>

 </body>
 </document>
	<?xml version="1.0"?>
	<!--
	/*
	* Copyright 2001-2006 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>Pull Model Howto</title>
	</properties>

	<body>

	<section name="Using the pull model with Turbine 2">

	<p>
	Turbine 2 can be used with two different programming models - the push model
	and the pull model. The difference is in how the Context is built up. The
	Context is used by the Velocity or WebMacro template files to "fill in the
	blanks" and introduce dynamic data into a static HTML-based template. This
	programming concept is incredibly powerful - because it allows the web
	designer, who may be experienced with HTML, CSS, and Javascript but not
	Java, to put data fields wherever they want on a page without having to ask
	the Java programmers to change a Java class and recompile. For more
	information on which to choose for your Turbine application, read Jon
	Stevens' informative commentary <a href="../pullmodel.html">Push vs
	Pull</a>.
	</p>

	<p>
	Also see the <a href="../services/pull-service.html">Pull Service</a>
	Documentation
	for another explanation of how the Pull Service works with Tools.
	</p>

	<p>
	The push model is based on a one-to-one mapping of Java Screen
	classes and Velocity template files. The Screen class puts key/value pairs
	into the Context. The <a href="context-howto.html">Context Howto</a>
	explains this approach.
	</p>

	<p>
	The pull model allows the web designer even more freedom than the push
	model. Java programmers can create globally accessible Java classes known as
	Tools. These Tools are going to be useful for getting data out of a
	service and bringing it to the presentation layer, authenticating users, or
	creating links (see the TemplateLink tool that is built into Turbine).
	</p>
	</section>

	<section name="Pull Tool Implementation">
	<p>
	Your SimpleSecurityTool should implement ApplicationTool, which is a simple
	interface with two methods, init(Object data) and refresh. It could be a
	facade class that calls other classes, or it could have its own business
	logic.
	</p>
	</section>

	<section name="Entries in TurbineResources.properties">
	<p>
	To make the Tool available to Turbine, you need to define your Tools in the
	TurbineResources.properties file. The "Pull Service" section of the
	properties file is where the tools are listed. You can use the following
	syntax (all explained in the TurbineResources.properties):
	</p>


	<source><![CDATA[
	tool.<Scope>.<Id> = <Classname>

	tool.request.formsTool = com.yourcompany.turbine.tools.SimpleFormsTool
	]]></source>

	<p>
	Classname is your java classname -
	com.yourcompany.turbine.tools.SimpleFormsTool
	</p>

	<p>
	Id is a unique identifier that you will use in your Velocity templates -
	formsTool, for instance.
	</p>

	<p>
	Scope defines the life cycle of the Tool. There are four, global, request,
	session, and persistent.
	</p>

	<p>
	Global: The tool is instantiated once and is available to all templates for
	all requests. Must be threadsafe.
	</p>

	<p>
	Request: The tool is instantiated once for every request to Turbine.
	Doesn't need to be threadsafe. The link, page, and flux tools are all
	defined as request scope.
	</p>

	<p>
	Session: The tool is instantiated once for each user session. Should be
	threadsafe. Useful for tools that might hold user profiles, or items in a
	shopping cart.
	</p>

	<p>
	Persistent: Tool is instantiated once for each user session, and is stored
	along with the user information. Must be threadsafe and implement
	Serializable. An example of how this scope would be used would be great!
	</p>

	<p>
	Additional tool-defined properties can be configured in the
	TurbineResources.properties. The syntax is defined under the "Pull Service"
	section.
	</p>

	</section>

	</body>
	</document>