tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jkuhn...@apache.org
Subject 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...
Date Mon, 03 Jul 2006 00:17:31 GMT
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">
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;title&gt;Tutorial: HelloWorld&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+    &lt;h1&gt;HelloWorld Tutorial&lt;/h1&gt;
+  &lt;/body&gt;
+&lt;/html&gt;
+</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">
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;!DOCTYPE web-app
+      PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+      "http://java.sun.com/dtd/web-app_2_3.dtd"&gt;
+
+&lt;web-app&gt;
+  &lt;display-name&gt;Tutorial: HelloWorld&lt;/display-name&gt;
+  &lt;servlet&gt;
+    &lt;servlet-name&gt;app&lt;/servlet-name&gt;
+    &lt;servlet-class&gt;org.apache.tapestry.ApplicationServlet&lt;/servlet-class&gt;
+    &lt;load-on-startup&gt;0&lt;/load-on-startup&gt;
+  &lt;/servlet&gt;
+  &lt;servlet-mapping&gt;
+    &lt;servlet-name&gt;app&lt;/servlet-name&gt;
+    &lt;url-pattern&gt;/app&lt;/url-pattern&gt;
+  &lt;/servlet-mapping&gt;
+&lt;/web-app&gt;
+</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">
+&lt;html&gt;
+  &lt;head&gt;
+    &lt;title&gt;Tutorial: HelloWorld&lt;/title&gt;
+  &lt;/head&gt;
+  &lt;body&gt;
+    &lt;h1&gt;HelloWorld Tutorial&lt;/h1&gt;
+    
+&lt;p&gt;
+  The current data and time is: 
+  &lt;strong&gt;&lt;span jwcid="@Insert" value="ognl:new java.util.Date()"&gt;June 26 2005&lt;/span&gt;&lt;/strong&gt;
+&lt;/p&gt;    
+    
+  &lt;/body&gt;
+&lt;/html&gt;
+</source>
+
+<p>
+The &lt;span&gt; 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 (&lt;span&gt;) and end (&lt;/span&gt;)
+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>&lt;span jwcid="@Insert" value="ognl:new java.util.Date()"/&gt;</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">
+&lt;p&gt;
+  &lt;a href="#" jwcid="@PageLink" page="Home"&gt;refresh&lt;/a&gt;
+&lt;/p&gt;
+</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&amp;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">
+  &lt;a href="/app?service=page&amp;amp;page=Home"&gt;refresh&lt;/a&gt;
+</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 &lt;a&gt; 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">&lt;bean&gt;</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">&lt;inject&gt;</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">&lt;component-specification&gt;</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">&lt;page-specification&gt;</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">&lt;component&gt;</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">&lt;component-type&gt;</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 &lt;a&gt; 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 &lt;a&gt;	
+}
+</source>
+
+	
+<p>
+The <code>begin()</code>	 method renders an open tag (the &lt;a&gt;, in
+this case). The <code>end()</code> method renders
+the corresponding &lt;/a&gt;. 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 &lt;img&gt;	 element. These informal parameters
+can be specified in the page's HTML template, or within the <a href="spec.html#spec.component">&lt;component&gt;</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">&lt;parameter&gt;</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">&lt;parameter&gt;</a> element.  This
+is, effectively, a binding to use if no binding is provided.
+</p>
+
+<source xml:space="preserve">
+  &lt;parameter name="title" default-value="literal:Link to current thread"/&gt;
+</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">
+  &lt;parameter name="title"  default-value="message:link-title"/&gt;  
+</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">&lt;parameter&gt;</a> element to
+use a different property name:
+</p>
+
+<source xml:space="preserve">
+&lt;parameter name="title" property="titleParameter"/&gt;  
+</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">&lt;parameter&gt;</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">&lt;library&gt;</a> element.
+</p>
+
+<p>
+The <a href="spec.html#spec.library">&lt;library&gt;</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">
+&lt;application name="Example Application"&gt;
+      
+  &lt;library id="contrib" specification-path="/org/apache/tapestry/contrib/Contrib.library"/&gt;
+  	
+&lt;/application&gt;</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">	
+&lt;span jwcid="palette@contrib:Palette" . . . /&gt;
+</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">
+&lt;component id="palette" type="contrib:Palette"&gt;
+  . . .
+&lt;/component&gt;
+</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">&lt;component-type&gt;</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">&lt;asset&gt;</a> element of
+the page or component specification.	For example:
+</p>
+
+<source xml:space="preserve">
+	
+  &lt;asset name="logo" path="images/logo_200.png"/&gt;
+  
+  &lt;component id="image" type="Image"&gt;
+    &lt;binding name="image" value="asset:logo"/&gt;
+  &lt;/component&gt;
+</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">&lt;library-specification&gt;</a>, which supports a subset of the attributes
+allowed within an <a href="spec.html#spec.application">&lt;application&gt;</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">
+&lt;!DOCTYPE library-specification PUBLIC 
+  "-//Apache Software Foundation//Tapestry Specification 3.0//EN" 
+  "http://jakarta.apache.org/tapestry/dtd/Tapestry_3_0.dtd"&gt;
+	
+&lt;library-specification/&gt;
+</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">&lt;library&gt;</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">&lt;library&gt;</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">
+  &lt;a href="#" jwcid="@PageLink" page="OtherPage" namespace="ognl:namespace"&gt; ... &lt;/a&gt;	
+</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">
+&lt;?xml version="1.0"?&gt;
+&lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
+ "http://java.sun.com/dtd/web-app_2_3.dtd"&gt;
+&lt;web-app&gt;
+  &lt;display-name&gt;My Application&lt;/display-name&gt;
+  
+  &lt;servlet-mapping&gt;
+    &lt;servlet-name&gt;myapp&lt;/servlet-name&gt;
+    &lt;url-pattern&gt;/app&lt;/url-pattern&gt; 
+  &lt;/servlet-mapping&gt;
+  
+  &lt;filter&gt; 
+    &lt;filter-name&gt;redirect&lt;/filter-name&gt;
+    &lt;filter-class&gt;org.apache.tapestry.RedirectFilter&lt;/filter-class&gt;
+  &lt;/filter&gt;
+	
+  &lt;filter-mapping&gt;
+    &lt;filter-name&gt;redirect&lt;/filter-name&gt;
+    &lt;url-pattern&gt;/&lt;/url-pattern&gt;
+  &lt;/filter-mapping&gt;
+
+  &lt;servlet&gt;
+    &lt;servlet-name&gt;myapp&lt;/servlet-name&gt;
+    &lt;servlet-class&gt;org.apache.tapestry.ApplicationServlet&lt;/servlet-class&gt; 
+    &lt;load-on-startup&gt;0&lt;/load-on-startup&gt;
+  &lt;/servlet&gt;
+  
+  &lt;session-config&gt;
+  	&lt;session-timeout&gt;15&lt;/session-timeout&gt;
+  &lt;/session-config&gt;
+    
+  &lt;welcome-file-list&gt;
+    &lt;welcome-file&gt;index.html&lt;/welcome-file&gt;
+  &lt;/welcome-file-list&gt;
+&lt;/web-app&gt;
+
+</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 
+&lt;load-on-startup&gt;, 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">&lt;meta&gt;</a> of the <a href="spec.html#spec.application">&lt;application&gt;</a> (in the application specification,
+		if the application uses one).
+	</li>
+	<li>
+		As an &lt;init-parameter&gt;
+		for the servlet, in the web application deployment descriptor.
+	</li>
+	<li>
+		As an &lt;init-parameter&gt;
+		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 &lt;init-parameter&gt;
+		for the servlet, in the web application deployment descriptor.
+	</li>
+	<li>
+		As an &lt;init-parameter&gt;
+		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">&lt;bean&gt;</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">&lt;meta&gt;</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">&lt;page-specification&gt;</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">&lt;meta&gt;</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">&lt;meta&gt;</a> must be provided in the <a href="spec.html#spec.page-specification">&lt;page-specification&gt;</a> or <a href="spec.html#spec.component-specification">&lt;component-specification&gt;</a>.
+	If no value is found there, the immediate containing <a href="spec.html#spec.application">&lt;application&gt;</a> or
+	<a href="spec.html#spec.library-specification">&lt;library-specification&gt;</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">&lt;extension&gt;</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



Mime
View raw message