seade 2003/08/27 00:25:44
Modified: xdocs/howto index.xml navigation.xml
migrate-from-2_1-howto.xml
Added: xdocs/howto migrate-from-2_2-howto.xml
velocityonlylayout-howto.xml
Log:
Converted a couple of docs over from the wiki and tidied up the navigation.
Revision Changes Path
1.9 +7 -5 jakarta-turbine-2/xdocs/howto/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/howto/index.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- index.xml 7 Jun 2003 06:38:13 -0000 1.8
+++ index.xml 27 Aug 2003 07:25:44 -0000 1.9
@@ -13,21 +13,23 @@
<p>
<ul>
<li><a href="action-event-howto.html">Action Events Howto</a></li>
+ <li><a href="configuration-howto.html">Configuration Howto</a></li>
<li><a href="extend-user-howto.html">Extend User Howto</a></li>
+ <li><a href="intake-howto.html">Intake Howto</a></li>
<li><a href="jboss-howto.html">JBoss Howto</a></li>
<li><a href="jsp-howto.html">JSP Howto</a></li>
- <li><a href="intake-howto.html">Intake Howto</a></li>
- <li><a href="migrate-from-2_1-howto.html">Migrating from 2.1</a></li>
+ <li><a href="migrate-from-2_1-howto.html">Migrating from 2.1 to 2.2</a></li>
+ <li><a href="migrate-from-2_2-howto.html">Migrating from 2.2 to 2.3</a></li>
<li><a href="pullmodel-howto.html">Pull Model Howto</a></li>
<li><a href="python-howto.html">Python Howto</a></li>
<li><a href="security-howto.html">Security Howto</a></li>
<li><a href="services-howto.html">Services Howto</a></li>
<li><a href="url-rewriting-howto.html">URL rewriting Howto</a></li>
- <li><a href="velocity-site-howto.html">Velocity Site Howto</a></li>
<li><a href="context-howto.html">Velocity Context Howto</a></li>
+ <li><a href="velocity-site-howto.html">Velocity Site Howto</a></li>
+ <li><a href="velocityonlylayout-howto.html">VelocityOnlyLayout
Howto</a></li>
<li><a href="hibernate-howto.html">Hibernate OM Howto</a></li>
- <li><a href="hibernate-howto.html">Configuration Howto</a></li>
- <li><a
href="http://nagoya.apache.org/wiki/apachewiki.cgi?CategoryJakartaTurbine2HowTo";>
+ <li><a
href="http://nagoya.apache.org/wiki/apachewiki.cgi?search=CategoryJakartaTurbine2HowTo";>
Additional Howtos from the Apache Wiki</a></li>
</ul>
</p>
1.6 +8 -3 jakarta-turbine-2/xdocs/howto/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/howto/navigation.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- navigation.xml 24 Jun 2003 08:16:59 -0000 1.5
+++ navigation.xml 27 Aug 2003 07:25:44 -0000 1.6
@@ -32,18 +32,23 @@
<item name="Services" href="/services/index.html"/>
<item name="Howtos" href="/howto/index.html">
<item name="Action Events Howto" href="/howto/action-event-howto.html"/>
+ <item name="Configuration Howto" href="/howto/configuration-howto.html"/>
<item name="Extend User Howto" href="/howto/extend-user-howto.html"/>
+ <item name="Hibernate OM Howto" href="/howto/hibernate-howto.html"/>
+ <item name="Intake Howto" href="/howto/intake-howto.html"/>
<item name="JBoss Howto" href="/howto/jboss-howto.html"/>
<item name="JSP Howto" href="/howto/jsp-howto.html"/>
- <item name="Intake Howto" href="/howto/intake-howto.html"/>
+ <item name="Migrating 2.1 to 2.2"
href="/howto/migrate-from-2_1-howto.html"/>
+ <item name="Migrating 2.2 to 2.3"
href="/howto/migrate-from-2_2-howto.html"/>
<item name="Pull Model Howto" href="/howto/pullmodel-howto.html"/>
<item name="Python Howto" href="/howto/python-howto.html"/>
<item name="Security Howto" href="/howto/security-howto.html"/>
<item name="Services Howto" href="/howto/services-howto.html"/>
- <item name="Migrating from 2.1" href="/howto/migrate-from-2_1-howto.html"/>
<item name="URL rewriting Howto" href="/howto/url-rewriting-howto.html"/>
- <item name="Velocity Site Howto" href="/howto/velocity-site-howto.html"/>
<item name="Velocity Context Howto" href="/howto/context-howto.html"/>
+ <item name="Velocity Site Howto" href="/howto/velocity-site-howto.html"/>
+ <item name="VelocityOnlyLayout Howto"
href="/howto/velocityonlylayout-howto.html"/>
+ <item name="Wiki Howtos"
href="http://nagoya.apache.org/wiki/apachewiki.cgi?search=CategoryJakartaTurbine2HowTo"/>
</item>
</menu>
1.5 +8 -0 jakarta-turbine-2/xdocs/howto/migrate-from-2_1-howto.xml
Index: migrate-from-2_1-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine-2/xdocs/howto/migrate-from-2_1-howto.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- migrate-from-2_1-howto.xml 29 Jan 2003 02:03:45 -0000 1.4
+++ migrate-from-2_1-howto.xml 27 Aug 2003 07:25:44 -0000 1.5
@@ -10,6 +10,14 @@
<body>
+<section name="Important note">
+<p>
+ The information in this HOWTO pertains to Turbine 2.2. Please refer
+ to the <a href="/howto/migrate-from-2_2-howto.html">Migrating from
+ 2.2 to 2.3</a> page for information on migating to Turbine 2.3.
+</p>
+</section>
+
<section name="Introduction">
<p>
This document describes the basic steps needed to migrate an
1.1 jakarta-turbine-2/xdocs/howto/migrate-from-2_2-howto.xml
Index: migrate-from-2_2-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Migrating from 2.2 to 2.3</title>
<author email="[EMAIL PROTECTED]">Eric Pugh</author>
<author email="[EMAIL PROTECTED]">Chris Chew</author>
<author email="[EMAIL PROTECTED]">Scott Eade</author>
</properties>
<body>
<section name="Introduction">
<p>
This document describes the basic steps needed to migrate an
application written for Turbine 2.2 to Turbine 2.3.
</p>
<p>
You may find that migrating to 2.3 is not all that difficult -
it should certainly be less trouble than migrating from 2.1 to
2.2. Most of the pain in figuring out this migration process
has been documented in the mailing list archives, but is
summarized here for your convenience.
</p>
</section>
<section name="Deprecated And Removed Services">
<p>
In 2.3, many services have been deprecated or removed wholly.
Below are the changes I made to get my 2.2 app to work under 2.3.
</p>
<p>
Remove from tr.props ( and any properties that start with services.XXX):
</p>
<source>
<![CDATA[
services.PoolBrokerService.classname=org.apache.turbine.services.db.TurbinePoolBrokerService
services.MapBrokerService.classname=org.apache.turbine.services.db.TurbineMapBrokerService
services.ResourceService.classname=org.apache.turbine.services.resources.TurbineResourceService
services.LoggingService.classname=org.apache.turbine.services.logging.TurbineLoggingService
]]>
</source>
<p>
Note: Removing LoggingService removes all logging stuff from
TurbineResources.properties as well! Now you use a Log4j.properties:
WEB-INF\conf\Log4j.properties. You need at least an empty file,
otherwise log4j complains, but something like this will be better:
</p>
<source>
<![CDATA[
# -------------------------------------------------------------------
# Log4j.properties
# -------------------------------------------------------------------
# This first category is required and the category
# must be named 'default'. This is used for all logging
# where an explicit category is not specified.
log4j.category.default = INFO, default
log4j.category.org.apache.turbine.services.pull.util.UIManager = DEBUG, default
log4j.appender.default = org.apache.log4j.RollingFileAppender
log4j.appender.default.file = logs/turbine.log
log4j.appender.default.MaxFileSize = 1024KB
log4j.appender.default.MaxBackupIndex = 5
log4j.appender.default.append = true
log4j.appender.default.layout = org.apache.log4j.PatternLayout
log4j.appender.default.layout.conversionPattern = %d %-5p [%-10t] %c{2} - %m%n
log4j.appender.email = org.apache.log4j.net.SMTPAppender
log4j.appender.email.BufferSize = 512
log4j.appender.email.From = @your-from-address@
log4j.appender.email.SMTPHost = @your-mail-host@
log4j.appender.email.Subject = Turbine Error Report
log4j.appender.email.To = @your-to-address@
log4j.appender.email.layout = org.apache.log4j.PatternLayout
log4j.appender.email.layout.conversionPattern = %d %-5p [%-10t] %c{2} - %m%n
# This category is used in the BasePeer class. All
# SQL generated will be logged if the category
# priority is set to DEBUG
log4j.category.org.apache.torque.util.BasePeer = DEBUG,
org.apache.torque.util.BasePeer
log4j.additivity.org.apache.torque.util.BasePeer = false
log4j.appender.org.apache.torque.util.BasePeer = org.apache.log4j.RollingFileAppender
log4j.appender.org.apache.torque.util.BasePeer.file = logs/sql.log
log4j.appender.org.apache.torque.util.BasePeer.MaxFileSize = 1024KB
log4j.appender.org.apache.torque.util.BasePeer.MaxBackupIndex = 3
log4j.appender.org.apache.torque.util.BasePeer.append = true
log4j.appender.org.apache.torque.util.BasePeer.layout =
org.apache.log4j.PatternLayout
log4j.appender.org.apache.torque.util.BasePeer.layout.conversionPattern = %d %-5p
[%-10t] %c{1} - %m%n
[EMAIL PROTECTED]@.modules.scheduledjobs = DEBUG, scheduledjobs, email
[EMAIL PROTECTED]@.modules.scheduledjobs = false
log4j.appender.scheduledjobs = org.apache.log4j.RollingFileAppender
log4j.appender.scheduledjobs.file = logs/batch.log
log4j.appender.scheduledjobs.MaxFileSize = 256KB
log4j.appender.scheduledjobs.MaxBackupIndex = 5
log4j.appender.scheduledjobs.append = true
log4j.appender.scheduledjobs.layout = org.apache.log4j.PatternLayout
log4j.appender.scheduledjobs.layout.conversionPattern = %d %-5p [%-10t] %c{1} - %m%n
]]>
</source>
</section>
<section name="Commons-logging Replaces Built-in Logging">
<p>
In 2.3, the built in logging has been deprecated in favor of using
commons-logging. Therefore, where ever you have this import:
</p>
<source>
<![CDATA[
import org.apache.turbine.util.Log;
]]>
</source>
<p>
you will need to remove it and replace it with:
</p>
<source>
<![CDATA[
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
]]>
</source>
<p>
Also, instead of calling static methods of the old Log object:
Log.debug("my message") you will need instead to do this:
</p>
<source>
<![CDATA[
private static Log log = LogFactory.getLog(Audit.class);
.
.
.
log.debug("My message");
]]>
</source>
<p>
The advantage of this is that now in your logging messages, you will know
what class the message is coming from, versus the old way where all you
got was the message and you would have to embed the name of the action to
know what was emitting the logging message! Also, this makes your
underlying logging architecture pluggable. If you use jdk1.4, you can
plug in the java logging, or use log4j. See the example Log4j.properties
file above to see a few of the possibilities.
</p>
</section>
<section name="Use VelocityOnly Layout">
<p>
Change from VelocityECSLayout to VelocityOnly Layout - see:
<a href="velocityonlylayout-howto.html">VelocityOnlyLayout Howto</a>.
</p>
</section>
<section name="New Dependencies">
<p>
In order to make the Turbine jar smaller, some things have been moved to
commons. There are in fact a raft of new dependencies that you should
ensure you use as part of your application - see:
<a href="dependencies.html">Dependencies</a>.
</p>
</section>
<section name="earlyInit Parameter For Selected Services">
<p>
In order to get some services to work under 2.3, it is necessary to set
an earlyInit parameter in TurbineResources.propertiess:
</p>
<source>
<![CDATA[
services.PullService.earlyInit=true
]]>
</source>
<p>
If your service is not being initialized as you would expect then try
setting this flag for it.
</p>
</section>
<section name="New Optional URI Handling Tools">
<p>
Under 2.3 there are new URI handling tools with a significant refactoring
of how relative and absolute URL's are handled in Turbine. Briefly, the
new tools avoid the confusion that arose previoulsy from mixing tools
with internal classes, providing uniform access to the various URI types
in Turbine. <strong>These new tools are backwards-compatible with your old
$link and $content tools, so you should not have to change any of your
templates if you decide to use the new tools.</strong>
</p>
<p>
To use the new tools, simply redefine the following pull tools in your
TurbineResources.properties:
</p>
<source>
<![CDATA[
tool.request.link = org.apache.turbine.services.pull.tools.TemplateLink
tool.request.content = org.apache.turbine.services.pull.tools.ContentTool
]]>
</source>
<p>
If you used some of the other tools for creating URL's, then there are
analogous new ones as well:
</p>
<source>
<![CDATA[
org.apache.turbine.services.pull.tools.RelativeTemplateLink
org.apache.turbine.services.pull.tools.TemplateLinkWithSlash
]]>
</source>
</section>
<section name="Ensure you refer to your templates correctly">
<p>
Places where you might previously have got away with using forward slashes
("/") in your references to template names will need to be corrected (note
that this does not apply to the Velocity #parse() and #include()
statements which operate at a lower level). See:
<a href="../services/template-service.html">Template Service</a>.
</p>
</section>
<section name="Extending Turbine User">
<p>
Refer to <a href="../services/torque-security-service.html">Torque
Security Service</a> for information on extending TurbineUser in Turbine
2.3 - this is now much easier than it was in previous releases. You
may also want to refer to
<a href="http://nagoya.apache.org/eyebrowse/[EMAIL PROTECTED]&msgNo=15077">
this message from the mail archive</a> - the quoted text from Henning is
great and Wei points to a couple of additional messages that may also
prove useful.
</p>
</section>
<section name="Building Torque OM Classes">
<p>
You will need to use Maven b9 or above in order to build the Torque
Security Service and even then you should install the latest available
release of the <a href="http://db.apache.org/torque/maven-howto.html";>
Torque generator</a> plugin.
</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 migrating an application by following this howto.
</p>
</section>
</body>
</document>
1.1 jakarta-turbine-2/xdocs/howto/velocityonlylayout-howto.xml
Index: velocityonlylayout-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>VelocityOnlyLayout</title>
<author email="[EMAIL PROTECTED]">Quinton McCombs</author>
<author email="[EMAIL PROTECTED]">Scott Eade</author>
</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)</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[
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
<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
<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
#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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
