You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by hl...@apache.org on 2004/03/02 23:35:35 UTC
cvs commit: jakarta-tapestry/doc/src/UsersGuide/images parameter-bindings.png write-binding.png parameter-manager.png core-classes.png read-binding.png
hlship 2004/03/02 14:35:35
Modified: doc/src/UsersGuide state.xml intro.xml components.xml
script-spec.xml template.xml UsersGuideFigures.vsd
spec.xml configuration.xml TapestryUsersGuide.xml
build.xml
Added: doc/src/UsersGuide jars.xml
doc/src/UsersGuide/images parameter-bindings.png
write-binding.png parameter-manager.png
core-classes.png read-binding.png
Log:
Add much content to the User's Guide.
Revision Changes Path
1.10 +41 -8 jakarta-tapestry/doc/src/UsersGuide/state.xml
Index: state.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/state.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- state.xml 28 Jan 2004 19:23:18 -0000 1.9
+++ state.xml 2 Mar 2004 22:35:34 -0000 1.10
@@ -1,5 +1,19 @@
<!-- $Id$ -->
-
+<!--
+ Copyright 2004 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.
+-->
<chapter id="state">
<title>Managing server-side state</title>
@@ -67,7 +81,7 @@
<para>
Different application servers implement &HttpSession; replication and failover in different ways; the servlet API
-specification is delibrately unspecific on how this implementation should take place. Tapestry
+specification is delibrately non-specific on how this implementation should take place. Tapestry
follows the conventions of the most limited interpretation of the servlet specification; it assumes
that attribute replication only occurs when the &HttpSession; <function>setAttribute()</function>
method is invoked
@@ -149,7 +163,7 @@
<para>
Tapestry doesn't mandate anything about the Visit object's class. The type of the
<literal>visit</literal> property is &Object;. In Java code, accessing the Visit object
-involves a cast
+involves a cast from &Object; to an application-specific class.
The following example demonstrates how a &listener-method;
may access the visit object.
</para>
@@ -308,7 +322,7 @@
<para>
For this scheme to work it is important that at the end of the request cycle, the page must return
to its pristine state. The prisitine state is equivalent to a freshly created instance of the page. In other words, any
-properties of the page that changed during the processing of the request must be returned to thier initial values.
+properties of the page that changed during the processing of the request must be returned to their initial values.
</para>
<para>
@@ -316,6 +330,18 @@
the same end user, or for another user entirely.
</para>
+<note>
+ <title>Importance of resetting properties</title>
+
+ <para>
+ Imagine a page containing a form in which a user enters their address and credit card information. When
+ the form is submitted, properties of the page will be updated with the values supplied by the user.
+ Those values must be cleared out before the page is stored into the page pool ... if not, then the <emphasis>next</emphasis>
+ user who accesses the page will see the previous user's address and credit card information as default
+ values for the form fields!
+ </para>
+</note>
+
<para>
Tapestry separates the persistent state of a page from any instance of the page.
This is very important, because
@@ -351,13 +377,13 @@
<para>
Persistent properties make use of a &spec.property-specification; element in the
page or component specification. Tapestry does something special when a component
-contains any such elements; it dynamically generates a subclass that provides the desired fields,
+contains any such elements; it dynamically fabricates a subclass that provides the desired fields,
methods and whatever extra initialization or cleanup is required.
</para>
<para>
You may also, optionally, make your class abstract, and define abstract accessor methods that will
-be filled in by Tapestry in the generated subclass. This allows you to read and update properties inside
+be filled in by Tapestry in the fabricated subclass. This allows you to read and update properties inside
your class, inside listener methods.
</para>
@@ -414,7 +440,7 @@
<property-specification
name="itemsPerPage"
persistent="yes"
- type="int"initial-value="10"/>
+ type="int" initial-value="10"/>
</page-specification>
]]>
@@ -440,6 +466,13 @@
and uses at the end of each request cycle
to reset the property back to its "pristine" state.
</para>
+
+<warning>
+<para>
+The previous paragraph may not be accurate; I believe Mindbridge may have changed this behavior
+recently.
+</para>
+</warning>
<para>
This means that you may perform initialization for the property inside
1.5 +20 -6 jakarta-tapestry/doc/src/UsersGuide/intro.xml
Index: intro.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/intro.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- intro.xml 28 Jan 2004 19:23:18 -0000 1.4
+++ intro.xml 2 Mar 2004 22:35:34 -0000 1.5
@@ -1,5 +1,19 @@
<!-- $Id$ -->
-
+<!--
+ Copyright 2004 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.
+-->
<chapter id="intro">
<title>Introduction</title>
@@ -45,7 +59,7 @@
<para>
This document describes many of the internals of Tapestry. It is not a tutorial,
-that is available as a separate document. Instead, this document is a guide to
+that is available as a separate document. Instead, this is a guide to
some of the internals of Tapestry, and is intended for experienced developers
who wish to leverage Tapestry fully.
</para>
@@ -192,7 +206,7 @@
<para>
The Engine is a central object, it occupies the same semantic space in Tapestry that the
&HttpSession; does in the Servlet API. The Engine is ultimately responsible for
-storing the persistant state of the application (properties that exist from one request to
+storing the persistent state of the application (properties that exist from one request to
the next), and this is accomplished by storing the Engine into the &HttpSession;.
This document will largely discuss the <emphasis>default</emphasis> implementation,
with notes about how the default implementation may be extended or overriden, where appropriate.
@@ -213,7 +227,7 @@
is an application-defined object that acts as a focal point
for all server-side state (not associated with any single page). Individual applications define for themselves
the class of the Visit object. The Visit is stored as a property of the Engine, and so is ultimately
-stored persistantly in the &HttpSession;
+stored persistently in the &HttpSession;
</para>
<para>
@@ -228,7 +242,7 @@
<title>Object Graph Navigation Language</title>
<para>
-Tapestry is highly integrated with &OGNL;, the Object Graph Navigation Language. OGNL is a Java expression language, which is used
+Tapestry is tightly integrated with &OGNL;, the Object Graph Navigation Language. OGNL is a Java expression language, which is used
to peek into objects and read or update their properties. OGNL is similar to, and must more powerful than,
the expression language built into the JSP 2.0 standard tag library. OGNL not only support property access,
it can include mathematical expressions and method invocations. It can reference static fields of public classes.
1.2 +530 -1 jakarta-tapestry/doc/src/UsersGuide/components.xml
Index: components.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/components.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- components.xml 28 Jan 2004 19:23:18 -0000 1.1
+++ components.xml 2 Mar 2004 22:35:34 -0000 1.2
@@ -1,5 +1,534 @@
-<chapter id="components">
+<!-- $Id$ -->
+<!--
+ Copyright 2004 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.
+-->
+ <chapter id="components">
<title>Creating Tapestry components</title>
+
+
+<section id="components.intro">
+ <title>Introduction</title>
+
+<para>
+Tapestry is a component based web application framework; components, objects which implement
+the &IComponent; interface, are the fundamental building blocks of Tapestry. Additional objects,
+such as the the engine, &IMarkupWriter; and the request cycle are infrastructure. The following figure
+identifies the core Tapestry classes and interfaces.
+</para>
+
+<figure>
+ <title>Core Tapestry Classes and Interfaces</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/core-classes.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+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 <link linkend="components.libraries">component library</link>.
+</para>
+
+<para>
+All the techniques used with pages work with components as well ... pages are a specialized kind
+of Tapestry component. This includes
+<link linkend="state.page-properties">specified properties</link> (including persistent properties)
+and &listener-method;s.
+</para>
+
+<para>
+Components fit into the overall page rendering process because they implement the &IRender; interface.
+Components that inherit from &BaseComponent; will use an HTML template. Components that inherit
+from &AbstractComponent; will render output in Java code, by implementing method
+<function>renderComponent()</function>.
+</para>
+
+<para>
+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.
+</para>
+
+</section> <!-- components.intro -->
+
+<section id="components.spec">
+ <title>Component Specifications</title>
+
+<para>
+Every component has a component specification, a file ending in <filename>.jwc</filename> whose
+root element is &spec.component-specification;.
+</para>
+
+<para>
+Each component's specification defines the basic characteristics of the component:
+<itemizedlist>
+ <listitem>
+ <para>The Java class for the component (which defaults to &BaseComponent;)</para>
+ </listitem>
+ <listitem>
+ <para>Whether the component uses its body, or discards it (the <literal>allow-body</literal> attribute,
+ which defaults to <literal>yes</literal>)</para>
+ </listitem>
+ <listitem>
+ <para>
+ The name, type and other information for each <emphasis>formal</emphasis>
+ parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Whether the component allows informal parameters or discards them
+ (the <literal>allow-informal-parameters</literal> attribute, which defaults to
+ <literal>yes</literal>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The names of any <emphasis>reserved parameters</emphasis> which may <emphasis>not</emphasis>
+ be used as informal parameters.
+ </para>
+ </listitem>
+</itemizedlist>
+</para>
+
+<para>
+Beyond those additions, a component specification is otherwise the same as a &spec.page-specification;.
+</para>
+
+<para>
+When a component is referenced in an HTML template (using the <literal>@<replaceable>Type</replaceable></literal>
+syntax), or in a specification (as the <literal>type</literal> attribute of
+a &spec.component; element), Tapestry must locate and parse the component's specification (this is only done once, with the
+result cached for later).
+</para>
+
+<para>
+Tapestry searches for components in the following places:
+<itemizedlist>
+ <listitem>
+ <para>As specified in a &spec.component-type; element (with the application specification)</para>
+ </listitem>
+ <listitem>
+ <para>In the same folder (typically, <filename>WEB-INF</filename> ) as the
+ application specification</para>
+ </listitem>
+ <listitem>
+ <para>
+ In the <filename>WEB-INF/<replaceable>servlet-name</replaceable></filename> folder
+ (<replaceable>servlet-name</replaceable> is the name of the Tapestry &ApplicationServlet;
+ for the application)
+ <footnote>
+ <para>
+ This is a very rare option that will only occur when a single WAR file contains
+ multiple Tapestry applications.
+ </para>
+ </footnote>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the <filename>WEB-INF</filename> folder
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the root context directory
+ </para>
+ </listitem>
+</itemizedlist>
+</para>
+
+<para>
+Generally, the <emphasis>correct</emphasis> place is in the
+<filename>WEB-INF</filename> folder. <link linkend="components.libraries">Components packaged into
+ libraries</link> have a different (and simpler) search.
+</para>
+
+
+</section> <!-- components.spec -->
+
+<section id="components.coding">
+ <title>Coding components</title>
+
+<para>
+When creating a new component by subclassing &AbstractComponent;, you must write the
+<function>renderComponent()</function> method. This method is invoked when the components container (typically, but not always,
+a page) invokes its own <function>renderBody()</function> method.
+</para>
+
+<programlisting>
+protected void renderComponent(&IMarkupWriter; writer, &IRequestCycle; cycle)
+{
+ . . .
+}
+</programlisting>
+
+<para>
+The &IMarkupWriter; object is used to produce output. It contains a number of <function>print()</function> methods
+that output text (the method is overloaded for different types). It also contains <function>printRaw()</function>
+methods -- the difference being that <function>print()</function> uses a filter to convert certain characters
+into HTML entities.
+</para>
+
+
+<para>
+&IMarkupWriter; also includes methods to simplify creating markup style output: that is, elements with attributes.
+</para>
+
+
+<para>
+For example, to create a <sgmltag class="starttag">a</sgmltag> link:
+
+<informalexample>
+<programlisting>
+writer.begin("a");
+writer.attribute("url", url);
+writer.attribute("class", styleClass);
+
+renderBody(writer, cycle);
+
+writer.end(); // close the <a>
+</programlisting>
+</informalexample>
+ </para>
+
+<para>
+The <function>begin()</function> method renders an open tag (the <sgmltag class="starttag">a</sgmltag>, in
+this case). The <function>end()</function> method renders
+the corresponding <sgmltag class="closetag">a</sgmltag>. As you can see, writing attributes into the tag
+is very simple.
+</para>
+
+
+<para>
+The call to <function>renderBody()</function> is used to render <emphasis>this</emphasis> component's
+body. A component doesn't have to render its body; the standard &Image; component doesn't render its
+body (and its component specification indicates that it discards its body). The &Conditional; component
+decides whether or not to render its body, and the
+&Foreach; component may render its body multiple times.
+</para>
+
+<para>
+A component that allows informal parameters can render those as well:
+
+<informalexample><programlisting>
+writer.beginEmpty("img");
+writer.attribute("src", imageURL);
+renderInformalParameters(writer, cycle);
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+This example will add any informal parameters for the component
+as additional attributes within the <sgmltag class="starttag">img</sgmltag> element. These informal parameters
+can be specified in the page's HTML template, or within the &spec.component; tag of the page's specification. Note the use
+of the <function>beginEmpty()</function> method, for creating a start tag that is not balanced with an end tag (or
+a call to the <function>end()</function> method).
+</para>
+
+</section> <!-- components.coding -->
+
+<section id="components.parameters">
+ <title>Component Parameters</title>
+
+<para>
+A Tapestry page consists of a number of components. These components communicate with, and coordinate with,
+the page (and each other) via <emphasis>parameters</emphasis>.
+</para>
+
+<para>
+A component parameter has a unique name and a type (a Java class, interface, or primitive type name).
+The &spec.parameter; component specification element is used to define formal component parameters.
+</para>
+
+<para>
+In a traditional desktop application, components have <emphasis>properties</emphasis>. A controller may
+set the properties of a component, but that's it: properties are write-and-forget.
+</para>
+
+<para>
+The Tapestry model is a little more complex. A component's parameters are <emphasis>bound</emphasis>
+to properties of the enclosing page. The component is allowed to read its parameter, to access
+the page property the parameter is bound to. A component may also <emphasis>update</emphasis> its
+parameter, to force a change to the bound page property.
+</para>
+
+<para>
+The vast majority of components simply read their parameters. Updating parameters is more rare; the most
+common components that update their parameters are form control components such as &TextField; or &Checkbox;.
+</para>
+
+<para>
+Because bindings are in the form of &OGNL; expressions, the property bound to a component parameter
+may not directly be a property of the page ... using a property sequence allows great flexibility.
+</para>
+
+<figure>
+ <title>Parameter Bindings</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/parameter-bindings.png" format="PNG"/>
+ </imageobject>
+ <caption>
+ <para>
+Using &OGNL;, the &TextField; component's <varname>value</varname> parameter is bound
+to the <classname>LineItem</classname>'s <varname>quantity</varname> property, using
+the OGNL expression <literal>lineItem.quantity</literal>, and the &Insert; component's
+<varname>value</varname> parameter is bound to the <classname>Product</classname>'s
+<varname>name</varname> property using the OGNL expression <literal>lineItem.product.name</literal>.
+
+ </para>
+ </caption>
+ </mediaobject>
+</figure>
+
+<para>
+Not all parameter bindings are writable. So far, the examples have been for parameters bound using
+the &spec.binding; specification element (or the equivalent use of the <literal>ognl:</literal> prefix
+in an HTML template). <emphasis>Invariant bindings</emphasis> are also possible--these are bindings directly to fixed
+values that never change and can't be updated. The &spec.static-binding; element is invariant; it's
+HTML template equivalent is a attribute with no prefix. Likewise, the
+&spec.message-binding; element, and the <literal>message:</literal> prefix on an attribute, are invariant.
+</para>
+
+<section id="components.parameters.bindings">
+ <title>Using Bindings</title>
+
+<para>
+To understand how Tapestry parameters work, you must understand how the binding objects work (even
+though, as we'll see, the binding objects are typically hidden). When a component needs access to
+a bound parameter value, it will invoke the method <code>getObject()</code> on &IBinding;
+</para>
+
+
+<figure>
+ <title>Reading a Parameter</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/read-binding.png" format="PNG"/>
+ </imageobject>
+ <caption>
+ <para>
+The <function>getObject()</function> method on &IBinding; will (if the binding is dynamic) evaluate the
+OGNL expression (provided in the &spec.binding; specification element) to access a property of the
+page. The result is that cast or otherwise coerced to a type useful to the component.
+ </para>
+ </caption>
+ </mediaobject>
+</figure>
+
+
+<para>
+Updating a parameter is the same way, except that the method is
+<function>setObject()</function>. Most of the implementations of &IBinding; (those for literal strings
+and localize messages), will throw an exception immediately, since they are invariant.
+</para>
+
+<figure>
+ <title>Writing a Parameter</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/write-binding.png" format="PNG"/>
+ </imageobject>
+ <caption>
+ <para>
+The <function>setObject()</function> method will use OGNL to update a page property.
+ </para>
+ </caption>
+ </mediaobject>
+</figure>
+
+<para>
+These flows are complicated by the fact that parameters may be optional; so not only do you need to acquire the
+correct binding object (method <function>getBinding()</function> defined in &IComponent;),
+but your code must be prepared for that object to be null (if the parameter
+is optional).
+</para>
+
+</section> <!-- components.parameters.bindings -->
+
+<section id="components.parameters.connected">
+ <title>Connected Parameter Properties</title>
+
+<para>
+Accessing and manipulating the &IBinding; objects is tedious, so Tapestry has an alternate approach. Parameters may
+be represented as <emphasis>connected parameter properties</emphasis> that hide the existence of
+the binding objects entirely. If you component needs to know the value bound to a parameter, it can
+read the connected parameter property. If it wants to update the property bound to the parameter, the component
+will update the connected parameter. This is a much more natural approach, but requires a little bit of setup.
+</para>
+
+<para>
+As with <link linkend="state.page-properties">specified properties</link>, Tapestry will fabricate an enhanced subclass with
+the necessary instance variables, accessor methods, and cleanup code.
+</para>
+
+<para>
+Connected parameters are controlled by the <varname>direction</varname>
+attribute of the &spec.parameter; element.
+<footnote>
+<para>
+ The name, "direction", made sense initially, but is now a bit confusing. It probably
+ should have been called "processing" or "connection-type".
+</para>
+</footnote>
+There are four values:
+<literal>in</literal>, <literal>form</literal>, <literal>auto</literal>
+and <literal>custom</literal>. The default is <literal>custom</literal>, which
+<emphasis>does not</emphasis> create a connected parameter property at all.
+</para>
+
+<section id="components.parameters.connected.in">
+ <title>Direction: in</title>
+
+<para>
+The majority of component parameters are read-only, and are only actually used
+within the component's <function>renderComponent()</function> method ... the method that
+actually produces HTML output. For such components, direction <literal>in</literal>
+is the standard, efficient choice.
+</para>
+
+<para>
+The connected parameter for each component is set just before <function>renderComponent()</function>
+is invoked. The parameter is reset to its initial value just after
+<function>renderComponent()</function> is invoked.
+</para>
+
+<para>
+Each component has a &ParameterManager;, whose responsibility is to set and reset connected
+parameter properties.
+</para>
+
+<figure>
+ <title>ParameterManager and <function>renderComponent()</function></title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/parameter-manager.png" format="PNG"/>
+ </imageobject>
+ <caption>
+ <para>
+The &ParameterManager; will read the values bound to each parameter, and update the
+connected parameter property before the component's <function>renderComponent()</function>
+method is invoked. The &ParameterManager; cleans up after <function>renderComponent()</function>
+is invoked.
+ </para>
+ </caption>
+ </mediaobject>
+</figure>
+
+<para>
+For invariant bindings (literal strings and such), the ParameterManager will only set the connected parameter property once,
+and does not reset the property after <function>renderComponent()</function>.
+</para>
+
+<warning>
+ <para>
+ If your component has any &listener-method;s that need to access a parameter value, then you
+ can't use direction <literal>in</literal> (or direction <literal>form</literal>). Listener methods are
+ invoked outside of the page rendering process, when value stored in the
+ connected parameter property is not set. You must use direction <literal>auto</literal> or
+ <literal>custom</literal> in such cases.
+ </para>
+</warning>
+
+
+</section> <!-- components.parameters.connected.in -->
+
+<section id="components.parameters.connected.form">
+ <title>Direction: form</title>
+
+<para>
+Components, such as &TextField; or &Checkbox;, that produce form control elements are the
+most likely candidates for updating their parameters. The read a parameter (usually named
+<varname>value</varname>) when they render. When the form is submitted, the same components
+read a query parameter and update their <varname>value</varname> parameter.
+</para>
+
+<para>
+The <literal>form</literal> direction simplifies this. For the most part, <literal>form</literal>
+is the same as <literal>in</literal>. The diffference is, when the form is submitted, after the
+component's <function>renderComponent()</function> method has been invoked, the connected parameter property
+is read and used to update the binding (that is, invoke the binding object's <function>setObject()</function>
+method).
+</para>
+
+</section> <!-- components.parameters.connected.form -->
+
+<section id="components.parameters.connected.auto">
+ <title>Direction: auto</title>
+
+<para>
+The previous direction values, <literal>in</literal> and <literal>form</literal>, have limitations. The value may only be
+accessed from within the component's <function>renderComponent()</function> method. That's often insufficient,
+especially when the component has a &listener-method; that needs access to a parameter.
+</para>
+
+<para>
+Direction <literal>auto</literal> doesn't use the &ParameterManager;. Instead, the connected parameter property
+is <emphasis>synthetic</emphasis>. Reading the property immediately turns around and invokes
+&IBinding;'s <function>getObject()</function> method. Updating the property invokes
+the &IBinding;'s <function>setObject()</function> function.
+</para>
+
+<para>
+This can be a bit less efficient than direction <literal>in</literal>, as the &OGNL; expression may be
+evaluated multiple times. In Tapestry 3.0, there are other limitations: the parameter must either be an object type,
+or one of a limited number of primitive Java types: boolean, int or double. The parameter must also be required. Future releases
+of Tapestry will relax these limitations.
+</para>
+
+<note>
+ <title>Removing parameter directions</title>
+ <para>
+Parameter directions are a bit of a sore spot: you must make too many decisions about how to use them, especially
+in terms of render-time-only vs. &listener-method;. Direction <literal>auto</literal> is too limited and
+possibly too inefficient. Tapestry 3.1 should address these limitations by improving direction
+<literal>auto</literal>. Instead of specifying a direction, you'll specify how long the component can cache the
+value obtained from the binding object (no caching, or only while the component is rendering, or until
+the page finishes rendering).
+ </para>
+</note>
+
+</section> <!-- components.parameters.connected.auto -->
+
+<section id="components.parameters.connected.custom">
+ <title>Direction: custom</title>
+
+<para>
+The <literal>custom</literal> direction, which is the default, <emphasis>does not</emphasis>
+create a connected parameter property. Your code is still responsible for
+accessing the &IBinding; object (via the <function>getBinding()</function> method of
+&IComponent;) and for invoking methods on the binding object.
+</para>
+
+</section> <!-- components.parameters.connected.custom -->
+
+</section> <!-- components.parameters.connected -->
+
+</section> <!-- components.parameters -->
+
+
+
+<section id="components.libraries">
+ <title>Component Libraries</title>
+
+</section> <!-- components.libraries -->
</chapter>
1.6 +16 -2 jakarta-tapestry/doc/src/UsersGuide/script-spec.xml
Index: script-spec.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/script-spec.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- script-spec.xml 11 Jul 2003 20:50:57 -0000 1.5
+++ script-spec.xml 2 Mar 2004 22:35:34 -0000 1.6
@@ -1,5 +1,19 @@
<!-- $Id$ -->
-
+<!--
+ Copyright 2004 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.
+-->
<appendix id="script-spec">
<title>Tapestry Script Specification DTD</title>
1.4 +46 -20 jakarta-tapestry/doc/src/UsersGuide/template.xml
Index: template.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/template.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- template.xml 28 Jan 2004 19:23:18 -0000 1.3
+++ template.xml 2 Mar 2004 22:35:34 -0000 1.4
@@ -1,5 +1,19 @@
<!-- $Id$ -->
-
+<!--
+ Copyright 2004 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.
+-->
<chapter id="template">
<title>Page and component templates</title>
@@ -47,7 +61,8 @@
</listitem>
<listitem>
<para>
- In the web application's context root directory (if the page is an application page, not a page from a library)
+ In the web application's context root directory (if the page is an application page, not a page from a component
+ library)
</para>
</listitem>
</itemizedlist>
@@ -110,7 +125,7 @@
<para>
A larger goal is to support real project teams: The special markup for Tapestry is unobtrusive, even invisible.
This allows an HTML designer to work on a template without breaking the dynamic portions of it. This is completely unlike
-JSPs, where the changes to support dynamic output are exteremly obtrusive and result in a file that is meaningless to an HTML
+JSPs, where the changes to support dynamic output are extremelyobtrusive and result in a file that is meaningless to an HTML
editor.
</para>
@@ -296,7 +311,8 @@
<title>Specifying parameters</title>
<para>
-Component parameters may always be specified in the specifiction, using the
+Component parameters may always be specified in the page or component
+specification, using the
&spec.binding;, &spec.static-binding; and &spec.message-binding; elements. Prior to Tapestry 3.0, that
was the only way ... but with 3.0, it is possible to specify parameters directly within the
HTML template.
@@ -329,7 +345,7 @@
<para>
Before Tapestry 3.0, there was a more clear separation of concerns. The template could only have declared
components (not implicit), and any informal attributes in the template were always static values. The type
-of the component and all its formal parameters were in the specification. The template was very much
+of the component and all its formal parameters were always expressed in the specification. The template was very much
focused on presentation, and the specification was very much focused on business logic. There were
always minor exceptions to the rules, but in general, seperation of concerns was very good.
</para>
@@ -369,8 +385,8 @@
<sidebar>
<para>
If you are used to developing with JSPs and JSP tags, this will be quite a difference. JSP tags have
-the equivalent of formal parameters, but nothing like informal parameters. Often a relatively
-simply JSP tag must be bloated out with dozens of extra attributes, to support arbitrary
+the equivalent of formal parameters (they are called "tag attributes"), but nothing like informal parameters. Often a relatively
+simply JSP tag must be bloated with dozens of extra attributes, to support arbitrary
HTML attributes.
</para>
</sidebar>
@@ -435,8 +451,9 @@
</para>
<para>
-Tapestry supports a limited number of additional directives that are about component placement, but address
-other concerns of integrating the efforts of HTML developers with the Java developers responsible
+Tapestry supports a limited number of additional directives that are not about component placement, but
+instead address other concerns about integrating the
+efforts of HTML developers with the Java developers responsible
for the running application.
</para>
@@ -484,8 +501,8 @@
</para>
<para>
-This snippet will get the <literal>hello</literal> message from the page's catalog of
-messages and insert it into the response. The text inside the &span;
+This snippet will get the <literal>hello</literal> message from the page's message catalog
+and insert it into the response. The text inside the &span;
tag is useful for WYSIWYG preview, but will be discarded at runtime in favor of a message string
from the catalog, such as "Hello", "Hola" or "Bonjour" (depending on the selected locale).
</para>
@@ -526,8 +543,8 @@
</programlisting>
</informalexample>
-(In this example, the placeholder text "Invalid Access" was replaced with a much
-longer message acquired from the message catalog.)
+In this example, the placeholder text "Invalid Access" was replaced with a much
+longer message acquired from the message catalog.
</para>
@@ -600,7 +617,7 @@
</para>
<para>
-Tapestry allows a special &jwcid;, <literal>$remove$</literal> for this case. A tag so marked is
+Tapestry allows a special &jwcid;, <literal>$remove$</literal>, for this case. A tag so marked is
not a component, but is instead eliminated from the
template. It is used, as in this case, to mark sections of the template that are just there for WYSIWYG preview.
</para>
@@ -639,7 +656,8 @@
</example>
<para>
-With the <literal>$remove$</literal> blocks in place, the output is as expected, one row for row in the database,
+With the <literal>$remove$</literal> blocks in place, the output is as expected, one row for each
+row read from the database,
and "Frank Smith" and "Jane Jones" nowhere to be seen.
</para>
@@ -659,15 +677,15 @@
<title><literal>$content$ jwcid</literal></title>
<para>
-In Tapestry, components can have their own templates. Because of how components integrate thier own templates
-with their bodies (the portion from their container's template), you can do a lot of iteresting things. It is very
+In Tapestry, components can have their own templates. Because of how components integrate their own templates
+with their bodies (the portion from their container's template), you can do a lot ofn iteresting things. It is very
common for a Tapestry application to have a Border component: a component that produces the &html;,
&head;, and &body; tags (along with additional tags
to reference stylesheets), plus some form of navigational control (typically, a nested table and a collection of links and images).
</para>
<para>
-Once again, maintaining previewability is a problem. Consider the following:
+Once again, maintaining the ability to use WYSIWYG preview is a problem. Consider the following:
<informalexample>
<programlisting><![CDATA[
<html>
@@ -692,7 +710,15 @@
</para>
<para>
-The template includes the
+It is quite common for Tapestry applications to have a <emphasis>Border</emphasis>
+component, a component that is used by pages to provide the
+&html;, &head;, and
+&body; tags, plus common navigational features (menus,
+copyrights, and so forth). In this example, it is presumed that the <literal>border</literal>
+component is a reference to just such as component.
+</para>
+
+<para>
When this page renders, the page template will provide the &html;, &head; and &body; tags.
Then when the <literal>border</literal> component renders, it will <emphasis>again</emphasis>
render those tags (possibly with different attributes, and mixed in to much other stuff).
1.2 +327 -129 jakarta-tapestry/doc/src/UsersGuide/UsersGuideFigures.vsd
<<Binary file>>
1.10 +16 -2 jakarta-tapestry/doc/src/UsersGuide/spec.xml
Index: spec.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/spec.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- spec.xml 28 Jan 2004 19:23:18 -0000 1.9
+++ spec.xml 2 Mar 2004 22:35:34 -0000 1.10
@@ -1,5 +1,19 @@
<!-- $Id$ -->
-
+<!--
+ Copyright 2004 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.
+-->
<appendix id="spec">
<title>Tapestry Specification DTDs</title>
1.14 +61 -10 jakarta-tapestry/doc/src/UsersGuide/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/configuration.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- configuration.xml 28 Jan 2004 19:23:18 -0000 1.13
+++ configuration.xml 2 Mar 2004 22:35:34 -0000 1.14
@@ -1,5 +1,19 @@
<!-- $Id$ -->
-
+<!--
+ Copyright 2004 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.
+-->
<chapter id="configuration">
<title>Configuring Tapestry</title>
@@ -89,11 +103,11 @@
<example>
- <title>Virtual Library Deployment Descriptor</title>
+ <title>Web Deployment Descriptor</title>
<programlisting>
<?xml version="1.0"?>
-<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
- "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
+<!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>
<distributable/> <co id="configuration.web.distributable"/>
<display-name>My Application</display-name>
@@ -103,13 +117,21 @@
<load-on-startup>0</load-on-startup> <co id="configuration.load-on-startup"/>
</servlet>
- <!-- The single mapping used for the Virtual Library application -->
-
<servlet-mapping>
<servlet-name>myapp</servlet-name>
<url-pattern>/app</url-pattern> <co id="configuration.web.url"/>
</servlet-mapping>
+ <filter> <co id="configuration.web.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>
+
<session-config>
<session-timeout>15</session-timeout>
</session-config>
@@ -174,6 +196,14 @@
you select.
</para>
</callout>
+<callout arearefs="configuration.web.filter">
+<para>
+This 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 <literal>http://myserver/mycontext/</literal> when, in fact,
+the real address is <literal>http://myserver/mycontext/app</literal>.
+</para>
+</callout>
</calloutlist>
<para>
@@ -216,7 +246,9 @@
<para>
If the application specification still can not be found, then an empty, "stand in"
-application specification is used.
+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.
</para>
@@ -438,7 +470,7 @@
<para>
This slows down request handling by a noticable amount, but is very
- useful in devlopment; it means that changes to templates and specifications
+ 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.
</para>
@@ -513,7 +545,26 @@
</para>
<para>
- Each application extension must implement an interface particular
+ 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.
+ </para>
+
+ <para>
+ You may access application extensions via the engine's specification property. For example:
+
+ <informalexample><programlisting>
+&IEngine; engine = getEngine();
+&IApplicationSpecification; specification = engine.getSpecification();
+
+myExtension myExtension = (MyExtension) specification.getExtension("myExtension");
+ </programlisting>
+ </informalexample>
+ </para>
+
+
+ <para>
+ Each application extension used with an framework extension point must implement an interface particular
to the extension point.
</para>
1.11 +21 -2 jakarta-tapestry/doc/src/UsersGuide/TapestryUsersGuide.xml
Index: TapestryUsersGuide.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/TapestryUsersGuide.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- TapestryUsersGuide.xml 28 Jan 2004 19:23:18 -0000 1.10
+++ TapestryUsersGuide.xml 2 Mar 2004 22:35:34 -0000 1.11
@@ -1,5 +1,20 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Id$ -->
+<!--
+ Copyright 2004 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.
+-->
<!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [
@@ -13,10 +28,12 @@
<!ENTITY chap-components SYSTEM "components.xml">
<!ENTITY chap-state SYSTEM "state.xml">
<!ENTITY chap-configuration SYSTEM "configuration.xml">
-
+
+<!ENTITY appendix-jars SYSTEM "jars.xml">
<!ENTITY appendix-spec SYSTEM "spec.xml">
<!ENTITY appendix-script-spec SYSTEM "script-spec.xml">
+
<!-- Configuration entities -->
<!ENTITY configuration.character-sets '<link linkend="configuration.character-sets">Character Sets</link>'>
@@ -114,6 +131,8 @@
&chap-state;
&chap-configuration;
+
+ &appendix-jars;
&appendix-spec;
1.3 +16 -1 jakarta-tapestry/doc/src/UsersGuide/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/build.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- build.xml 17 Jan 2003 17:38:44 -0000 1.2
+++ build.xml 2 Mar 2004 22:35:34 -0000 1.3
@@ -1,5 +1,20 @@
<?xml version="1.0"?>
-
+<!-- $Id$ -->
+<!--
+ Copyright 2004 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.
+-->
<!DOCTYPE project [
<!ENTITY docbook-setup SYSTEM "file:../common/docbook-setup.xml">
]>
1.1 jakarta-tapestry/doc/src/UsersGuide/jars.xml
Index: jars.xml
===================================================================
<!-- $Id: jars.xml,v 1.1 2004/03/02 22:35:34 hlship Exp $ -->
<!--
Copyright 2004 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.
-->
<appendix id="jars">
<title>Tapestry JAR files</title>
<para>
The Tapestry distribution includes the Tapestry JARs, plus all the dependencies (other libraries that
Tapestry makes use of). The JAR files are in the <filename>lib</filename> folder (or in folders beneath it).
</para>
<variablelist>
<varlistentry>
<term>&TapestryFrameworkJar;</term>
<listitem>
<para>
The main Tapestry framework. This is needed at compile time and runtime. The framework release number is
integrated into the file name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&TapestryContribJar;</term>
<listitem>
<para>
Contains additional components and tools that are not integral to the framework itself, such
as the &Palette;. Needed at runtime if any such components are used in an application.
The framework release number is integrated into the file name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>runtime/<replaceable>*</replaceable>.jar</filename></term>
<listitem>
<para>
Frameworks that are usually needed at runtime (but not at framework build time) and
are not always supplied by the servlet container. This currently
is just the &Log4J; framework.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>ext/<replaceable>*</replaceable>.jar</filename></term>
<listitem>
<para>
Frameworks needed when compiling the framework and at runtime. This is
several other &Jakarta; frameworks (including &BSF; and &BCEL;), plus
the &OGNL; and &Javassist; frameworks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>j2ee/*.jar</filename></term>
<listitem>
<para>
Contains the J2EE and Servlet APIs. These are needed when building the framework, but
are typically provided at runtime by the servlet container or application server.
</para>
</listitem>
</varlistentry>
</variablelist>
</appendix>
1.1 jakarta-tapestry/doc/src/UsersGuide/images/parameter-bindings.png
<<Binary file>>
1.1 jakarta-tapestry/doc/src/UsersGuide/images/write-binding.png
<<Binary file>>
1.1 jakarta-tapestry/doc/src/UsersGuide/images/parameter-manager.png
<<Binary file>>
1.1 jakarta-tapestry/doc/src/UsersGuide/images/core-classes.png
<<Binary file>>
1.1 jakarta-tapestry/doc/src/UsersGuide/images/read-binding.png
<<Binary file>>
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tapestry-dev-help@jakarta.apache.org