tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jkuhn...@apache.org
Subject svn commit: r420925 [3/9] - /tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/
Date Tue, 11 Jul 2006 16:54:18 GMT
Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/friendly-urls.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/friendly-urls.xml?rev=420925&r1=420924&r2=420925&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/friendly-urls.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/friendly-urls.xml Tue Jul 11 09:54:16 2006
@@ -1,223 +1,300 @@
 <?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.
+    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>Configuring Friendly URLs</title>
-</properties>
-<body>
-    
-    <p>
-    Earlier versions of Tapestry have had a long-standing tradition of
-    <em>really ugly URLs</em>. Because the framework generates the URLs and
-    is also responsible for parsing and dispatching on them in later requests, it was
-    not seen as an issue.
-    </p>
-    
-    <p>
-    In fact, the ugly URLs <em>do</em> cause some problems:
-    </p>
-    
-    <ul>
-      <li>Since all requests are routed through a single  servlet
-        (typically mapped to <code>/app</code>), J2EE declarative security, which is path-based,
-        is defeated.</li>
-      <li>
-        Ugly URLs tend to be longer than friendly URLs, which can make a difference when creating
-        a WML application.
-      </li>
-     <li>A single directory may contain all the artifacts (HTML templates,  specifications, properties files) for
-      all the pages in an entire application.  There isn't a sanctioned approach to organizing
-      things into subdirectories.</li>
-      <li>The reliance on query parameters means that common search engines will only see
-        a tiny fraction of the application.</li>
-    </ul>
-    
-    <p>
-    Starting with 4.0, <em>friendly URLs</em> are integrated directly into framework (in 3.0 an
-    ambitious, but more limited, patch was required). 
-    </p>
-    
-    <p>
-<strong>Warning:</strong>
-<br/>
-      For security purposes, enabling friendly URLs implies that pages are no longer
-      accessible via their ugly URL counterpart. This is not the case. If a malevolent user
-      can either guess - or via cookies identify - your servlet path, they can construct an
-      ugly URL to a resource that is protected via security and gain access to the protected
-      resource.
-    </p>
-    <p>
-    Friendly URLs are divided into two concerns:
-    </p>
-    
-    <ul>
-      <li>Converting information normally stored as a query parameter into part of the URL path.</li>
-      <li>Parsing the path to restore the information previously encoded.</li>
-    </ul>
-    
-    <p>
-      For example, the ugly URL <code>/app?page=news/Thread&amp;service=page</code> may be converted into
-      the friendly URL <code>/news/Threads.html</code>.  In this case, the <code>page=news/Thread</code> query parameter
-      became the <code>news/Thread</code> portion of the URL, and the <code>service=page</code> query parameter
-      became the <code>.html</code> extension to the URL.
-    </p>
-    
-  <section name="Understanding Tapestry URLs">
-    
-    
-    <p>
-      To understand how to get friendly URLs, you must understand a little about what 
-      information Tapestry packs into URLs.
-    </p>
-    
-    <p>
-    Every request to a Tapestry application is mapped to an <em>engine service</em>. An engine service
-    is something like a servlet, embedded within Tapestry. The <code>service</code> query parameter
-    is used to select an engine service by name.  A number of services are provided with the framework, the most common
-    of which are:
-    </p>
-    
-    <dl>
-      <dt>page</dt>
-      <dd>Activates and renders a specific page.</dd>
-      <dt>direct</dt>
-      <dd>Used with the <a href="site:DirectLink">DirectLink</a> and <a href="site:Form">Form</a> components.</dd>
-      <dt>home</dt>
-      <dd>Default service used when the service parameter is not specified (such as when
-        first accessing the application); activates and renders the Home page.</dd>
-    </dl>
-    
-    <p>
-      Each service is responsible for creating URLs with the correct query parameters.
-      By default, the URL path is always <code>/app</code> and any additional information comes out
-      of the query parameters.  The most common parameters are:
-    </p>
-    
-    <dl>
-      <dt>page</dt>
-      <dd>The name of a page to activate.</dd>
-      <dt>service</dt>
-      <dd>The service responsible for the request.</dd>
-      <dt>component</dt>
-      <dd>The nested component id of a component.</dd>
-      <dt>sp
-        
-      </dt>
-      <dd>
-        Stores listener parameters passed in the URL (used by <a href="site:DirectLink">DirectLink</a> and passed into <a href="listenermethods.html">listener method</a>s, the "sp" is a holdover from 3.0).
-      </dd>
-    </dl>
-    
-    <p>
-      Following this scheme, a typical URL might be
-      <code>/app?component=border.logout&amp;page=news/Thread&amp;service=direct</code>.  Yep, that's UGLY.
-    </p>
-    
-  </section>
-  
-  <section name="Enabling Friendly URLs">
-    
-    
-    <p>
-      To use ordinary ugly URLs, Tapestry requires only a 
-      <a href="configuration.html#configuration.deployment-descriptor">small amount of configuration
-        in web.xml</a>.  Enabling friendly URLs requires adding more
-        configuration to web.xml, and to your <a href="site:hivemind">HiveMind module deployment descriptor</a>.
-    </p>
-    
-    <p>
-      Friendly URLs are controlled by
-      <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoder.html">ServiceEncoder</a>s. Getting Tapestry to output friendly URLs is a matter of
-      plugging encoders into the correct pipeline ... this is all done using HiveMind.
-    </p>
-    
-    <subsection name="page-service-encoder">
-      
-      
-      <p>
-        The most common type of encoder is the <code>page-service-encoder</code>, which encodes
-        the <code>page</code> and <code>service</code> parameters.  In your hivemodule.xml:
-      </p>
-      
-      <source xml:space="preserve">
+    <properties>
+        <title>Configuring Friendly URLs</title>
+    </properties>
+    <body>
+
+        <section name="Configuring Friendly URLs">
+            <p>
+                Earlier versions of Tapestry have had a long-standing tradition of
+                <em>really ugly URLs</em>
+                . Because the framework generates the URLs and is also responsible for parsing and
+                dispatching on them in later requests, it was not seen as an issue.
+            </p>
+
+            <p>
+                In fact, the ugly URLs
+                <em>do</em>
+                cause some problems:
+            </p>
+
+            <ul>
+                <li>
+                    Since all requests are routed through a single servlet (typically mapped to
+                    <code>/app</code>
+                    ), J2EE declarative security, which is path-based, is defeated.
+                </li>
+                <li>
+                    Ugly URLs tend to be longer than friendly URLs, which can make a difference when
+                    creating a WML application.
+                </li>
+                <li>
+                    A single directory may contain all the artifacts (HTML templates,
+                    specifications, properties files) for all the pages in an entire application.
+                    There isn't a sanctioned approach to organizing things into subdirectories.
+                </li>
+                <li>
+                    The reliance on query parameters means that common search engines will only see
+                    a tiny fraction of the application.
+                </li>
+            </ul>
+
+            <p>
+                Starting with 4.0,
+                <em>friendly URLs</em>
+                are integrated directly into framework (in 3.0 an ambitious, but more limited, patch
+                was required).
+            </p>
+
+            <p>
+                <strong>Warning:</strong>
+                <br />
+                For security purposes, enabling friendly URLs implies that pages are no longer
+                accessible via their ugly URL counterpart. This is not the case. If a malevolent
+                user can either guess - or via cookies identify - your servlet path, they can
+                construct an ugly URL to a resource that is protected via security and gain access
+                to the protected resource.
+            </p>
+            <p>Friendly URLs are divided into two concerns:</p>
+
+            <ul>
+                <li>
+                    Converting information normally stored as a query parameter into part of the URL
+                    path.
+                </li>
+                <li>Parsing the path to restore the information previously encoded.</li>
+            </ul>
+
+            <p>
+                For example, the ugly URL
+                <code>/app?page=news/Thread&amp;service=page</code>
+                may be converted into the friendly URL
+                <code>/news/Threads.html</code>
+                . In this case, the
+                <code>page=news/Thread</code>
+                query parameter became the
+                <code>news/Thread</code>
+                portion of the URL, and the
+                <code>service=page</code>
+                query parameter became the
+                <code>.html</code>
+                extension to the URL.
+            </p>
+
+            <section name="Understanding Tapestry URLs">
+
+
+                <p>
+                    To understand how to get friendly URLs, you must understand a little about what
+                    information Tapestry packs into URLs.
+                </p>
+
+                <p>
+                    Every request to a Tapestry application is mapped to an
+                    <em>engine service</em>
+                    . An engine service is something like a servlet, embedded within Tapestry. The
+                    <code>service</code>
+                    query parameter is used to select an engine service by name. A number of
+                    services are provided with the framework, the most common of which are:
+                </p>
+
+                <dl>
+                    <dt>page</dt>
+                    <dd>Activates and renders a specific page.</dd>
+                    <dt>direct</dt>
+                    <dd>
+                        Used with the
+                        <a href="site:DirectLink">DirectLink</a>
+                        and
+                        <a href="site:Form">Form</a>
+                        components.
+                    </dd>
+                    <dt>home</dt>
+                    <dd>
+                        Default service used when the service parameter is not specified (such as
+                        when first accessing the application); activates and renders the Home page.
+                    </dd>
+                </dl>
+
+                <p>
+                    Each service is responsible for creating URLs with the correct query parameters.
+                    By default, the URL path is always
+                    <code>/app</code>
+                    and any additional information comes out of the query parameters. The most
+                    common parameters are:
+                </p>
+
+                <dl>
+                    <dt>page</dt>
+                    <dd>The name of a page to activate.</dd>
+                    <dt>service</dt>
+                    <dd>The service responsible for the request.</dd>
+                    <dt>component</dt>
+                    <dd>The nested component id of a component.</dd>
+                    <dt>
+                        sp
+
+                    </dt>
+                    <dd>
+                        Stores listener parameters passed in the URL (used by
+                        <a href="site:DirectLink">DirectLink</a>
+                        and passed into
+                        <a href="listenermethods.html">listener method</a>
+                        s, the "sp" is a holdover from 3.0).
+                    </dd>
+                </dl>
+
+                <p>
+                    Following this scheme, a typical URL might be
+                    <code>
+                        /app?component=border.logout&amp;page=news/Thread&amp;service=direct
+                    </code>
+                    . Yep, that's UGLY.
+                </p>
+
+            </section>
+
+            <section name="Enabling Friendly URLs">
+
+
+                <p>
+                    To use ordinary ugly URLs, Tapestry requires only a
+                    <a href="configuration.html#configuration.deployment-descriptor">
+                        small amount of configuration in web.xml
+                    </a>
+                    . Enabling friendly URLs requires adding more configuration to web.xml, and to
+                    your
+                    <a href="site:hivemind">HiveMind module deployment descriptor</a>
+                    .
+                </p>
+
+                <p>
+                    Friendly URLs are controlled by
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoder.html">
+                        ServiceEncoder
+                    </a>
+                    s. Getting Tapestry to output friendly URLs is a matter of plugging encoders
+                    into the correct pipeline ... this is all done using HiveMind.
+                </p>
+
+                <subsection name="page-service-encoder">
+
+
+                    <p>
+                        The most common type of encoder is the
+                        <code>page-service-encoder</code>
+                        , which encodes the
+                        <code>page</code>
+                        and
+                        <code>service</code>
+                        parameters. In your hivemodule.xml:
+                    </p>
+
+                    <source xml:space="preserve">
 &lt;contribution configuration-id="tapestry.url.ServiceEncoders"&gt;
   &lt;page-service-encoder id="page" extension="html" service="page"/&gt;
 &lt;/contribution&gt;</source>
