You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by jk...@apache.org on 2006/07/03 02:17:31 UTC
svn commit: r418665 [2/6] - in /tapestry/tapestry4/trunk:
src/documentation/content/xdocs/ src/documentation/content/xdocs/QuickStart/
src/documentation/content/xdocs/UsersGuide/
src/documentation/content/xdocs/examples/ src/site/ src/site/resources/im...
Added: tapestry/tapestry4/trunk/src/site/xdoc/QuickStart/helloworld.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/QuickStart/helloworld.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/QuickStart/helloworld.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/QuickStart/helloworld.xml Sun Jul 2 17:17:29 2006
@@ -0,0 +1,348 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2005 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>Quick Start: Hello World</title>
+</properties>
+<body>
+
+<p>
+In this tutorial, we'll cover setting up the most basic Tapestry application,
+a simple "Hello World" application that displays the current time. We'll then
+extend it just a bit, adding a touch of interactivity.
+</p>
+
+<p>
+The final source for this tutorial is packaged as <strong>helloworld.tar.gz</strong>.
+</p>
+
+<section name="Tapestry Application Basics">
+
+
+<p>
+Our first application will look like the following when it runs:
+</p>
+
+<img src="../images/QuickStart/helloworld1.png" alt="HelloWorld step 1 screen shot."/>
+
+<p>
+Tapestry applications always include a page named "Home". The Home page is the first page
+displayed by the application, when it is first started (that is, when the client web browser
+first accesses the starting URL).
+</p>
+
+<p>
+Tapestry pages are always a combination of a Java class and a template (we could say, "an HTML template",
+but Tapestry is not limited to just HTML). In many cases, Tapestry will use a built-in Java class
+when you don't provide one; for a trivial page like ours, we don't need to supply a Java class at all.
+</p>
+
+<p>
+ We'll start with the HTML template then, which is a file named Home.html in the root of the web application context.
+ In the project, it is stored as src/context/Home.html:
+</p>
+
+<source xml:space="preserve">
+<html>
+ <head>
+ <title>Tutorial: HelloWorld</title>
+ </head>
+ <body>
+ <h1>HelloWorld Tutorial</h1>
+ </body>
+</html>
+</source>
+
+<p>
+There's nothing special in this HTML template, nothing dynamic (not yet, anyway). We could access it
+as http://localhost:8080/helloworld/Home.html and see the same thing; but notice that in the screen shot
+the URL is <a href="http://localhost:8080/hellworld/app">http://localhost:8080/hellworld/app</a>.
+That means that a servlet, mapped to the /app path
+within the web application, was responsible for the output you can see in the web browser.
+</p>
+
+<p>
+Tapestry applications always use a specific servlet class provided with the framework.
+This is defined in the web deployment descriptor, web.xml.
+This file is stored in the project as src/context/WEB-INF/web.xml:
+</p>
+
+<source xml:space="preserve">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE web-app
+ PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+
+<web-app>
+ <display-name>Tutorial: HelloWorld</display-name>
+ <servlet>
+ <servlet-name>app</servlet-name>
+ <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class>
+ <load-on-startup>0</load-on-startup>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>app</servlet-name>
+ <url-pattern>/app</url-pattern>
+ </servlet-mapping>
+</web-app>
+</source>
+
+<p>
+Here we've given our application a name, "app". We're using the standard Tapestry ApplicationServlet class as
+our servlet, and mapped it to the path /app. The name you choose for you application is relatively unimportant, and
+Tapestry will adapt to whatever name you do choose.
+</p>
+
+<p>
+The path, on the other hand, needs to be /app. This is not hard-coded into Tapestry, but does require
+a small amount of configuration if you choose to use another path. As well see in a later
+tutorial, Tapestry can be quite sophisticated in terms of building application URLs, so don't
+be too concerned about this aspect of Tapestry just yet.
+</p>
+
+<p>
+That's all there is to HelloWorld in this phase. No Java code at all. Before going on to bigger and better things, we're going
+to add a little bit to this application, to give you a slightly more realistic feel for Tapestry ... but we'll still
+avoid writing any Java code at all.
+</p>
+
+</section>
+
+<section name="Adding dynamic output">
+
+
+<p>
+We're going to change the Home page to display the current date and time. It will look something like
+this:
+</p>
+
+<img src="../images/QuickStart/helloworld2.png" alt="HelloWorld showing current date/time"/>
+
+<p>
+In Tapestry, pretty much any time anything dynamic occurs, there's going to be a <em>component</em> involved. Tapestry components
+are much like Tapestry pages ... they consist of a template and a Java class (purists may note that there may be an XML
+file to tie those together, and that the template and the Java class are both optional -- more on this
+later).
+</p>
+
+<p>
+Tapestry components "hide" inside the HTML template. They look like ordinary HTML tags, but have
+extra attributes in them, often with unusual values. The revised Home.html template:
+</p>
+
+<source xml:space="preserve">
+<html>
+ <head>
+ <title>Tutorial: HelloWorld</title>
+ </head>
+ <body>
+ <h1>HelloWorld Tutorial</h1>
+
+<p>
+ The current data and time is:
+ <strong><span jwcid="@Insert" value="ognl:new java.util.Date()">June 26 2005</span></strong>
+</p>
+
+ </body>
+</html>
+</source>
+
+<p>
+The <span> tag is the placeholder within the template for the component. The special
+attribute, jwcid, is Tapestry's clue that this is a component, and not just ordinary HTML.
+</p>
+
+<p>The "@Insert" value for the jwcid attribute can be thought of as "instance of
+the <a href="site:Insert">Insert</a> component". Insert is one of many built-in Tapestry components. This isn't quite the Java class; it is
+a component type, which is used by Tapestry to find out about the component, such as what parameters
+can be configured and what Java class contains the logic for the component. Again, more on that later.
+</p>
+
+<p>
+Before we get to the value parameter, a word about the <em>body</em> of the component. The body
+is the portion of the template enclosed by the component's start (<span>) and end (</span>)
+tags. Ultimately, the component itself determines when, if, or how many times it will render
+its body ("render" is the verb used throughout Tapestry meaning "write HTML output").
+</p>
+
+<p>
+ The Insert component expressly <em>does not</em> render its body. Any text inside the
+ component's body is quietly discarded at runtime. We could, in fact, abbreviate the
+ component within the template to
+ just <code><span jwcid="@Insert" value="ognl:new java.util.Date()"/></code> and not put
+ any text inside its tags. So why did we?
+</p>
+
+<p>
+ The answer is <em>previewability</em>, that is, the ability to see, at least approximately, what the
+ page will look like <em>without</em> running the actual application. You can load the Home.html
+ file into a web browser, or a specialized editor such as Dreamweaver or HomeSite, and see what it
+ looks like. For example, if we bypass the Tapestry servlet and access the template directly,
+ we see the following:
+</p>
+
+<img src="../images/QuickStart/helloworld3.png" alt="HelloWorld Home.html template"/>
+
+<p>
+ That <em>provisional text</em>, "June 26 2005" is not <em>exactly</em> what the application will
+ display at runtime ... but it's close enough; it's not blank and it's approximately right. In a real
+ application with real style sheets and layouts, this would be enough validate that the layout
+ of the running application was correct.
+</p>
+
+<p>
+<strong>Note:</strong>
+<br/>
+ This side track, about previewability, is actually one of the cornerstones of Tapestry:
+ a <em>clean</em> seperation between logic and content. A non-Java HTML developer could edit
+ this template and make significant changes and validate them in their editor of choice without
+ involving a Java developer. As long as the HTML side of the team honors the components,
+ the tags with a jwcid attribute, and doesn't make changes to <em>those</em> elements, the rest
+ of the HTML template can be freely editted. It is only at the junction between content
+ and runtime behavior, that is, <em>inside</em> components, that HTML and Java developers need to work together.
+</p>
+
+<p>
+ So, what does <code>value="ognl:new java.util.Date()"</code> mean?
+ Let's start with the attribute value, <code>ognl:new java.util.Date</code>. The "ognl:" prefix
+ signals to Tapestry that this is an expression to be evaluated, rather than a ordinary, literal
+ string. If we did want the Insert to always render the same literal string, such as "Tapestry Rocks!",
+ we wouldn't need the prefix, we could just write
+ <code>value="Tapestry Rocks!"</code>.
+</p>
+
+<p>
+OGNL is the Object Graph Navigation Language, an open source expression language used by several
+open-source projects, including Tapestry, <a href="http://opensymphony.com/webwork/">WebWork</a> and <a href="http://springframework.org/">Spring</a>. OGNL has some astounding
+capabilities, not just reading and updating object properties, but also includes support for creating
+new objects entirely (as here), as well as creating lists, maps and arrays of objects.
+</p>
+
+<p>
+Here, evaluating the expression results in a new instance of the java.util.Date class. This Date
+instance is <em>bound</em> to the value parameter of the Insert component. "Bound" is another
+specialized Tapestry term, one that concerns the relationship between a component parameter and
+a property (or expression) of its container. Here, the component is the Insert component,
+the container is the Home page, and the expression is <code>new java.util.Date</code>. Binding might
+look like just an assignment of a property of the Insert component, but is
+a bit more; components often use bindings to <em>update</em> properties of their container, something we'll see
+when discussing the form element components.
+</p>
+
+<p>
+ In the Java code for the Insert component is the logic that obtains value parameter and
+ converts it into into a string that is rendered into the response.
+</p>
+
+ <p>
+ So, the expression provides the Date instance, the value parameter gives the Insert component access
+ to that value, and the Insert component provides the logic for converting that Date into a string
+ and having it show up on the rendered page. Every time the Insert component renders, it will
+ re-read its value parameter, causing the expression to be evaluated once more, and a new Date instance
+ to be created. You can see this by hitting your browser's refresh button repeatedly; the displayed date will
+ keep changing.
+</p>
+
+<p>
+ In the next section, we'll see how to create a link to get the displayed date to be updated.
+</p>
+
+</section>
+
+<section name="Creating Links">
+
+
+<p>
+ We're going to extend the application once more, adding a refresh link that we can click
+ instead of using the browser's refresh button. The end result looks like:
+</p>
+
+<img src="../images/QuickStart/helloworld4.png" alt="HelloWorld with refresh link"/>
+
+<p>
+ We created this new link by adding the following to Home.html:
+</p>
+
+<source xml:space="preserve">
+<p>
+ <a href="#" jwcid="@PageLink" page="Home">refresh</a>
+</p>
+</source>
+
+<p>
+ Again, anything dynamic in Tapestry is going to involve a component; here it's the
+ <a href="site:PageLink">PageLink</a> component, one of a family of components that generate callback links into a
+ Tapestry application.
+</p>
+
+<p>
+ Tapestry automatically creates a URL for this; you can see this URL in the screenshot:
+ http://localhost:8080/workbench/app?page=Home&service=page. That URL provides two
+ critical pieces of information: service=page means "render a page", and page=Home identifies which
+ page to render.
+</p>
+
+<p>
+ <em>Do I really need a component for that? </em> You might be tempted to change the template to:
+</p>
+
+<source xml:space="preserve">
+ <a href="/app?service=page&amp;page=Home">refresh</a>
+</source>
+
+<p>
+ This is a <strong>bad idea</strong>. Tapestry is doing more than spewing out a URL, it's
+ <em>session encoding</em> the URL for you<sup>1</sup> and may be doing other useful things that
+ we'll see later. Further, second guessing Tapestry's URLs is never a good idea; the PageLink component
+ will be around in the next release of Tapestry, but the URL format may change between releases.
+</p>
+
+<p>
+ Another question: what's with the href attribute in the attribute? What does <code>href="#"</code> mean?
+ This is another side to previewability: to preview this page, the link
+ ultimately generated by the PageLink needs to preview as a <em>link</em>. An <a> tag
+ without an href attribute is an <em>anchor</em>. Again, this is a distinction that is more visible
+ in real applications, supported by a style sheet.
+</p>
+
+<p>
+ The href provided in the HTML template is simply discarded in favor of the href attribute
+ generated inside the PageLink components (/app?service=...). You can actually
+ mix and match these component-generated attributes with extra attributes
+ provided in the template; these are called <em>informal parameters</em>, and are covered in a later
+ tutorial.
+</p>
+
+</section>
+
+<section name="Next: DirectLink">
+
+
+<p>
+ That covers the PageLink component, at least for now. Next up: the <a href="directlink.html">DirectLink Tutorial</a>.
+</p>
+</section>
+
+<p>
+ <sup>1</sup> Session encoding is an aspect of the Servlet API. Encoding a URL adds information about
+ the server-side session (the HttpSession) if there is one. Although this information can
+ be obtained via HTTP cookies, not all users have cookies enabled in their browser. The servlet
+ specification encourages you to always encode your URLs, and this is simply done for you in Tapestry.
+ It's another example of the basic Tapestry principle: <em>make the simplest choice the correct choice</em>.
+</p>
+</body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/QuickStart/helloworld.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml Sun Jul 2 17:17:29 2006
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2005 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>Component Bindings</title>
+</properties>
+<body>
+
+<p>
+Components are configured by <em>binding</em> their parameters. Binding of parameters
+may occur inside a page or component template, or a page or component specification.
+</p>
+
+<p>
+When binding a component parameter, the value to be bound may be just a literal string, or
+it could be an <a href="http://www.ognl.org">OGNL</a> expression, or subject to any of a number of other interpretations. Tapestry
+uses a <em>prefix</em> value, such as "ognl:", or "message:", to identify how the rest of the
+value is to be interpreted. The prefix identifies the <em>binding type</em>:
+</p>
+
+
+<table>
+ <tr>
+ <th>Binding Type</th>
+ <th>Description</th>
+ <th>Example</th>
+ <th>OGNL Equivalent</th>
+ </tr>
+
+ <tr>
+ <td>asset</td>
+ <td>References an asset of the component.</td>
+ <td>asset:stylesheet </td>
+ <td>ognl:assets.stylesheet</td>
+ </tr>
+
+ <tr>
+ <td>bean</td>
+ <td>References a named bean (defined by a <a href="spec.html#spec.bean"><bean></a> element).</td>
+ <td>bean:validationDelegate</td>
+ <td>ognl:beans.validationDelegate</td>
+ </tr>
+
+ <tr>
+ <td>component</td>
+ <td>References a nested component with the provided component id.</td>
+ <td>component:form</td>
+ <td>ognl:components.form</td>
+ </tr>
+
+ <tr>
+ <td>hivemind</td>
+ <td>References a HiveMind object, much like <a href="spec.html#spec.inject"><inject></a>.</td>
+ <td>hivemind:service:app.MyService</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>listener</td>
+ <td>The name of a <a href="listenermethods.html">listener method</a>.</td>
+ <td>listener:formSubmit</td>
+ <td>ognl:listeners.formSubmit</td>
+ </tr>
+
+ <tr>
+ <td>literal</td>
+ <td>Used to "escape" a binding prefix, marking the suffix as a literal value.</td>
+ <td>literal:ognl:not-an-expression</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>message</td>
+ <td>References a localized message from the component's message catalog.</td>
+ <td>message:page-title</td>
+ <td>ognl:messages.getMessage("page-title")</td>
+ </tr>
+
+ <tr>
+ <td>ognl</td>
+ <td>An OGNL expression to be evaluated.</td>
+ <td>ognl:engine.visit.admin</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>state</td>
+ <td>True of false dependening on whether the named <a href="state.html#state.aso">application state object</a> exists.</td>
+ <td>state:visit</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>translator</td>
+ <td>Initializer used to obtain and configure a <a href="../tapestry/apidocs/org/apache/tapestry/form/translator/Translator.html">Translator</a> instance.</td>
+ <td>translator:number,pattern=#</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>validator</td>
+ <td>Initializer used to obtain and configure an <a href="../tapestry/apidocs/org/apache/tapestry/valid/IValidator.html">IValidator</a> instance (used with <a href="site:ValidField">ValidField</a>).</td>
+ <td>validator:string,required,minimumLength=5</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>validators</td>
+ <td>List of configured <a href="../tapestry/apidocs/org/apache/tapestry/form/validator/Validator.html">Validator</a> instances (used with <a href="site:TextField">TextField</a> and others). </td>
+ <td>validators:email,required,minLength=10</td>
+ <td/>
+ </tr>
+</table>
+
+<p>
+ Most of these are quite straight forward; the
+ <a href="validation.html#validation.validator-binding">validator, validators and translator</a> prefixes
+ require some additional description.
+</p>
+
+<p>
+<strong>Note:</strong>
+<br/>
+ You can define your own prefixes by contributing into the tapestry.bindings.BindingFactories configuration point.
+</p>
+
+<p>
+What happens when you omit a binding prefix? In a page or component <em>template</em>, the value it is assumed to be a literal string, as with the "literal:" prefix.
+In a page or component specification, or inside a Java annotation, the value is assumed to be an <a href="http://www.ognl.org">OGNL</a> expression, as with the "ognl:" prefix
+(but even this can be configured). You will occasionally have
+to use an explicit "literal:" prefix inside such files.
+</p>
+
+
+<p>
+ Many of the bindings are driven by a HiveMind configuration; the configuration will
+ define the available values, and contributing the configuration allows
+ new values to be defined.
+</p>
+
+<table>
+ <tr>
+ <th>Binding Prefix</th>
+ <th>Configuration</th>
+ </tr>
+ <tr>
+ <td>translator</td>
+ <td>
+<a href="../tapestry/hivedocs/config/tapestry.form.translator.Translators.html">tapestry.form.translator.Translators</a>
+</td>
+ </tr>
+ <tr>
+ <td>state</td>
+ <td>
+<a href="../tapestry/hivedocs/config/tapestry.state.ApplicationObjects.html">tapestry.state.ApplicationObjects</a>
+</td>
+ </tr>
+ <tr>
+ <td>validator</td>
+ <td>
+<a href="../tapestry/hivedocs/config/tapestry.valid.Validators.html">tapestry.valid.Validators</a>
+</td>
+ </tr>
+</table>
+
+</body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/components.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/components.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/components.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/components.xml Sun Jul 2 17:17:29 2006
@@ -0,0 +1,678 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004, 2005 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>Creating Tapestry components</title>
+</properties>
+<body>
+
+<p>
+Tapestry is a component based web application framework; components, objects which implement
+the <a href="../tapestry/apidocs/org/apache/tapestry/IComponent.html">IComponent</a> interface, are the fundamental building blocks of Tapestry. Additional objects,
+such as the the engine, <a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> and the request cycle are infrastructure. The following figure
+identifies the core Tapestry classes and interfaces.
+</p>
+
+<img alt="Core Tapestry Classes and Interfaces" src="../images/UsersGuide/core-classes.png"/>
+
+<p>
+Tapestry components can be simple or complex. They can be specific to a
+single application or completely generic. They can be part of an application,
+or they can be packaged into
+a <a href="#components.libraries">component library</a>.
+</p>
+
+<p>
+All the techniques used with pages work with components as well ... pages are a specialized kind
+of Tapestry component. This includes
+<a href="state.html#state.page-properties">specified properties</a>
+ (including persistent properties)
+and <a href="listenermethods.html">listener method</a>s.
+</p>
+
+<p>
+Components fit into the overall page rendering process because they implement the <a href="../tapestry/apidocs/org/apache/tapestry/IRender.html">IRender</a> interface.
+Components that inherit from <a href="../tapestry/apidocs/org/apache/tapestry/BaseComponent.html">BaseComponent</a> will use an HTML template. Components that inherit
+from <a href="../tapestry/apidocs/org/apache/tapestry/AbstractComponent.html">AbstractComponent</a> will render output in Java code, by implementing method
+<code>renderComponent()</code>.
+</p>
+
+<p>
+The components provided with the framework are not special in any way: they don't have access to
+any special APIs or perform any special down-casts. Anything a framework component can do, can be done by
+your own components.
+</p>
+
+
+<section name="Component Specifications">
+
+
+<p>
+Every component has a component specification, a file ending with a .jwc extension, whose
+root element is <a href="spec.html#spec.component-specification"><component-specification></a>.
+</p>
+
+<p>
+Each component's specification defines the basic characteristics of the component:
+</p>
+
+<ul>
+ <li>
+ The Java class for the component (which defaults to <a href="../tapestry/apidocs/org/apache/tapestry/BaseComponent.html">BaseComponent</a>)
+ </li>
+ <li>
+ Whether the component uses its body, or discards it (the allow-body attribute,
+ which defaults to yes)
+ </li>
+ <li>
+ <p>
+ The name, type and other information for each <em>formal</em>
+ parameter.
+ </p>
+ </li>
+ <li>
+ <p>
+ Whether the component allows informal parameters or discards them
+ (the allow-informal-parameters attribute, which defaults to
+ yes)
+ </p>
+ </li>
+ <li>
+ <p>
+ The names of any <em>reserved parameters</em> which may <em>not</em>
+ be used as informal parameters.
+ </p>
+ </li>
+</ul>
+
+
+<p>
+Beyond those additions, a component specification is otherwise the same as a <a href="spec.html#spec.page-specification"><page-specification></a>.
+</p>
+
+<p>
+When a component is referenced in an HTML template (using the @<em>Type</em>
+syntax), or in a specification (as the type attribute of
+a <a href="spec.html#spec.component"><component></a> element), Tapestry must locate and parse the component's specification (this is only done once, with the
+result cached for later).
+</p>
+
+<p>
+Tapestry searches for components in the following places:</p>
+
+<ul>
+ <li>
+ As specified in a <a href="spec.html#spec.component-type"><component-type></a> element (within the application specification).
+ </li>
+ <li>
+ In the same folder as the
+ application specification, which is typically the WEB-INF folder.
+ </li>
+ <li>
+ In the WEB-INF/<em>servlet-name</em> folder
+ (<em>servlet-name</em> is the name of the Tapestry <a href="../tapestry/apidocs/org/apache/tapestry/ApplicationServlet.html">ApplicationServlet</a>
+ for the application).
+ </li>
+ <li>
+ In the WEB-INF folder.
+ </li>
+ <li>
+ In the root context directory.
+ </li>
+</ul>
+
+
+ <p>
+<strong>Note:</strong>
+<br/>
+ The second option, WEB-INF/<em>servlet-name</em>,
+ exists to support the rare case of a single WAR file containing
+ multiple Tapestry applications.
+ </p>
+
+<p>
+Generally, the <em>correct</em> place is in the
+WEB-INF folder. <a href="#components.libraries">Components packaged into
+ libraries</a> have a different (and simpler) search.
+</p>
+
+
+</section> <!-- components.spec -->
+
+<section name="Coding components">
+
+
+<p>
+When creating a new component by subclassing <a href="../tapestry/apidocs/org/apache/tapestry/AbstractComponent.html">AbstractComponent</a>, you must implement the
+<code>renderComponent()</code> method. This method is invoked when the component's container (typically, but not always,
+a page) invokes its own <code>renderBody()</code> method.
+</p>
+
+<source xml:space="preserve">
+protected void renderComponent(<a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> writer, <a href="../tapestry/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a> cycle)
+{
+ . . .
+}
+</source>
+
+<p>
+The <a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> object is used to produce output. It contains a number of <code>print()</code> methods
+that output text (the method is overloaded for different types). It also contains <code>printRaw()</code>
+methods -- the difference being that <code>print()</code> uses a filter to convert certain characters
+into HTML entities.
+</p>
+
+
+<p>
+<a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> also includes methods to simplify creating markup style output: that is, elements with attributes.
+</p>
+
+
+<p>
+For example, to create a <a> link:
+ </p>
+
+<source xml:space="preserve">
+public void renderComponent(<a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> writer, <a href="../tapestry/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a> cycle)
+{
+ . . .
+
+ writer.begin("a");
+ writer.attribute("url", url);
+ writer.attribute("class", styleClass);
+
+ renderBody(writer, cycle);
+
+ writer.end(); // close the <a>
+}
+</source>
+
+
+<p>
+The <code>begin()</code> method renders an open tag (the <a>, in
+this case). The <code>end()</code> method renders
+the corresponding </a>. As you can see, writing attributes into the tag
+is equally simple.
+</p>
+
+
+<p>
+The call to <code>renderBody()</code> is used to render <em>this</em> component's
+body. A component doesn't have to render its body; the standard <a href="site:Image">Image</a> component doesn't render its
+body (and its component specification indicates that it discards its body). The <a href="site:Conditional">Conditional</a> component
+decides whether or not to render its body, and the
+<a href="site:Foreach">Foreach</a> component may render its body multiple times.
+</p>
+
+<p>
+A component that allows informal parameters can render those as well:
+</p>
+
+<source xml:space="preserve">
+ writer.beginEmpty("img");
+ writer.attribute("src", imageURL);
+ renderInformalParameters(writer, cycle);
+</source>
+
+
+<p>
+This example will add any informal parameters for the component
+as additional attributes within the <img> element. These informal parameters
+can be specified in the page's HTML template, or within the <a href="spec.html#spec.component"><component></a> tag of the page's specification. Note the use
+of the <code>beginEmpty()</code> method, for creating a start tag that is not balanced with an end tag (or
+a call to the <code>end()</code> method).
+</p>
+
+</section> <!-- components.coding -->
+
+<section name="Component Parameters">
+
+
+<p>
+A Tapestry page consists of a number of components. These components communicate with, and coordinate with,
+the page (and each other) via <em>parameters</em>.
+</p>
+
+<p>
+A formal component parameter has a unique name, and may be optional or required. Optional parameters
+may have a default value.
+The <a href="spec.html#spec.parameter"><parameter></a> component specification element is used to define formal component parameters.
+</p>
+
+<p>
+In a traditional desktop application, components have <em>properties</em>. A controller may
+set the properties of a component, but that's it: properties are write-and-forget.
+</p>
+
+<p>
+The Tapestry model is a little more complex. A component's parameters are <em>bound</em>
+to properties of the enclosing page (or component). The component is allowed to read its parameter, to access
+the page property the parameter is bound to. A component may also <em>update</em> its
+parameter, to force a change to the bound page property. In fact, behind the scenes, each component parameter
+has a <em>binding</em> object, an instance of type <a href="../tapestry/apidocs/org/apache/tapestry/IBinding.html">IBinding</a>, that is used to read or update the property.
+</p>
+
+<p>
+The vast majority of components simply read their parameters. Updating parameters is more rare; the most
+common components that update their parameters are form element components such as <a href="site:TextField">TextField</a> or <a href="site:Checkbox">Checkbox</a>.
+</p>
+
+<p>
+Because bindings are often in the form of <a href="http://www.ognl.org">OGNL</a> expressions, the property bound to a component parameter
+may not directly be a property of the page ... using a property sequence allows great flexibility.
+</p>
+
+<img alt="Parameter Bindings" src="../images/UsersGuide/parameter-bindings.png"/>
+
+ <p>
+Using <a href="http://www.ognl.org">OGNL</a>, the <a href="site:TextField">TextField</a> component's value parameter is bound
+to the LineItem's quantity property, using
+the OGNL expression lineItem.quantity, and the <a href="site:Insert">Insert</a> component's
+value parameter is bound to the Product's
+name property using the OGNL expression lineItem.product.name.
+ </p>
+
+
+<p>
+When using localized messages (the message: prefix) or literal strings (no prefix), there is still a binding object, just a binding
+of a different type. Not all bindings are writable. OGNL expressions may be writeable, if the expression
+identifies a property that is itself writeable. Most other types of bindings are read only.
+</p>
+
+
+<p>
+To access a component parameter inside Java code is simply a matter of defining an accessor method. For example,
+if your component has a title parameter, then you define a getTitle() accessor method:</p>
+
+<source xml:space="preserve">
+public abstract String getTitle();
+
+public void renderComponent(<a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> writer, <a href="../tapestry/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a> cycle)
+{
+ writer.begin("a");
+ writer.attribute("href", . . .);
+ writer.attribute("title", getTitle());
+
+ . . .
+}
+</source>
+
+<p>
+When your code invokes getTitle(), the binding for the title parameter will be used to obtain a value, which is returned. Likewise,
+invoking setTitle() will use the binding for the title parameter to update the bound value.
+</p>
+
+<p>
+<strong>Note:</strong>
+<br/>
+If you are upgrading from Tapestry 3.0, you may be wondering "how do I specify parameter direction now?". Parameter direction was
+a hint you would provide to Tapestry that would tell Tapestry when it was appropriate to copy values into, or out of, component
+parameter properties. This is no longer necessary in Tapestry 4.0 -- the runtime code generation for parameter properties is much
+more sophisticated. All parameters are now similar to Tapestry 3.0's auto direction, but much smarter. Tapestry 3.0 auto parameters
+were only useable with required parameters and were inefficient. In Tapestry 4.0, parameter values are cached such that the OGNL expression
+does not have to be evaluated every time the parameter is accessed and things still work properly for optional parameters.
+</p>
+
+
+<p>
+There are two ways to set default values for parameters. You may provide a default-value attribute in the <a href="spec.html#spec.parameter"><parameter></a> element. This
+is, effectively, a binding to use if no binding is provided.
+</p>
+
+<source xml:space="preserve">
+ <parameter name="title" default-value="literal:Link to current thread"/>
+</source>
+
+<p>
+ Remember that outside of the template, all <a href="bindings.html">binding reference</a>s, including the default-value attribute, default
+ to OGNL expressions. Therefore, it is necessary to prefix the default value with the literal: prefix to ensure
+ that Tapestry doesn't treat it as an expression.
+</p>
+
+<p>
+ What's nice is that the default value doesn't have to be a simple string; it can be a computed OGNL expression, or
+ a reference to a localized message:
+</p>
+
+
+<source xml:space="preserve">
+ <parameter name="title" default-value="message:link-title"/>
+</source>
+
+<source xml:space="preserve">
+link-title=Link to current thread
+</source>
+
+<p>
+The second approach to defining default values for parameters is to set the parameter's property from the component's finishLoad() method.
+</p>
+
+<source xml:space="preserve">
+public abstract void setTitle(String title);
+
+protected void finishLoad()
+{
+ super.finishLoad();
+
+ setTitle("Link to current thread");
+}
+</source>
+
+<p>
+Even with parameter defaults, there are times when you want to behave differently depending on whether a parameter is bound or not bound.
+The method isParameterBound() exists for those cases:
+</p>
+
+<source xml:space="preserve">
+public abstract String getTitle();
+
+public void renderComponent(<a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> writer, <a href="../tapestry/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a> cycle)
+{
+ writer.begin("a");
+ writer.attribute("href", . . .);
+
+ if (isParameterBound("title"))
+ writer.attribute("title", getTitle());
+
+ . . .
+}
+</source>
+
+
+<p>
+Using isParameterBound() is most useful with parameters whose type is a primitive type. In the previous example, we could simply invoke getTitle()
+and see if the result is null. For, say, an int property, we would need a way to distinguish between 0 and no value provided ... that's
+what isParameterBound() is for.
+</p>
+
+
+<p>
+Note that you always pass the name of the <em>parameter</em> to the isParameterBound() method,
+even when you've used the property attribute of the <a href="spec.html#spec.parameter"><parameter></a> element to
+use a different property name:
+</p>
+
+<source xml:space="preserve">
+<parameter name="title" property="titleParameter"/>
+</source>
+
+<source xml:space="preserve">
+public abstract String getTitleParameter();
+
+public void renderComponent(<a href="../tapestry/apidocs/org/apache/tapestry/IMarkupWriter.html">IMarkupWriter</a> writer, <a href="../tapestry/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a> cycle)
+{
+ writer.begin("a");
+ writer.attribute("href", . . .);
+
+ if (isParameterBound("title"))
+ writer.attribute("title", getTitleParameter());
+
+ . . .
+}
+</source>
+
+<p>
+When Tapestry enhances a class to add a component property, it (by default) caches the value of the binding for the duration of the component's render.
+That is, while a component is rendering, it will (at most) use the parameter's binding once, and store the result internally, clearing the cached value
+as the component finishes rendering. The parameter property <em>can be accessed when the component is not rendering</em> (an important improvement
+from Tapestry 3.0), the result simply is not cached (each access to the property when the component is not rendering is another access via the
+binding object).
+</p>
+
+<p>
+This caching behavior is not always desired; in some cases, the component operates best with caching disabled. The <a href="spec.html#spec.parameter"><parameter></a> element's
+cache parameter can be set to "false" to defeat this caching.
+</p>
+
+
+<p>
+However, for the majority of binding types (most types except for "ognl"), the value obtained is invariant ... it will always be the same value. Values
+obtained from invariant bindings are <em>always</em> cached <em>indefinately</em> (not just for the component's render). In other words, literal string values,
+localized messages and so forth are accessed via the binding just once. This is great for <em>efficiency</em>; after "warming up", a Tapestry page
+will render faster the second time through, because so many component parameters are invariant and already in place inside
+component properties.
+</p>
+
+<p>
+On the other hand, <em>informal parameters</em> are not cached at all; the values for such parameters are always re-obtained from the
+binding object on each use.
+</p>
+
+<p>
+<strong>Note:</strong>
+<br/>
+When using 3.0 DTDs with Tapestry 4.0, parameters with direction "auto" are <em>not cached</em>. Other direction types (or no direction
+specified) are cached. There is no real support for direction "custom" in 4.0 ... all parameters will be realized as parameter properties.
+</p>
+
+</section> <!-- components.parameters -->
+
+
+
+<section name="Component Libraries">
+
+
+<p>
+Tapestry has a very advanced concept of a <em>component library</em>. A component library contains both Tapestry components and Tapestry pages
+(not to mention engine services).
+</p>
+
+<subsection name="Referencing Library Components">
+
+
+<p>
+Before a component library may be used, it must be listed in the application specification. Often, an application specification is <em>only</em>
+needed so that it may list the libraries used by the application. Libraries are identified using the <a href="spec.html#spec.library"><library></a> element.
+</p>
+
+<p>
+The <a href="spec.html#spec.library"><library></a> element provides an <em>id</em> for the library, which is used to reference components (and pages) within the library. It also
+provides a path to the library's specification. This is a complete path for a .library file on the classpath. For example:
+</p>
+<source xml:space="preserve">
+<application name="Example Application">
+
+ <library id="contrib" specification-path="/org/apache/tapestry/contrib/Contrib.library"/>
+
+</application></source>
+
+<p>
+In this example, Contrib.library defines a set of components, and those component can be accessed using
+contrib: as a prefix. In an HTML template, this might appear as:
+</p>
+
+<source xml:space="preserve">
+<span jwcid="palette@contrib:Palette" . . . />
+</source>
+
+
+<p>
+This example defines a component with id <code>palette</code>. The component will be an instance of the Palette component, supplied within
+the contrib component library. If an application uses multiple libraries, they will each have their own prefix.
+Unlike JSPs and JSP tag libraries, the prefix is set once, in the application specification, and is used consistently in all HTML templates and
+ specifications within the application.
+</p>
+
+<p>
+The same syntax may be used in page and component specifications:
+</p>
+
+<source xml:space="preserve">
+<component id="palette" type="contrib:Palette">
+ . . .
+</component>
+</source>
+
+
+</subsection> <!-- components.libraries.ref -->
+
+<subsection name="Library component search path">
+
+
+<p>
+<a href="#components.spec">Previously</a>, we described the search path for components and pages within the application. The rules are somewhat different
+for components and pages within a library.
+</p>
+
+<p>
+Tapestry searches for library component specifications in the following places:
+</p>
+
+<ul>
+ <li>
+ As specified in a <a href="spec.html#spec.component-type"><component-type></a> element (with the library specification).
+ </li>
+ <li>
+ In the same package folder as the
+ library specification.
+ </li>
+</ul>
+
+
+<p>
+The search for page specifications is identical: as defined in the library specification, or in the same package folder.
+</p>
+
+</subsection> <!-- components.libraries.search -->
+
+<subsection name="Using Private Assets">
+
+
+<p>
+Often, a component must be packaged up with images, stylesheets or other resources (collectively termed "assets")
+that are needed at runtime. A reference to such an asset can be created using the <a href="spec.html#spec.asset"><asset></a> element of
+the page or component specification. For example:
+</p>
+
+<source xml:space="preserve">
+
+ <asset name="logo" path="images/logo_200.png"/>
+
+ <component id="image" type="Image">
+ <binding name="image" value="asset:logo"/>
+ </component>
+</source>
+
+<p>
+In this case, if the component is packaged as /com/example/mylibrary/MyComponent.jwc, then
+the asset will be /com/examples/mylibrary/images/logo_200.png. Further, the asset path will be localized.
+</p>
+
+<p>
+All assets (classpath, context or external) are converted into instances of <a href="../tapestry/apidocs/org/apache/tapestry/IAsset.html">IAsset</a> and treated identically by
+components (such as <a href="site:Image">Image</a>). As in this example, relative paths are allowed: they are interpreted relative
+to the specification (page or component) they appear in.
+</p>
+
+<p>
+The Tapestry framework will ensure that an asset will be converted to a valid URL that may be referenced from a client
+web browser ... even though the actual service is inside a JAR or otherwise on the classpath, not normally
+referenceable from the client browser.
+</p>
+
+<p>
+The <em>default</em> behavior is to serve up the <em>localized</em> resource
+using the asset service. In effect, the framework will read the contents of the asset and pipe that binary content
+down to the client web browser.
+</p>
+
+<p>
+An alternate behavior is to have the framework copy the asset to a fixed directory. This directory should be mapped
+to a known web folder; that is, have a URL that can be referenced from a client web browser. In this way, the web server
+can more efficiently serve up the asset, as a static resource (that just happens to be copied into place in a just-in-time manner).
+
+</p>
+
+<p>
+This behavior is controlled by a pair of <a href="configuration.html#configuration.properties">configuration properties</a>:
+org.apache.tapestry.asset.dir and org.apache.tapestry.asset.URL.
+
+</p>
+</subsection> <!-- components.libraries.classpath-assets -->
+
+<subsection name="Library Specifications">
+
+
+
+<p>
+A library specification is a file with a .library extension. Library specifications
+use a root element of <a href="spec.html#spec.library-specification"><library-specification></a>, which supports a subset of the attributes
+allowed within an <a href="spec.html#spec.application"><application></a> element (but allowing the <em>same</em> nested elements). Often, the library specification is an empty placeholder, used
+to an establish a search location for page and component specifications:
+</p>
+
+<source xml:space="preserve">
+<!DOCTYPE library-specification PUBLIC
+ "-//Apache Software Foundation//Tapestry Specification 3.0//EN"
+ "http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd">
+
+<library-specification/>
+</source>
+
+
+<p>
+It is allowed that components in one library be constructed using components provided by another library.
+The referencing library's specification may contain
+<a href="spec.html#spec.library"><library></a> elements that identify some other library.
+</p>
+
+</subsection> <!-- comopnents.libraries.spec -->
+
+<subsection name="Libraries and Namespaces">
+
+
+<p>
+Tapestry organizes components and pages (but <em>not</em> engine services) into
+<em>namespaces</em>. Namespaces are closely related to, but not exactly the same as,
+the library prefix established using the <a href="spec.html#spec.library"><library></a> element in an application or library specification.
+</p>
+
+<p>
+Every Tapestry application consists of a default namespace, the application namespace. This is the namespace used
+when referencing a page or component without a prefix. When a page or component can't be resolved within the application namespace,
+the framework namespace is searched. Only if the component (or page) is not part of the framework namespace does an error result.
+</p>
+
+<p>
+In fact, it is possible to override both pages and components provided by the framework. This is frequently used to change the
+look and feel of the default StateSession or Exception page. In theory, it is even possible to override fundamental components such as
+<a href="site:Insert">Insert</a> or <a href="site:Foreach">Foreach</a>!
+</p>
+
+<p>
+Every component provides a namespace property that defines the namespace (an instance
+of <a href="../tapestry/apidocs/org/apache/tapestry/INamespace.html">INamespace</a>) that the component belongs to.
+</p>
+
+<p>
+You rarely need to be concerned with namespaces, however. The rare exception is when a page from a library wishes to
+make use of the <a href="site:PageLink">PageLink</a> or <a href="site:ExternalLink">ExternalLink</a> components to create a link to <em>another page</em> within
+the same namespace. This is accomplished (in the source page's HTML template) as:
+</p>
+
+<source xml:space="preserve">
+ <a href="#" jwcid="@PageLink" page="OtherPage" namespace="ognl:namespace"> ... </a>
+</source>
+
+
+</subsection> <!-- components.libraries.namespace -->
+
+</section> <!-- components.libraries -->
+
+
+</body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/components.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/configuration.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/configuration.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/configuration.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/configuration.xml Sun Jul 2 17:17:29 2006
@@ -0,0 +1,774 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004, 2005 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>Configuring Tapestry</title>
+</properties>
+<body>
+
+<p>
+<strong>Warning:</strong>
+<br/>
+ Configuration is the area of greatest change between Tapestry 3.0 and Tapestry 4.0. Tapestry 4.0 has been
+ restructured around <a href="http://jakarta.apache.org/hivemind/">HiveMind</a>, which includes a very rich environment for services and
+ configurations.
+</p>
+
+
+<p>
+Tapestry is designed to operate on a variety of different JVMs and versions of
+the Java Servlet API. Below you can find the list of supported and
+tested configurations:
+</p>
+
+<dl>
+ <dt>Java 1.2.2</dt>
+ <dd>
+ Operates correctly. Requires the Xerces parser to be in the classpath
+ (usually provided by the servlet container).
+ </dd>
+
+ <dt>Java 1.3.x</dt>
+
+ <dd>
+ Operates correctly. Requires the Xerces parser to be in the classpath
+ (usually provided by the servlet container).
+ </dd>
+
+ <dt>Java 1.4.x (recommended)</dt>
+
+
+ <dd>
+ Operates correctly.
+ </dd>
+</dl>
+
+
+
+<p>
+ Supported Java Servlet API Versions:
+</p>
+
+<dl>
+ <dt>Java Servlet API 2.2</dt>
+
+ <dd>
+ Operates correctly with minor exceptions related to character encoding
+ of the requests due to the limitations of the Servlet API version.
+ </dd>
+
+ <dt>Java Servlet API 2.3 (recommended)</dt>
+
+ <dd>
+ Operates correctly.
+ </dd>
+</dl>
+
+
+
+<section name="Web deployment descriptor">
+
+
+<p>
+All Tapestry applications make use of the <a href="../tapestry/apidocs/org/apache/tapestry/ApplicationServlet.html">ApplicationServlet</a> class as their
+servlet; it is rarely necessary to create a subclass. A typical web.xml configuration
+maps the servlet to the /app path, and adds a servlet filter (discussed shortly):
+</p>
+
+
+<source xml:space="preserve">
+<?xml version="1.0"?>
+<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd">
+<web-app>
+ <display-name>My Application</display-name>
+
+ <servlet-mapping>
+ <servlet-name>myapp</servlet-name>
+ <url-pattern>/app</url-pattern>
+ </servlet-mapping>
+
+ <filter>
+ <filter-name>redirect</filter-name>
+ <filter-class>org.apache.tapestry.RedirectFilter</filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>redirect</filter-name>
+ <url-pattern>/</url-pattern>
+ </filter-mapping>
+
+ <servlet>
+ <servlet-name>myapp</servlet-name>
+ <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class>
+ <load-on-startup>0</load-on-startup>
+ </servlet>
+
+ <session-config>
+ <session-timeout>15</session-timeout>
+ </session-config>
+
+ <welcome-file-list>
+ <welcome-file>index.html</welcome-file>
+ </welcome-file-list>
+</web-app>
+
+</source>
+
+ <p>
+ The servlet class should always be <a href="../tapestry/apidocs/org/apache/tapestry/ApplicationServlet.html">ApplicationServlet</a>. There's rarely
+ a need to create a subclass; Tapestry has many other hooks for extending the
+ application.
+ </p>
+<p>
+It is generally a good idea to specify
+<load-on-startup>, this causes
+the servlet container to instantitate and initialize the the application servlet, which in turn,
+reads the Tapestry application specification. Many common development errors will be spotted immediately,
+rather than when the first application request arrives.
+</p>
+
+ <p>
+ The servlet is mapped to /app within the context. The context
+ itself has a path, determined by the application server and based on the name of the WAR file.
+
+ The client web browser will see the Tapestry application
+ as http://<em>host</em>/<em>war-name</em>/app.
+ </p>
+
+ <p>
+ Using /app as the URL is a common convention when creating
+ Tapestry applications, but is not a requirement. If you choose an alternate URL,
+ you must override the <code>org.apache.tapestry.servlet-path</code> configuration property.
+ </p>
+
+<p>
+The <a href="../tapestry/apidocs/org/apache/tapestry/RedirectFilter.html">RedirectFilter</a> filter sends a client redirect to the user when they access the web application context. The filter
+sends a client redirect to the user's browser, directing them to the application servlet. In this way,
+the "public" URL for an application can be http://myserver/mycontext/ when, in fact,
+the real address is http://myserver/mycontext/app.
+</p>
+
+<p>
+On initialization, the Tapestry servlet will locate its
+application specification; a file that identifies details about the
+application, the pages and components within it, and any
+component libraries it uses. Tapestry provides a great deal of
+flexibility on where the specification is stored; trivial Tapestry
+applications can operate without an application specification.
+</p>
+
+<p>
+<strong>Fixme:</strong>
+<br/>
+This documentation is out of date with respect to <a href="http://jakarta.apache.org/hivemind/">HiveMind</a>. In 4.0, the servlet will create and initialize a HiveMind Registry.
+</p>
+
+<p>
+The specification is normally
+stored under WEB-INF. In fact, Tapestry performs a search to find the specification:
+</p>
+
+<ul>
+<li>
+ On the classpath, as defined by the org.apache.tapestry.application-specification
+ <a href="configuration.html#configuration.properties">configuration property</a>.
+</li>
+<li>
+ As /WEB-INF/<em>name</em>/<em>name</em>.application.
+ The <em>name</em> is the servlet name. This location
+ is only used in the rare case of a single WAR containing multiple Tapestry
+ applications.
+</li>
+<li>
+ As /WEB-INF/<em>name</em>.application.
+ Again, <em>name</em> is the
+ servlet name. This is the standard location.
+</li>
+</ul>
+
+<p>
+If the application specification still can not be found, then an empty, "stand in"
+application specification is used. This is perfectly acceptible ... an application specification is typically
+needed only when an application makes use of component libraries, or requires some other kind of customization
+only possible with an application specification.
+</p>
+
+
+</section> <!-- configuration.deployment-descriptor -->
+
+<section name="Application Property Source">
+
+
+<p>
+Tapestry occasionally must obtain a value for a configuration property. These configuration
+properties are items that are frequently optional, and don't fit into any particular
+specification. Many are related to the runtime environment, such as which class to instantiate as the
+Visit object.
+</p>
+
+<p>
+Tapestry
+is very flexible about where values for such properties may be obtained. In general,
+the search path for configuration properties is:
+</p>
+
+<ul>
+ <li>
+ As a <a href="spec.html#spec.meta"><meta></a> of the <a href="spec.html#spec.application"><application></a> (in the application specification,
+ if the application uses one).
+ </li>
+ <li>
+ As an <init-parameter>
+ for the servlet, in the web application deployment descriptor.
+ </li>
+ <li>
+ As an <init-parameter>
+ for the servlet context, also in the web application deployment descriptor.
+ </li>
+ <li>
+ As a JVM system property.
+ </li>
+ <li>
+ Hard-coded "factory" defaults (for some properties). These are accessed as
+ <a href="http://jakarta.apache.org/hivemind/">HiveMind</a> symbols.
+ </li>
+</ul>
+
+<p>
+It is expected that some configuration properties are not defined at any level; those will
+return null.
+</p>
+
+
+<p>
+Applications are free to leverage this lookup mechanism as well.
+</p>
+
+<p>
+<strong>Fixme:</strong>
+<br/>
+ Need to reference the ApplicationPropertySource, GlobalPropertySource and
+ ComponentPropertySource services here.
+</p>
+
+<p>
+Applications may also want to change or augment
+the default search path; this is accomplished by overriding
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/AbstractEngine.html">AbstractEngine</a> method <code>createPropertySource()</code>. For example,
+some configuration data could be drawn from a database.
+</p>
+
+<p>
+<strong>Fixme:</strong>
+<br/>
+ The previous paragraph is out of date; extension of the search path will
+ involve a HiveMind contribution, details to be provided.
+</p>
+
+
+</section> <!-- configuration.app-property-source -->
+
+<section name="Global Property Source">
+
+
+ <p>
+ In some cases, a slightly different property source is used, the global property source.
+ </p>
+
+<ul>
+ <li>
+ As an <init-parameter>
+ for the servlet, in the web application deployment descriptor.
+ </li>
+ <li>
+ As an <init-parameter>
+ for the servlet context, also in the web application deployment descriptor.
+ </li>
+ <li>
+ As a JVM system property.
+ </li>
+ <li>
+ Hard-coded "factory" defaults (for some properties). These are accessed as
+ <a href="http://jakarta.apache.org/hivemind/">HiveMind</a> symbols.
+ </li>
+</ul>
+</section> <!-- configuration.global-property-source -->
+
+<section name="Configuration Properties">
+
+
+<p>
+The following are all the configuration values
+currently used in Tapestry:
+</p>
+
+<table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>org.apache.tapestry.accepted-locales</td>
+ <td>
+ Controls which locales are supported by the application; see the
+ documentation on
+ <a href="localization.html#localization.accepted-locales">limiting accepted locales</a>
+ for details.
+ </td>
+ </tr>
+
+ <tr>
+ <td>org.apache.tapestry.bean-class-packages</td>
+ <td>
+ A comma-seperated list, used when converting class names for managed beans (specified
+ using the <a href="spec.html#spec.bean"><bean></a> element) into fully qualified class names. This property is specified
+ in the containing library or application specification.
+ </td>
+ </tr>
+
+ <tr>
+ <td>org.apache.tapestry.component-class-packages</td>
+ <td>
+ A comma-seperated list of package names, used when
+ <a href="page-class.html#page-class.component">searching for the component class</a>. These must
+ appear as <a href="spec.html#spec.meta"><meta></a> tags in the application or library specification
+ containing the component
+ </td>
+</tr>
+
+ <tr>
+ <td>org.apache.tapestry.default-binding-prefix</td>
+ <td>
+ The default binding to use when no explicit binding prefix is provided. This is typically set inside a page or
+ component specification, or within an application specification or library specification (to provide the default
+ for all pages and components). If not otherwise specified,
+ the default binding prefix is "ognl".
+ </td>
+ </tr>
+
+ <tr>
+ <td>org.apache.tapestry.default-cookie-max-age</td>
+ <td>
+ The default max age (in seconds) for cookies written by Tapestry, including the cookie used
+ to track the user's locale. A value of -1 means the cookie is a session cookie,
+ stored only until the user's browser exits. The default value is equivalent to one week.
+ </td>
+ </tr>
+
+ <tr>
+
+ <td>org.apache.tapestry.default-page-class</td>
+
+ <td>
+ By default, any page that omits the
+ class attribute (in its <a href="spec.html#spec.page-specification"><page-specification></a>)
+ will be instantiated as <a href="../tapestry/apidocs/org/apache/tapestry/html/BasePage.html">BasePage</a>. If this is not desired,
+ the default may be overridden by specifying a fully
+ qualified class name.
+ </td>
+
+</tr>
+
+<tr>
+ <td>org.apache.tapestry.disable-caching</td>
+
+ <td>
+ If specified (as "true"), then the framework will discard all cached data
+ (specifications, templates, pooled objects, etc.) at the end of each request cycle.
+
+ <p>
+ This slows down request handling by a noticable amount, but is very
+ useful in development; it means that changes to templates and specifications
+ are immediately visible to the application. It also helps identify
+ any errors in managing persistent page state.
+ </p>
+
+ <p>
+ This should never be enabled in production; the performance hit is too large.
+ Unlike most other configuration values, this must be specified
+ as a JVM system property.
+ </p>
+ </td>
+</tr>
+
+
+
+
+<tr>
+ <td>org.apache.tapestry.enable-reset-service</td>
+
+ <td>
+ If not specified as "true", then the reset service
+ will be non-functional. The reset service is used to force
+ the running Tapestry application to discard all cached data (including
+ templates, specifications, pooled objects and more). This must
+ be explicitly enabled, and should only be used in development (in production,
+ it is too easily exploited as a denial of service attack).
+
+ <p>
+ Unlike most other configuration values, this must be specified
+ as a JVM system property.
+ </p>
+ </td>
+</tr>
+
+<tr>
+ <td>org.apache.tapestry.engine-class</td>
+
+ <td>
+ The fully qualified class name to instantiate as the application engine.
+ This configuration value is only used when the
+ application specification does not exist, or fails to
+ specify a class. By default, <a href="../tapestry/apidocs/org/apache/tapestry/engine/BaseEngine.html">BaseEngine</a> is used if this configuration
+ value is also left unspecified.
+ </td>
+</tr>
+
+
+<tr>
+ <td>org.apache.tapestry.enhance.disable-abstract-method-validation</td>
+
+ <td>
+ Used to trigger a work around for a bug in IBM's JDK 1.4.0. This particular JDK reports <em>all</em> methods
+ of an abstract class as abstract, even if they are, in fact, concrete. This causes spurious errors
+ about unimplemented abstract methods. Specifying true for this property
+ disables checks for unimplemented abstract methods.
+
+ <p>
+<strong>Warning:</strong>
+<br/>
+ Support for this property has been temporarily removed from release 4.0.
+ </p>
+ </td>
+</tr>
+
+
+<tr>
+ <td>org.apache.tapestry.global-class</td>
+
+ <td>
+ The fully qualified class name to instantiate as the engine global
+ property. The Global object is much like Visit object,
+ except that it is shared by all instances
+ of the application engine rather than being private to any particular session.
+ If not specified, a synchronized instance of HashMap is used.
+ </td>
+</tr>
+
+<tr>
+ <td>org.apache.tapestry.home-page</td>
+ <td>
+ The name of the page to be displayed by the home engine service (that is, the page initially
+ displayed when there's no other information in the request URL). The default is "Home".
+ </td>
+</tr>
+
+ <tr>
+ <td>org.apache.tapestry.jwcid-attribute-name</td>
+ <td>
+ Controls the attribute used to recognize the locations of contained components within
+ a <a href="template.html#template.components">component template</a>. The default is "jwcid".
+ </td>
+ </tr>
+
+<tr>
+ <td>org.apache.tapestry.messages-encoding</td>
+
+ <td>
+ Defines the character set used when reading the properties files comprising a
+ page or component <a href="localization.html#localization.component-catalog">message catalog</a>.
+ The default value is ISO-8859-1.
+
+
+ <p>
+ Please see the <a href="localization.html#localization.component-catalog.encoding">message catalog localization discussion</a>
+ for more information.
+ </p>
+ </td>
+</tr>
+
+
+<tr>
+ <td>org.apache.tapestry.output-encoding</td>
+
+ <td>
+ Defines the character set used by the application to encode its HTTP responses.
+ This is also the character set that the application assumes that the browser uses
+ when submitting data unless it is not specified differently in the HTTP request.
+
+ <p>
+ The default for this configuration property is UTF-8.
+ Normally there is no need to modify this value since UTF-8 allows almost all
+ characters to be correctly encoded and displayed.
+ </p>
+ </td>
+
+</tr>
+
+
+
+
+<tr>
+ <td>org.apache.tapestry.page-class-packages</td>
+ <td>
+ A comma-seperated list of package names, used when
+ <a href="page-class.html">searching for the page class</a>. These must
+ appear as <a href="spec.html#spec.meta"><meta></a> tags in the application or library specification
+ containing the page.
+ </td>
+</tr>
+
+ <tr>
+ <td>org.apache.tapestry.servlet-path</td>
+ <td>
+ Defines the servlet path used when constructing URLs. The default value is <code>/app</code>. Note that this is just
+ the <em>servlet path</em>. In many cases, the application will be inside a context; Tapestry will automatically prefix this
+ value with the correct value for the context. For example, workbench.war will by default be deployed with a context path of /workbench, and Tapestry will build URLs as
+ /workbench/app.
+ </td>
+
+ </tr>
+
+
+<tr>
+ <td>org.apache.tapestry.template-encoding</td>
+
+ <td>
+ Defines the character set used by the application templates.
+ The default value is ISO-8859-1.
+
+
+ <p>
+ Please see the <a href="localization.html#localization.template-encoding">template localization discussion</a>
+ for more information.
+ </p>
+ </td>
+</tr>
+
+ <tr>
+ <td>org.apache.tapestry.template-extension</td>
+
+ <td>
+ Overrides the default extension used to locate templates for pages or components.
+ The default extension is "html", this configuration property
+ allows overrides where appropriate. For example,
+ an application that produces WML may want to override this to "wml".
+
+
+ <p>
+ This configuration property does not follow the normal search path rules. The
+ <a href="spec.html#spec.meta"><meta></a> must be provided in the <a href="spec.html#spec.page-specification"><page-specification></a> or <a href="spec.html#spec.component-specification"><component-specification></a>.
+ If no value is found there, the immediate containing <a href="spec.html#spec.application"><application></a> or
+ <a href="spec.html#spec.library-specification"><library-specification></a> is checked. If still not found, the default is used.
+ </p>
+
+ </td>
+ </tr>
+
+ <tr>
+ <td>org.apache.tapestry.607-patch</td>
+
+ <td>
+ A workaround for <a href="http://issues.apache.org/jira/browse/TAPESTRY-607">TAPESTRY-607</a>, a problem
+ related to response character sets when using some versions of Tomcat 5. The Tomcat bug is
+ <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37072">37072</a>. This patch ensures that
+ HttpServletResponse.setContentType() is only invoked once, even if the output is reset (for instance, to
+ switch to the Tapestry exception page). The value must be set to true as a JVM system property.
+ </td>
+ </tr>
+
+ <tr>
+ <td>org.apache.tapestry.visit-class</td>
+
+ <td>
+ The fully qualified class name to instantiate as the
+ <a href="index.html#intro.engine-service-visit">Visit object</a>.
+
+ <p>
+ If not specified, an instance of HashMap will be created.
+ </p>
+
+ <p>
+ This is something of a holdover from Tapestry 3.0; for Tapestry 4.0, you will likely want to
+ override the default visit <a href="state.html#state.aso">application state object</a> (or simply add your own application state objects).
+ </p>
+
+ </td>
+ </tr>
+
+</table>
+</section> <!-- configuration.properties -->
+
+<section name="Application extensions">
+
+
+<p>
+<strong>Warning:</strong>
+<br/>
+ Application extensions are deprecated as of release 4.0. The use of <a href="http://jakarta.apache.org/hivemind/">HiveMind</a> services and
+ contributions eliminates the need for extensions.
+</p>
+
+<p>Tapestry is designed for flexibility; this extends beyond simply
+configuring the framework, and encompasses actually replacing or augmenting the implementation
+of the framework. If Tapestry doesn't do what you want it to, there are multiple paths
+for extending, changing and overriding its normal behavior.
+ In some cases,
+ it is necessary to subclass framework classes in order to alter behavior, but in
+ many cases, it is possible to use an application extension.
+ </p>
+
+<p>
+ Application extensions are JavaBeans declared in the application specification using
+ the <a href="spec.html#spec.extension"><extension></a> element. Each extension consists of a name, a Java class
+ to instantiate, and an optional configuration (that is, properties of the
+ bean may be set). The framework has a finite number of extension points. If an extension
+ bean with the correct name exists, it will be used at that extension point.
+ </p>
+
+ <p>
+ Your application may have its own set of extensions not related to Tapestry framework extension points.
+ For example, you might have an application extension referenced from multiple pages to perform common
+ operations such as JNDI lookups.
+ </p>
+
+ <p>
+ You may access application extensions via the engine's specification property. For example:
+ </p>
+
+<source xml:space="preserve">
+<a href="../tapestry/apidocs/org/apache/tapestry/IEngine.html">IEngine</a> engine = getEngine();
+<a href="../tapestry/apidocs/org/apache/tapestry/spec/IApplicationSpecification.html">IApplicationSpecification</a> specification = engine.getSpecification();
+
+MyExtension myExtension = (MyExtension) specification.getExtension("myExtension");
+</source>
+
+
+ <p>
+ Each application extension used with an framework extension point must implement an interface particular
+ to the extension point.
+ </p>
+
+<table>
+ <tr>
+ <th>Extension Name</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+<td>org.apache.tapestry.property-source </td> <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/IPropertySource.html">IPropertySource</a>
+</td>
+
+ <td>
+ This extension
+ is fit into the configuration property search path, after the servlet context, but
+ before JVM system properties. A typical use would be to access some set of configuration
+ properties stored in a database.
+ </td>
+</tr>
+
+
+
+ <tr>
+<td>org.apache.tapestry.request-decoder </td> <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/request/IRequestDecoder.html">IRequestDecoder</a>
+</td>
+ <td>
+ A request decoder is used
+ to identify the actual server name, server port, scheme and request URI for the
+ request. In some configurations, a firewall may invalidate the values provided by
+ the actual HttpServletRequest (the values reflect the internal server forwarded
+ to by the firewall, not the actual values used by the external client). A
+ request decoder knows how to determine the actual values.
+ </td>
+</tr>
+
+
+
+ <tr>
+<td>org.apache.tapestry.monitor-factory </td> <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/IMonitorFactory.html">IMonitorFactory</a>
+</td>
+
+ <td>An object that is used to create <a href="../tapestry/apidocs/org/apache/tapestry/engine/IMonitor.html">IMonitor</a> instances. Monitors
+ are informed about key application events (such as loading a page)
+ during the processing of a request.
+
+
+ <p>
+ The factory may create a new instance for the request, or may simply
+ provide access to a shared instance.
+ </p>
+
+ <p>
+ If not specified, a default implementation is used (<a href="../tapestry/apidocs/org/apache/tapestry/engine/DefaultMonitorFactory.html">DefaultMonitorFactory</a>).
+ </p>
+ </td>
+</tr>
+
+
+
+ <tr>
+<td>org.apache.tapestry.specification-resolver-delegate </td> <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/resolver/ISpecificationResolverDelegate.html">ISpecificationResolverDelegate</a>
+</td>
+
+ <td>
+ An object which is used to find page and component specifications that are not located
+ using the default search rules. The use of this is open-ended, but is generally
+ useful in very advanced scenarios where specifications are stored externally
+ (perhaps in a database), or constructed on the fly.
+ </td>
+</tr>
+
+
+
+ <tr>
+<td>org.apache.tapestry.template-source-delegate </td> <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/engine/ITemplateSourceDelegate.html">ITemplateSourceDelegate</a>
+</td>
+
+ <td>
+ An object which is used to find page or component templates that are not located
+ using the default search rules. The use of this is open-ended, but is generally
+ useful in very advanced scenarios where templates are stored externally
+ (perhaps in a database), or constructed on the fly.
+ </td>
+</tr>
+
+<tr>
+<td>org.apache.tapestry.ognl-type-converter</td> <td>ognl.TypeConverter</td>
+
+<td>
+Specifies an implementation of ognl.TypeConverter to be used for expression bindings.
+See OGNL's <a href="http://www.ognl.org/2.6.3/Documentation/html/typeConversion.html">Type
+ Converter documentation</a>
+for further information on implementing a custom type converter.
+</td>
+</tr>
+
+</table>
+
+</section> <!-- configuration.extensions -->
+
+
+
+</body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/configuration.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/events.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/events.xml?rev=418665&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/events.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/events.xml Sun Jul 2 17:17:29 2006
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2005 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>Page Events</title>
+</properties>
+<body>
+
+<p>
+Tapestry component and page classes may implement <em>optional listener interfaces</em>. This interfaces
+allow the component (or page) to be notified when certain lifecycle events occur. Each interface
+consists of a single method.
+</p>
+
+<p>
+It is merely necessary to implement the interface; the framework will automatically register
+the component (or page) to receive the notification. It is perfectly acceptible to implement
+multiple interfaces.
+</p>
+
+<table>
+ <tr>
+ <th>Interface</th>
+ <th>Invoked</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/event/PageAttachListener.html">PageAttachListener</a>
+</td>
+ <td>When a page is first attached to the current request. After
+ the page's persistent properties have been rolled back.</td>
+ <td>
+ Set up the page's properties based on the current session state, possibly
+ by pulling data from an <a href="state.html#state.aso">application state object</a>.
+ </td>
+ </tr>
+ <tr>
+ <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/event/PageValidateListener.html">PageValidateListener</a>
+</td>
+ <td>When a page is activated (selected to render the reponse). Throw <a href="../tapestry/apidocs/org/apache/tapestry/PageRedirectException.html">PageRedirectException</a>
+ to activate a different page.</td>
+ <td>
+ Typically, checking the user's allowed access to a page, based on application-specific
+ security rules.
+ </td>
+ </tr>
+ <tr>
+ <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/event/PageBeginRenderListener.html">PageBeginRenderListener</a>
+</td>
+ <td>Just before the page begins to render. This is the last chance to update
+ persistent page properties.</td>
+ <td/>
+ </tr>
+ <tr>
+ <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/event/PageEndRenderListener.html">PageEndRenderListener</a>
+</td>
+ <td>At the end of the page render (even if an exception is thrown while the page
+ renders).</td>
+ <td/>
+ </tr>
+ <tr>
+ <td>
+<a href="../tapestry/apidocs/org/apache/tapestry/event/PageDetachListener.html">PageDetachListener</a>
+</td>
+ <td>As the page is detached from the request and returned to the shared page
+ pool.</td>
+ <td>
+ Final cleanups to "scrub" the page, remove any client-specific state, and otherwise
+ return it to a pristine state.
+ </td>
+ </tr>
+</table>
+
+<p>
+<strong>Note:</strong>
+<br/>
+ Tapestry 3.0 defined a single <a href="../tapestry/apidocs/org/apache/tapestry/event/PageRenderListener.html">PageRenderListener</a> interface instead of
+ <a href="../tapestry/apidocs/org/apache/tapestry/event/PageBeginRenderListener.html">PageBeginRenderListener</a> and <a href="../tapestry/apidocs/org/apache/tapestry/event/PageEndRenderListener.html">PageEndRenderListener</a>. This is still supported in 4.0 (it
+ has been redefined as extending the other two interfaces), but will likely be removed
+ in a future release.
+</p>
+</body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/events.xml
------------------------------------------------------------------------------
svn:eol-style = native