-      
-      <p>
-        This contribution to the <a href="../tapestry/hivedocs/config/tapestry.url.ServiceEncoders.html">tapestry.url.ServiceEncoders</a> configuration point
-        creates a <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoder.html">ServiceEncoder</a> that maps the <code>.html</code> extension (on the URL path)
-        to the page service. The <code>id</code> attribute must be unique for all
-        contributed encoders.
-      </p>
-      
-      <p>
-        For Tapestry to recognize the URLs, you must inform the servlet container
-        to send them to the Tapestry application servlet, by adding a mapping
-        to web.xml:
-      </p>
-      <source xml:space="preserve">
+
+                    <p>
+                        This contribution to the
+                        <a href="../tapestry/hivedocs/config/tapestry.url.ServiceEncoders.html">
+                            tapestry.url.ServiceEncoders
+                        </a>
+                        configuration point creates a
+                        <a
+                            href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoder.html">
+                            ServiceEncoder
+                        </a>
+                        that maps the
+                        <code>.html</code>
+                        extension (on the URL path) to the page service. The
+                        <code>id</code>
+                        attribute must be unique for all contributed encoders.
+                    </p>
+
+                    <p>
+                        For Tapestry to recognize the URLs, you must inform the servlet container to
+                        send them to the Tapestry application servlet, by adding a mapping to
+                        web.xml:
+                    </p>
+                    <source xml:space="preserve">
 &lt;servlet-mapping&gt;
   &lt;servlet-name&gt;myapp&lt;/servlet-name&gt;
   &lt;url-pattern&gt;*.html&lt;/url-pattern&gt;
-&lt;/servlet-mapping&gt;</source>  
-      
+&lt;/servlet-mapping&gt;</source>
 
-<p>
-<strong>Note:</strong>
-<br/>
-  This means that even static HTML pages that are part of your web application will be
-  treated as Tapestry pages; any incoming request that ends with .html will be routed
-  into the Tapestry application. Page specifications are optional, so Tapestry will treat
-  the HTML pages are if they were HTML page templates.  If you want to allow ordinary static
-  content, then you should use another extension such as ".page" or ".tap" (the choice
-  is arbitrary).
-</p>      
-      
-    </subsection>
-    
-    <subsection name="direct-service-encoder">
-      
-      
-      <p>A specialized encoder used <em>exclusively</em>
-        with the direct service. Encodes the page name into the 
-        servlet path, then a comma, then the nested id for the component.  One of two extensions
-        is used, depending on whether the URL is stateful (an HttpSession existed when the link was rendered), or
-        stateless.</p>
-        
-        <p>
-          A typical URL might be:
-          <code>/admin/Menu,border.link.direct</code>.  This indicates a page name of <code>admin/Menu</code> and
-          a component id of <code>border.link</code>.  By convention, the ".direct" extension is for stateless URLs.
-        </p>
-        
-        <p>The hivemodule.xml contribution:</p>
-        
-<source xml:space="preserve">
+
+                    <span class="info">
+                        <strong>Note:</strong>
+                        <p>
+                            This means that even static HTML pages that are part of your web
+                            application will be treated as Tapestry pages; any incoming request that
+                            ends with .html will be routed into the Tapestry application. Page
+                            specifications are optional, so Tapestry will treat the HTML pages are
+                            if they were HTML page templates. If you want to allow ordinary static
+                            content, then you should use another extension such as ".page" or ".tap"
+                            (the choice is arbitrary).
+                        </p>
+                    </span>
+
+                </subsection>
+
+                <subsection name="direct-service-encoder">
+
+
+                    <p>
+                        A specialized encoder used
+                        <em>exclusively</em>
+                        with the direct service. Encodes the page name into the servlet path, then a
+                        comma, then the nested id for the component. One of two extensions is used,
+                        depending on whether the URL is stateful (an HttpSession existed when the
+                        link was rendered), or stateless.
+                    </p>
+
+                    <p>
+                        A typical URL might be:
+                        <code>/admin/Menu,border.link.direct</code>
+                        . This indicates a page name of
+                        <code>admin/Menu</code>
+                        and a component id of
+                        <code>border.link</code>
+                        . By convention, the ".direct" extension is for stateless URLs.
+                    </p>
+
+                    <p>The hivemodule.xml contribution:</p>
+
+                    <source xml:space="preserve">
 &lt;contribution configuration-id="tapestry.url.ServiceEncoders"&gt;
   &lt;direct-service-encoder id="direct" stateless-extension="direct" stateful-extension="sdirect"/&gt;
 &lt;/contribution&gt;
-</source>        
+</source>
 
-<p>
-  In  addition, the <code>*.direct</code> and <code>*.sdirect</code> mappings must be added to web.xml:
-</p>
+                    <p>
+                        In addition, the
+                        <code>*.direct</code>
+                        and
+                        <code>*.sdirect</code>
+                        mappings must be added to web.xml:
+                    </p>
 
-<source xml:space="preserve">
+                    <source xml:space="preserve">
 &lt;servlet-mapping&gt;
   &lt;servlet-name&gt;myapp&lt;/servlet-name&gt;
   &lt;url-pattern&gt;*.direct&lt;/url-pattern&gt;
@@ -228,132 +305,161 @@
   &lt;url-pattern&gt;*.sdirect&lt;/url-pattern&gt;
 &lt;/servlet-mapping&gt;  </source>
 
-    </subsection>
-    
-    <subsection name="asset-encoder">
-      
-      
-      <p>
-        The <code>asset-encoder</code> is for use with the asset service.  The asset service exposes assets stored
-        on the classpath (i.e., inside JARs) to the client web browser. The asset service receives a request with a
-        resource path, and writes back a binary stream of that resources content.
-      </p>
-      
-      <p>
-        In addition, each request includes a <em>message digest</em>, a string generated from the bytes of the
-        the resource.  This message digest acts as a <em>credential</em>, assuring that only classpath resources
-        explicitly exposed by the application are accessible by the client (this prevents devious users from
-        obtaining Java class files, for example). The message digest can only be computed by the server, using the full
-        content of the actual file.
-      </p>
-      
-      <p>
-        To enable friendly URLs for the asset service, add the following to your hivemodule.xml:
-      </p>
-      
-      <source xml:space="preserve">
+                </subsection>
+
+                <subsection name="asset-encoder">
+
+
+                    <p>
+                        The
+                        <code>asset-encoder</code>
+                        is for use with the asset service. The asset service exposes assets stored
+                        on the classpath (i.e., inside JARs) to the client web browser. The asset
+                        service receives a request with a resource path, and writes back a binary
+                        stream of that resources content.
+                    </p>
+
+                    <p>
+                        In addition, each request includes a
+                        <em>message digest</em>
+                        , a string generated from the bytes of the the resource. This message digest
+                        acts as a
+                        <em>credential</em>
+                        , assuring that only classpath resources explicitly exposed by the
+                        application are accessible by the client (this prevents devious users from
+                        obtaining Java class files, for example). The message digest can only be
+                        computed by the server, using the full content of the actual file.
+                    </p>
+
+                    <p>
+                        To enable friendly URLs for the asset service, add the following to your
+                        hivemodule.xml:
+                    </p>
+
+                    <source xml:space="preserve">
 &lt;contribution configuration-id="tapestry.url.ServiceEncoders"&gt;
   &lt;asset-encoder id="asset" path="/assets"/&gt;
 &lt;/contribution&gt;</source>
-      
-      <p>
-        This contribution will encode asset URLs using the given path.  The provided path, <code>/assets</code> comes first,
-        then the digest string, then the path for the URL.  An example URI would be <code>/assets/91ab6d51232df0384663312f405babbe/org/apache/tapestry/contrib/palette/select_right.gif</code>.
-      </p>
-      
-      <p>
-        In addition you must add a mapping to web.xml:
-      </p>
-      
-<source xml:space="preserve">
+
+                    <p>
+                        This contribution will encode asset URLs using the given path. The provided
+                        path,
+                        <code>/assets</code>
+                        comes first, then the digest string, then the path for the URL. An example
+                        URI would be
+                        <code>
+                            /assets/91ab6d51232df0384663312f405babbe/org/apache/tapestry/contrib/palette/select_right.gif
+                        </code>
+                        .
+                    </p>
+
+                    <p>In addition you must add a mapping to web.xml:</p>
+
+                    <source xml:space="preserve">
 &lt;servlet-mapping&gt;
   &lt;servlet-name&gt;myapp&lt;/servlet-name&gt;
   &lt;url-pattern&gt;/assets/*&lt;/url-pattern&gt;
-&lt;/servlet-mapping&gt;</source>      
-      
-      
-      <p>
-        If you choose a different folder than <code>/assets/</code> then be sure to make corresponding changes
-        in both hivemodule.xml and web.xml.
-      </p>
-      
-    </subsection>
-    
-    <subsection name="extension-encoder">
-      
-      
-      <p>
-        The <code>extension-encoder</code> 
-        is used to encode just the <code>service</code> query parameter. The output URL is the service name
-        with a fixed extension (typically, ".svc"), i.e., <code>/home.svc</code> or <code>/restart.svc</code>.
-      </p>
-      
-      <p>In your hivemodule.xml:</p>
-  
-      <source xml:space="preserve">
+&lt;/servlet-mapping&gt;</source>
+
+
+                    <p>
+                        If you choose a different folder than
+                        <code>/assets/</code>
+                        then be sure to make corresponding changes in both hivemodule.xml and
+                        web.xml.
+                    </p>
+
+                </subsection>
+
+                <subsection name="extension-encoder">
+
+
+                    <p>
+                        The
+                        <code>extension-encoder</code>
+                        is used to encode just the
+                        <code>service</code>
+                        query parameter. The output URL is the service name with a fixed extension
+                        (typically, ".svc"), i.e.,
+                        <code>/home.svc</code>
+                        or
+                        <code>/restart.svc</code>
+                        .
+                    </p>
+
+                    <p>In your hivemodule.xml:</p>
+
+                    <source xml:space="preserve">
 &lt;contribution configuration-id="tapestry.url.ServiceEncoders"&gt;
   &lt;extension-encoder id="extension" extension="svc" after="*"/&gt;
-&lt;/contribution&gt;</source>        
-   
-      
-      <p>
-        The use of the <code>after</code> attribute ensures that this encoder is always executed after
-        any other encoders. Order is important!
-      </p>
-      
-      <p>
-        For this example, another mapping is required in the web.xml:
-      </p>
-      
-      <source xml:space="preserve">
+&lt;/contribution&gt;</source>
+
+
+                    <p>
+                        The use of the
+                        <code>after</code>
+                        attribute ensures that this encoder is always executed after any other
+                        encoders. Order is important!
+                    </p>
+
+                    <p>For this example, another mapping is required in the web.xml:</p>
+
+                    <source xml:space="preserve">
 &lt;servlet-mapping&gt;
   &lt;servlet-name&gt;myapp&lt;/servlet-name&gt;
   &lt;url-pattern&gt;*.svc&lt;/url-pattern&gt;
-&lt;/servlet-mapping&gt;</source>      
-    </subsection>
+&lt;/servlet-mapping&gt;</source>
+                </subsection>
 
-<subsection name="encoder">
-  
+                <subsection name="encoder">
 
-  <p>
-    Finally, when one of the pre-defined encoders is insufficient, you can define your own.
-    The &lt;encoder&gt; element allows an arbitrary object that implements the <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoder.html">ServiceEncoder</a>
-    interface to be plugged into the pipeline.  The &lt;encoder&gt; element 
-    supports the (required) id attribute, and the optional before and
-    after attributes.
-  </p>    
-  
-  <p>
-    From the Virtual Library example, a custom encoder implementation is used as a 
-    special way to reference
-    the ViewBook and ViewPerson pages using the external service (see the <a href="site:ExternalLink">ExternalLink</a> component for more
-    information about using this engine service).  The end result is
-    that the URLs for these two pages look like
-    <code>/vlib/book/2096</code> rather than <code>/vlib/ViewBook.external?sp=2096</code> or
-    <code>/vlib/app?page=ViewBook&amp;service=external&amp;sp=2096</code>.  Certainly the
-    first option is by far the prettiest.
-  </p>
-    
-  <p>
-    These encoders are configured in hivemodule.xml as follows:
-  </p>
-  
-  <source xml:space="preserve">
+
+                    <p>
+                        Finally, when one of the pre-defined encoders is insufficient, you can
+                        define your own. The &lt;encoder&gt; element allows an arbitrary object that
+                        implements the
+                        <a
+                            href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoder.html">
+                            ServiceEncoder
+                        </a>
+                        interface to be plugged into the pipeline. The &lt;encoder&gt; element
+                        supports the (required) id attribute, and the optional before and after
+                        attributes.
+                    </p>
+
+                    <p>
+                        From the Virtual Library example, a custom encoder implementation is used as
+                        a special way to reference the ViewBook and ViewPerson pages using the
+                        external service (see the
+                        <a href="site:ExternalLink">ExternalLink</a>
+                        component for more information about using this engine service). The end
+                        result is that the URLs for these two pages look like
+                        <code>/vlib/book/2096</code>
+                        rather than
+                        <code>/vlib/ViewBook.external?sp=2096</code>
+                        or
+                        <code>/vlib/app?page=ViewBook&amp;service=external&amp;sp=2096</code>
+                        . Certainly the first option is by far the prettiest.
+                    </p>
+
+                    <p>These encoders are configured in hivemodule.xml as follows:</p>
+
+                    <source xml:space="preserve">
 &lt;encoder id="viewbook" before="external" object="instance:ViewPageEncoder,pageName=ViewBook,url=/book"/&gt;
 &lt;encoder id="viewperson" before="external" object="instance:ViewPageEncoder,pageName=ViewPerson,url=/person"/&gt;
 &lt;page-service-encoder id="external" extension="external" service="external"/&gt;    
-</source>  
+</source>
 
-  <p>
-    The order of the encoders in the pipline is very important, so the use of the before attribute ensures that the specialized encoders for these two pages
-    are allowed to operate before the general purpose external service encoder.
-  </p>
-  
-  <p>
-    The two special pages are mapped in web.xml using their custom URLs:
-  </p>  
-    
-<source xml:space="preserve">  &lt;servlet-mapping&gt;
+                    <p>
+                        The order of the encoders in the pipline is very important, so the use of
+                        the before attribute ensures that the specialized encoders for these two
+                        pages are allowed to operate before the general purpose external service
+                        encoder.
+                    </p>
+
+                    <p>The two special pages are mapped in web.xml using their custom URLs:</p>
+
+                    <source xml:space="preserve">  &lt;servlet-mapping&gt;
     &lt;servlet-name&gt;vlib&lt;/servlet-name&gt;
     &lt;url-pattern&gt;/book/*&lt;/url-pattern&gt;
   &lt;/servlet-mapping&gt;
@@ -361,20 +467,25 @@
     &lt;servlet-name&gt;vlib&lt;/servlet-name&gt;
     &lt;url-pattern&gt;/person/*&lt;/url-pattern&gt;
   &lt;/servlet-mapping&gt;
-</source>    
-    
-  <p>
-    The implementation of the ViewPageEncoder class is all about an encode() method and a matching decode()
-    method.
-  </p>    
-  
-  <p>
-    The encode() method must check to see if the link being generated is the right page name
-    and the right service, returning (without doing anything) if not.  The link
-    being constructed is represented as an instance of <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoding.html">ServiceEncoding</a>:
-  </p>
-  
-  <source xml:space="preserve">
+</source>
+
+                    <p>
+                        The implementation of the ViewPageEncoder class is all about an encode()
+                        method and a matching decode() method.
+                    </p>
+
+                    <p>
+                        The encode() method must check to see if the link being generated is the
+                        right page name and the right service, returning (without doing anything) if
+                        not. The link being constructed is represented as an instance of
+                        <a
+                            href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ServiceEncoding.html">
+                            ServiceEncoding
+                        </a>
+                        :
+                    </p>
+
+                    <source xml:space="preserve">
   public void encode(ServiceEncoding encoding)
   {
     if (!isExternalService(encoding))
@@ -411,21 +522,21 @@
 
     return service.equals(Tapestry.EXTERNAL_SERVICE);
   }  </source>
-    
-  <p>
-    We cheat just a bit here because we know that the service parameters
-    will be a single numeric string.  You can see exactly how encoder works, by building
-    a new servlet path that encodes information that was stored as query parameters,
-    the setting those query parameters to null
-  </p>
-  
-  <p>
-    The flip side is the decode() method, which works by recognizing the URL
-    generated by the encode() method and restoring the query parameters by
-    parsing the URL:
-  </p>
-  
-  <source xml:space="preserve">  public void decode(ServiceEncoding encoding)
+
+                    <p>
+                        We cheat just a bit here because we know that the service parameters will be
+                        a single numeric string. You can see exactly how encoder works, by building
+                        a new servlet path that encodes information that was stored as query
+                        parameters, the setting those query parameters to null
+                    </p>
+
+                    <p>
+                        The flip side is the decode() method, which works by recognizing the URL
+                        generated by the encode() method and restoring the query parameters by
+                        parsing the URL:
+                    </p>
+
+                    <source xml:space="preserve">  public void decode(ServiceEncoding encoding)
   {
     String servletPath = encoding.getServletPath();
 
@@ -440,16 +551,17 @@
     encoding.setParameterValue(ServiceConstants.PAGE, _pageName);
     encoding.setParameterValues(ServiceConstants.PARAMETER, params);
   } </source>
-  
-  </subsection>
-  
-    <p>
-      When constructing this style of encoder, it is important to remember that
-      the servlet path does not end with a slash, but tthe path info, if non-null, will start
-      with a slash.
-    </p>
-  
-  </section>
-    
-  </body>
+
+                </subsection>
+
+                <p>
+                    When constructing this style of encoder, it is important to remember that the
+                    servlet path does not end with a slash, but tthe path info, if non-null, will
+                    start with a slash.
+                </p>
+
+            </section>
+
+        </section>
+    </body>
 </document>

Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/hivemind.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/hivemind.xml?rev=420925&r1=420924&r2=420925&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/hivemind.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/hivemind.xml Tue Jul 11 09:54:16 2006
@@ -1,116 +1,171 @@
 <?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.
+    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>HiveMind Integration</title>
-</properties>
-<body>
-    <p> Tapestry 4.0 is intimately integrated into the <a href="http://jakarta.apache.org/hivemind/">HiveMind</a> microkernel. Building a complex system onto a 
-      dependency injection microkernel such as HiveMind has many benefits; the code is easier to write, test and 
-      maintain. HiveMind's flexible approach makes it easy to provide extension points ... many of the common kinds of 
-      customizations in Tapestry 3.0 that required code changes (such as subclassing <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/BaseEngine.html">BaseEngine</a>) are now accomplished 
-      by providing objects via a HiveMind module descriptor for your application. </p>
-    <p> In fact, you should not think of HiveMind as just Tapestry's infrastructure, but as infrastructure for your 
-      application as well. A very succesful design pattern in Tapestry is to keep pages and components very simple, and 
-      <em>delegate</em> as much logic as possible out to HiveMind services. Listener methods should ideally do little 
-      more than marshall together the correct information and pass it over to a service (this sidesteps most of the 
-      issues with testing pages and components, which tend to be abstract). </p>
-      
-<p>
-<strong>Warning:</strong>
-<br/>
-  Tapestry 4.0 is <strong>not compatible with HiveMind 1.0</strong>. Tapestry 4.0 may only be used with
-  HiveMind 1.1. The compatibility issues are related to the underlying Javassist library; HiveMind 1.0 and Tapestry 3.0
-  use one version of the library, HiveMind 1.1 and Tapestry 4.0 use a more recent version.
-</p>     
- 
-    <section name="Injecting Services">
-      
-      <p> But how to get access to those services? Tapestry allows you to <em>inject</em> your pages and components 
-        with HiveMind services (or other objects accessible from within a HiveMind registry). This is accomplished via 
-        the <a href="spec.html#spec.inject">&lt;inject&gt;</a> specification element: </p>
-      <source xml:space="preserve">
+    <properties>
+        <title>HiveMind Integration</title>
+    </properties>
+    <body>
+
+        <section name="HiveMind Integration">
+            <p>
+                Tapestry 4.0 is intimately integrated into the
+                <a href="http://jakarta.apache.org/hivemind/">HiveMind</a>
+                microkernel. Building a complex system onto a dependency injection microkernel such
+                as HiveMind has many benefits; the code is easier to write, test and maintain.
+                HiveMind's flexible approach makes it easy to provide extension points ... many of
+                the common kinds of customizations in Tapestry 3.0 that required code changes (such
+                as subclassing
+                <a
+                    href="../tapestry-framework/apidocs/org/apache/tapestry/engine/BaseEngine.html">
+                    BaseEngine
+                </a>
+                ) are now accomplished by providing objects via a HiveMind module descriptor for
+                your application.
+            </p>
+            <p>
+                In fact, you should not think of HiveMind as just Tapestry's infrastructure, but as
+                infrastructure for your application as well. A very succesful design pattern in
+                Tapestry is to keep pages and components very simple, and
+                <em>delegate</em>
+                as much logic as possible out to HiveMind services. Listener methods should ideally
+                do little more than marshall together the correct information and pass it over to a
+                service (this sidesteps most of the issues with testing pages and components, which
+                tend to be abstract).
+            </p>
+
+            <span class="warn">
+                <strong>Warning:</strong>
+                <p>
+                    Tapestry 4.0 is
+                    <em>not compatible with HiveMind 1.0</em>
+                    . Tapestry 4.0 may only be used with HiveMind 1.1. The compatibility issues are
+                    related to the underlying Javassist library; HiveMind 1.0 and Tapestry 3.0 use
+                    one version of the library, HiveMind 1.1 and Tapestry 4.0 use a more recent
+                    version.
+                </p>
+            </span>
+
+            <subsection name="Injecting Services">
+
+                <p>
+                    But how to get access to those services? Tapestry allows you to
+                    <em>inject</em>
+                    your pages and components with HiveMind services (or other objects accessible
+                    from within a HiveMind registry). This is accomplished via the
+                    <a href="spec.html#spec.inject">&lt;inject&gt;</a>
+                    specification element:
+                </p>
+                <source xml:space="preserve">
 &lt;page-specification class=". . ."&gt;
 
   &lt;inject property="mailSender" object="service:mymodule.MailSender"/&gt;
   
 &lt;/page-specification&gt; </source>
-      <p> This would create a new property on your page, mailSender, that would be connected to a HiveMind service, 
-        mymodule.MailSender. The object attribute is an <em>object reference</em>, consisting of a prefix ("service:") 
-        followed by a <em>locator</em>. The prefix identifies how the locator should be interpreted; in this case, as a 
-        full qualified service id. HiveMind itself defines a <a href="http://jakarta.apache.org/hivemind/hivemind/ObjectProviders.html">base set of prefixes</a>, to which 
-        Tapestry adds the following: </p>
-      <table>
-        <tr>
-          <th>Prefix</th>
-          <th>Description</th>
-          <th>Example</th>
-        </tr>
-        <tr>
-          <td>app-property</td>
-          <td>The locator is the name of a property that is resolved using:
-            <ul>
-              <li>The application specification's <a href="spec.html#spec.meta">&lt;meta&gt;</a> properties</li>
-              <li>The servlet's &lt;init-parameter&gt; elements</li>
-              <li>The servlet context's &lt;init-parameter&gt; elements</li>
-              <li>The delegate property source (a <a href="spec.html#spec.extension">&lt;extension&gt;</a>)</li>
-              <li>A HiveMind symbol</li>
-            </ul>
-</td>
-            <td>
-              app-property:org.apache.tapestry.template-extension
-            </td>
-        </tr>
-        <tr>
-          <td>engine-service</td>
-          <td>The locator is the name of an engine service (an instance of <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/IEngineService.html">IEngineService</a>).</td>
-          <td>engine-service:page</td>
-        </tr>
-        <tr>
-          <td>global-property</td>
-          <td>The locator is the name of global property, defined as a servlet &lt;init-parameter&gt;,
-            a servlet context &lt;init-parameter&gt;,
-            or a HiveMind symbol. </td>
-            <td>global-property:org.apache.tapestry.disable-caching</td>
-        </tr>        
-        <tr>
-          <td>infrastructure</td>
-          <td> The locator is the name of a property provided by the tapestry.Infrastructure service; this service 
-            provides access to the key Tapestry services. </td>
-          <td>infrastructure:applicationSpecification</td>
-        </tr>
-
-      </table>
-      <p>
-<strong>Note:</strong>
-<br/> More prefixes are forthcoming. </p>
-      
-      <p>
-        You can access the service via the property.  You can do this from a <a href="spec.html#spec.binding">&lt;binding&gt;</a> element, or from within
-        the template, using an OGNL expression.  For example:  <code>ognl:mailSender.sendMail(to, subject)</code> would
-        read the to and subject properties of the page, and pass them to the sendMail() method of the mymodule.MailSender service (which has
-        been injected into the mailSender property).
-      </p>
-      
-      <p>
-        From within Java code, you can define an abstract accessor method:
-      </p>
-      
-      <source xml:space="preserve">
+                <p>
+                    This would create a new property on your page, mailSender, that would be
+                    connected to a HiveMind service, mymodule.MailSender. The object attribute is an
+                    <em>object reference</em>
+                    , consisting of a prefix ("service:") followed by a
+                    <em>locator</em>
+                    . The prefix identifies how the locator should be interpreted; in this case, as
+                    a full qualified service id. HiveMind itself defines a
+                    <a href="http://jakarta.apache.org/hivemind/hivemind/ObjectProviders.html">
+                        base set of prefixes
+                    </a>
+                    , to which Tapestry adds the following:
+                </p>
+                <table>
+                    <tr>
+                        <th>Prefix</th>
+                        <th>Description</th>
+                        <th>Example</th>
+                    </tr>
+                    <tr>
+                        <td>app-property</td>
+                        <td>
+                            The locator is the name of a property that is resolved using:
+                            <ul>
+                                <li>
+                                    The application specification's
+                                    <a href="spec.html#spec.meta">&lt;meta&gt;</a>
+                                    properties
+                                </li>
+                                <li>The servlet's &lt;init-parameter&gt; elements</li>
+                                <li>The servlet context's &lt;init-parameter&gt; elements</li>
+                                <li>
+                                    The delegate property source (a
+                                    <a href="spec.html#spec.extension">&lt;extension&gt;</a>
+                                    )
+                                </li>
+                                <li>A HiveMind symbol</li>
+                            </ul>
+                        </td>
+                        <td>app-property:org.apache.tapestry.template-extension</td>
+                    </tr>
+                    <tr>
+                        <td>engine-service</td>
+                        <td>
+                            The locator is the name of an engine service (an instance of
+                            <a
+                                href="../tapestry-framework/apidocs/org/apache/tapestry/engine/IEngineService.html">
+                                IEngineService
+                            </a>
+                            ).
+                        </td>
+                        <td>engine-service:page</td>
+                    </tr>
+                    <tr>
+                        <td>global-property</td>
+                        <td>
+                            The locator is the name of global property, defined as a servlet
+                            &lt;init-parameter&gt;, a servlet context &lt;init-parameter&gt;, or a
+                            HiveMind symbol.
+                        </td>
+                        <td>global-property:org.apache.tapestry.disable-caching</td>
+                    </tr>
+                    <tr>
+                        <td>infrastructure</td>
+                        <td>
+                            The locator is the name of a property provided by the
+                            tapestry.Infrastructure service; this service provides access to the key
+                            Tapestry services.
+                        </td>
+                        <td>infrastructure:applicationSpecification</td>
+                    </tr>
+
+                </table>
+                <span class="info">
+                    <strong>Note:</strong>
+                    <p>More prefixes are forthcoming.</p>
+                </span>
+
+                <p>
+                    You can access the service via the property. You can do this from a
+                    <a href="spec.html#spec.binding">&lt;binding&gt;</a>
+                    element, or from within the template, using an OGNL expression. For example:
+                    <code>ognl:mailSender.sendMail(to, subject)</code>
+                    would read the to and subject properties of the page, and pass them to the
+                    sendMail() method of the mymodule.MailSender service (which has been injected
+                    into the mailSender property).
+                </p>
+
+                <p>From within Java code, you can define an abstract accessor method:</p>
+
+                <source xml:space="preserve">
 public abstract class MyPage extends BasePage
 {
   public abstract MailSender getMailSender();
@@ -127,38 +182,70 @@
      . . .
   }
 }</source>
-      
-      
-    </section>
-    <!-- hivemind.inject -->
-     
-    <section name="Bootstrapping the Registry">
-      
-      <p> The <a href="../tapestry-framework/apidocs/org/apache/tapestry/ApplicationServlet.html">ApplicationServlet</a> is responsible for initializing HiveMind's Registry on startup. </p>
-      <p>
-<strong>Note:</strong>
-<br/> The ApplicationServlet takes over all the roles usually supplied by HiveMind's HiveMindFilter. This 
-        includes the initial creation of the HiveMind Registry (as discussed), but also includes cleaning up thread 
-        local information at the end of each request, and shutting down the Registry when the servlet is destroyed. 
-        </p>
-      <p> The ApplicationServlet will create a default registry, consisting of all META-INF/hivemodule.xml files found 
-        on the servlet classpath. This is how the base HiveMind and Tapestry module descriptors are loaded. You may 
-        package module deployment descriptors inside libraries or even in your application WAR. </p>
-      <p> In addition, two other descriptors will be parsed if they exist: </p>
-      <ul>
-        <li>/WEB-INF/<em>applicationId</em>/hivemodule.xml</li>
-        <li>/WEB-INF/hivemodule.xml</li>
-      </ul>
-      <p>
-<strong>Note:</strong>
-<br/>The descriptor will not be recognized if it is located in META-INF/ in the context root of a web application
-            however it will if it is under the WEB-INF/ locations. The META-INF/ location is specific to libraries.</p>
-      <p> Both of these files exist in the web application context; the <em>applicationId</em> is the name of the application 
-        servlet, as given in web.xml deployment descriptor (this is only useful in the very rare case that you package 
-        more than one Tapestry application in a single web application). </p>
-      <p> By subclassing ApplicationServlet and overriding the <code>constructRegistry()</code> method, you can easily 
-        extend these rules, loading additional descriptors from arbitrary locations. </p>
-    </section>
-    <!-- hivemind.bootstrap -->
-  </body>
+
+
+            </subsection>
+            <!-- hivemind.inject -->
+
+            <subsection name="Bootstrapping the Registry">
+
+                <p>
+                    The
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/ApplicationServlet.html">
+                        ApplicationServlet
+                    </a>
+                    is responsible for initializing HiveMind's Registry on startup.
+                </p>
+                <span class="info">
+                    <strong>Note:</strong>
+                    <p>
+                        The ApplicationServlet takes over all the roles usually supplied by
+                        HiveMind's HiveMindFilter. This includes the initial creation of the
+                        HiveMind Registry (as discussed), but also includes cleaning up thread local
+                        information at the end of each request, and shutting down the Registry when
+                        the servlet is destroyed.
+                    </p>
+                </span>
+                <p>
+                    The ApplicationServlet will create a default registry, consisting of all
+                    META-INF/hivemodule.xml files found on the servlet classpath. This is how the
+                    base HiveMind and Tapestry module descriptors are loaded. You may package module
+                    deployment descriptors inside libraries or even in your application WAR.
+                </p>
+                <p>In addition, two other descriptors will be parsed if they exist:</p>
+                <ul>
+                    <li>
+                        /WEB-INF/
+                        <em>applicationId</em>
+                        /hivemodule.xml
+                    </li>
+                    <li>/WEB-INF/hivemodule.xml</li>
+                </ul>
+                <span class="info">
+                    <strong>Note:</strong>
+                    <p>
+                        The descriptor will not be recognized if it is located in META-INF/ in the
+                        context root of a web application however it will if it is under the
+                        WEB-INF/ locations. The META-INF/ location is specific to libraries.
+                    </p>
+                </span>
+                <p>
+                    Both of these files exist in the web application context; the
+                    <em>applicationId</em>
+                    is the name of the application servlet, as given in web.xml deployment
+                    descriptor (this is only useful in the very rare case that you package more than
+                    one Tapestry application in a single web application).
+                </p>
+                <p>
+                    By subclassing ApplicationServlet and overriding the
+                    <code>constructRegistry()</code>
+                    method, you can easily extend these rules, loading additional descriptors from
+                    arbitrary locations.
+                </p>
+            </subsection>
+            <!-- hivemind.bootstrap -->
+
+        </section>
+    </body>
 </document>

Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/injection.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/injection.xml?rev=420925&r1=420924&r2=420925&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/injection.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/injection.xml Tue Jul 11 09:54:16 2006
@@ -1,143 +1,173 @@
 <?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.
+    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>Property Injection</title>
-</properties>
-<body>
-    
-<p>
-Tapestry 4.0 introduces an entirely new concept into Tapestry application development: property injection.
-By use of the <a href="spec.html#spec.inject">&lt;inject&gt;</a> element in page and component specifications, it is possible
-to add new properties to pages or components, using the <a href="spec.html#spec.inject">&lt;inject&gt;</a> element in the page
-or component specification.
-</p>    
-
-<p>
-The new properties that are created often are more than just wrappers around an instance variable; in many cases
-they create complex synthetic accessor methods.
-</p>
-
-<p>
-There are different <em>types</em> of injected properties, defined by the type attribute of the <a href="spec.html#spec.inject">&lt;inject&gt;</a>
-element. The type determines how the object attribute is interpreted, and otherwise guides how code
-for the property is generated at runtime.  The default type is <strong>object</strong>.
-</p>
-
-<p>
-Like so much in Tapestry, this list is open to extension.  The 
-<a href="../tapestry/hivedocs/config/tapestry.enhance.InjectWorkers.html">tapestry.enhance.InjectWorkers</a> configuration point
-defines the available types of injection.
-The <a href="../tapestry/hivedocs/config/tapestry.enhance.EnhancementWorkers.html">tapestry.enhance.EnhancementWorkers</a> configuration
-point defines an entire pipeline used to perform runtime code enhancement (of which property injection
-is a critical phase).
-</p>
-
-<p>
-In addition, many other elements support a property attribute; this is the name of a property to create
-that holds the corresponding object.  For example, the <a href="spec.html#spec.bean">&lt;bean&gt;</a> element's property allows access
-to a managed bean; the bean is <em>still</em> created on first reference.  Components and assets
-may also be injected in this way.
-</p>
-
-
-<section name="meta injection">
-  
-  
-<p>
-The meta injection type provides a page or component with access to its meta data.  Meta data for a component is primarily provided as
-<a href="spec.html#spec.meta">&lt;meta&gt;</a> tags in the component or page specification.
-</p>
-  
-<p>
-However, meta-data may be specified elsewhere; the search starts in the component (or page) specification, but if not defined there, the
-search continues inside the component's namespace (its application or library specification).  If no value is found there,
-the search continues in the list of application property sources.  In other words, there are multiple places to set defaults, which can
-be overridden.
-</p>
-  
-<p>
-  Beyond wide searching, the other added value for the meta property injection is <em>type coercion</em>.  Meta data always
-  starts as simple strings, but your properties may be of any type.  Tapestry will attempt to coerce the string value to your desired
-  type.
-</p>
-
-<p>
-For example, perhaps you want to use meta-data to control the number of items from some large list that is displayed on a single page.
-You can define the meta-data, and the property in your page or component specification:
-</p>
-  
-<source xml:space="preserve">
+    <properties>
+        <title>Property Injection</title>
+    </properties>
+    <body>
+
+        <section name="Property Injection">
+            <p>
+                Tapestry 4.0 introduces an entirely new concept into Tapestry application
+                development: property injection. By use of the
+                <a href="spec.html#spec.inject">&lt;inject&gt;</a>
+                element in page and component specifications, it is possible to add new properties
+                to pages or components, using the
+                <a href="spec.html#spec.inject">&lt;inject&gt;</a>
+                element in the page or component specification.
+            </p>
+
+            <p>
+                The new properties that are created often are more than just wrappers around an
+                instance variable; in many cases they create complex synthetic accessor methods.
+            </p>
+
+            <p>
+                There are different
+                <em>types</em>
+                of injected properties, defined by the type attribute of the
+                <a href="spec.html#spec.inject">&lt;inject&gt;</a>
+                element. The type determines how the object attribute is interpreted, and otherwise
+                guides how code for the property is generated at runtime. The default type is
+                <strong>object</strong>
+                .
+            </p>
+
+            <p>
+                Like so much in Tapestry, this list is open to extension. The
+                <a href="../tapestry/hivedocs/config/tapestry.enhance.InjectWorkers.html">
+                    tapestry.enhance.InjectWorkers
+                </a>
+                configuration point defines the available types of injection. The
+                <a href="../tapestry/hivedocs/config/tapestry.enhance.EnhancementWorkers.html">
+                    tapestry.enhance.EnhancementWorkers
+                </a>
+                configuration point defines an entire pipeline used to perform runtime code
+                enhancement (of which property injection is a critical phase).
+            </p>
+
+            <p>
+                In addition, many other elements support a property attribute; this is the name of a
+                property to create that holds the corresponding object. For example, the
+                <a href="spec.html#spec.bean">&lt;bean&gt;</a>
+                element's property allows access to a managed bean; the bean is
+                <em>still</em>
+                created on first reference. Components and assets may also be injected in this way.
+            </p>
+
+
+            <section name="meta injection">
+
+
+                <p>
+                    The meta injection type provides a page or component with access to its meta
+                    data. Meta data for a component is primarily provided as
+                    <a href="spec.html#spec.meta">&lt;meta&gt;</a>
+                    tags in the component or page specification.
+                </p>
+
+                <p>
+                    However, meta-data may be specified elsewhere; the search starts in the
+                    component (or page) specification, but if not defined there, the search
+                    continues inside the component's namespace (its application or library
+                    specification). If no value is found there, the search continues in the list of
+                    application property sources. In other words, there are multiple places to set
+                    defaults, which can be overridden.
+                </p>
+
+                <p>
+                    Beyond wide searching, the other added value for the meta property injection is
+                    <em>type coercion</em>
+                    . Meta data always starts as simple strings, but your properties may be of any
+                    type. Tapestry will attempt to coerce the string value to your desired type.
+                </p>
+
+                <p>
+                    For example, perhaps you want to use meta-data to control the number of items
+                    from some large list that is displayed on a single page. You can define the
+                    meta-data, and the property in your page or component specification:
+                </p>
+
+                <source xml:space="preserve">
 
   &lt;meta key="page.size" value="15"/&gt;
   
   &lt;inject property="pageSize" type="meta" object="page.size"/&gt;
 
-</source>  
-  
-<p>
-You can access the this meta data value in code by defining a property:
-</p>
+</source>
 
-<source xml:space="preserve">
+                <p>You can access the this meta data value in code by defining a property:</p>
+
+                <source xml:space="preserve">
   
   public abstract int getPageSize();
   
 </source>
-  
-</section> <!-- injection.meta -->
 
-<section name="object injection">
-  
-  
-<p>
-The most common kind of injection, because "object" is the default injection type. The object is a HiveMind object.
-The <a href="hivemind.html">HiveMind integration documentation</a> covers this type
-of injection in more detail.
-</p>
+            </section><!-- injection.meta -->
 
-<p>
+            <section name="object injection">
 
-</p>
 
-</section> <!-- injection.object -->
+                <p>
+                    The most common kind of injection, because "object" is the default injection
+                    type. The object is a HiveMind object. The
+                    <a href="hivemind.html">HiveMind integration documentation</a>
+                    covers this type of injection in more detail.
+                </p>
 
-<section name="page injection">
-  
-  
-<p>
-Page injection allows a page to be injected into another page (or component). Beneather the covers,
-the logic simply accesses the <a href="../tapestry-framework/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a> object and obtains the page from it, and adds a
-cast if necessary.
-</p>
+                <p>
+
+                </p>
+
+            </section><!-- injection.object -->
+
+            <section name="page injection">
 
-<p>
-The property type can be Object, <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>, or any type assignable to <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>.
-</p>
 
-<p>
-  This is often used with <a href="listenermethods.html">listener method</a>s.  For example:
-</p>
+                <p>
+                    Page injection allows a page to be injected into another page (or component).
+                    Beneather the covers, the logic simply accesses the
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/IRequestCycle.html">
+                        IRequestCycle
+                    </a>
+                    object and obtains the page from it, and adds a cast if necessary.
+                </p>
 
-<source xml:space="preserve">
+                <p>
+                    The property type can be Object,
+                    <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+                    , or any type assignable to
+                    <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+                    .
+                </p>
+
+                <p>
+                    This is often used with
+                    <a href="listenermethods.html">listener method</a>
+                    s. For example:
+                </p>
+
+                <source xml:space="preserve">
   &lt;inject property="detailsPage" type="page" object="Details"/&gt;
 </source>
 
-<source xml:space="preserve">
+                <source xml:space="preserve">
   public abstract Details getDetailsPage();
   
   public IPage doShowDetails(long productId)
@@ -149,41 +179,45 @@
     return details;
   }
 </source>
-  
-<p>
-This is a common idiom: getting a page and casting it to its real type, invoking methods upon it,
-then returning it (from the listener method), so that it is activated to render the response.
-</p>
-  
-</section> <!-- injection.page -->
 
-<section name="script injection">
-  
-  
-<p>
-Tapestry includes extensive support for creating client-side JavaScript. At the core of this are specialized script templates. These templates
-must be parsed into <a href="../tapestry-framework/apidocs/org/apache/tapestry/IScript.html">IScript</a> objects in order to be used.  The script injection type hides the details of this process, and simply represents
-the parsed script template as a read-only property.
-</p>
-  
-<p>
-The object is the relative path to the script template; it is evaluated relative to the page or component specification (typically, it is another
-file in the same folder).  
-</p>
+                <p>
+                    This is a common idiom: getting a page and casting it to its real type, invoking
+                    methods upon it, then returning it (from the listener method), so that it is
+                    activated to render the response.
+                </p>
+
+            </section><!-- injection.page -->
+
+            <section name="script injection">
+
+
+                <p>
+                    Tapestry includes extensive support for creating client-side JavaScript. At the
+                    core of this are specialized script templates. These templates must be parsed
+                    into
+                    <a href="../tapestry-framework/apidocs/org/apache/tapestry/IScript.html">
+                        IScript
+                    </a>
+                    objects in order to be used. The script injection type hides the details of this
+                    process, and simply represents the parsed script template as a read-only
+                    property.
+                </p>
+
+                <p>
+                    The object is the relative path to the script template; it is evaluated relative
+                    to the page or component specification (typically, it is another file in the
+                    same folder).
+                </p>
 
-<p>
-This example is from the Palette component:
-</p>
+                <p>This example is from the Palette component:</p>
 
-<source xml:space="preserve">
+                <source xml:space="preserve">
   &lt;inject property="script" type="script" object="Palette.script"/&gt;
 </source>
 
-<p>
-The script can then be executed from the Java code:
-</p>
+                <p>The script can then be executed from the Java code:</p>
 
-<source xml:space="preserve">
+                <source xml:space="preserve">
   public abstract IScript getScript();
 
   . . .   
@@ -193,39 +227,49 @@
   getScript().execute(cycle, pageRenderSupport, _symbols);
 </source>
 
-</section> <!-- injection.script -->
+            </section><!-- injection.script -->
 
-<section name="state injection">
-  
-  
-<p>
-This style of injection allows easy access to <a href="state.html#state.aso">Application State Objects</a>,
-objects which store various kinds of global information (information needed on many pages).
-</p>  
-  
-</section>
+            <section name="state injection">
 
-<section name="state-flag injection">
-  
-  
-  <p>
-  Using the <a href="#injection.state">state</a> injection can force the creation
-  of an application state object; this type of injection will create a <em>read only</em>
-  boolean property that indicates <em>if</em> an application state object already exists.
-  </p>
-  
-  <p>
-    This is used to <em>prevent</em> the creation of an application state object until it
-    is absolutely needed.
-  </p>
-  
-  <p>
-    For example; in a situtation where the user may or may not be logged in, you would
-    inject a state flag and the state in two properties and check the state flag
-    <em>first</em>:
-  </p>
-  
-<source xml:space="preserve">
+
+                <p>
+                    This style of injection allows easy access to
+                    <a href="state.html#state.aso">Application State Objects</a>
+                    , objects which store various kinds of global information (information needed on
+                    many pages).
+                </p>
+
+            </section>
+
+            <section name="state-flag injection">
+
+
+                <p>
+                    Using the
+                    <a href="#injection.state">state</a>
+                    injection can force the creation of an application state object; this type of
+                    injection will create a
+                    <em>read only</em>
+                    boolean property that indicates
+                    <em>if</em>
+                    an application state object already exists.
+                </p>
+
+                <p>
+                    This is used to
+                    <em>prevent</em>
+                    the creation of an application state object until it is absolutely needed.
+                </p>
+
+                <p>
+                    For example; in a situtation where the user may or may not be logged in, you
+                    would inject a state flag and the state in two properties and check the state
+                    flag
+                    <em>first</em>
+                    :
+                </p>
+
+                <source xml:space="preserve">
 // &lt;inject&gt; type state-flag in the XML
 public abstract boolean getUserIdentityExists();
 
@@ -244,7 +288,7 @@
   }
 }
 </source>
-</section> <!-- injection.state-flag -->
-    
-  </body>
+            </section><!-- injection.state-flag -->
+        </section>
+    </body>
 </document>



Mime
View raw message