tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Tapestry > Layout Component
Date Wed, 18 Jan 2012 02:11:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/12/_/styles/combined.css?spaceKey=TAPESTRY&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Layout+Component">Layout
Component</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~bobharner">Bob
Harner</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Added Nested Layouts section, and some wordsmithing and link fixes<br />
    </div>
        <br/>
                         <h4>Changes (14)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{float} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >You may see frequent reference
to a *Layout Component*, but you won&#39;t find it in the [component <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">reference|http://tapestry.apache.org/current/apidocs/index.html].</span>
<span class="diff-added-words"style="background-color: #dfd;">reference|Component Reference].</span>
The Layout Component is a component _that you create_ to provide common elements across all
of your pages. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >In traditional servlet development,
you may be familiar with the use of a JSP include to include a banner across the top of your
page and a copyright message across the bottom. Tapestry doesn&#39;t have a mechanism
for such <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">includes,</span>
<span class="diff-added-words"style="background-color: #dfd;">includes --</span>
nor does it <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">have
the need.</span> <span class="diff-added-words"style="background-color: #dfd;">need
one.</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Instead,
you create a layout component that acts like a template for your pages: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Instead,
you create a layout component that acts as a template: <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code:xml|title=Layout.tml}
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Layout
is a regular component like any other, with an ordinary component template. Like all component
templates, it will be stored on the classpath (i.e., under src/main/resources). <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">and
then each page in your application can wrap itself in that template. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >The magic is in the &lt;t:body/&gt;
element in the center; this will be replaced by <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">the
_page&#39;s content_,</span> <span class="diff-added-words"style="background-color:
#dfd;">each page&#39;s _content_,</span> whatever that is. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >In a real-world example, the two
&lt;div&gt; elements in this example might contain the typical <span class="diff-added-words"style="background-color:
#dfd;">repeating</span> content you&#39;ll see <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">in</span>
<span class="diff-added-words"style="background-color: #dfd;">across the pages of</span>
a web application: banners (and banner ads!), menus, login forms and so forth. <span class="diff-added-words"style="background-color:
#dfd;">Often these components get very complex ... in fact, in many applications the Layout
component grows to be more complex than almost any other component.</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Often
these get very complex ... in fact, in most applications, the Layout component grows to be
more complex than almost any page in the application. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >{info} <br>Remember that if
your layout component includes a link to a resource such as an image or a stylesheet, you
must use an _absolute_ URL. The same component will be used for pages in many different folders,
or with many different activation contexts, so relative URLs won&#39;t work. <br>{info}
<br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Layout
is a regular component like other, with an ordinary component template. Like all component
templates, it will be stored on the classpath (typically under src/main/resources). <br>
<br></td></tr>
            <tr><td class="diff-unchanged" >Components must always have a Java
class. But in this trivial example, the Layout component doesn&#39;t need any logic: <br>
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">We
save ourselves some typing by using the @[Import|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html]
annotation (in 5.2 or later), as opposed to directly adding the &lt;link&gt; element
to the template. (For 5.0 and 5.1, use the deprecated @[IncludeStyleSheet|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html]
annotation instead.) <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">We
use the @[Import|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html]
annotation (in 5.2 or later), as opposed to directly adding the &lt;link&gt; element
to the template, for significant performance benefits [described elsewhere|Assets]. (For 5.0
and 5.1, use the deprecated @[IncludeStyleSheet|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html]
annotation instead.)  <br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >Any page in the application that follows
this pattern, using the Layout component, will have the same look and feel. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >You may find that your application
has more than one look and feel: perhaps user registration pages have one look, while administrative
pages have another. This can be accomplished by having multiple <span class="diff-changed-words"><span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">L</span><span
class="diff-added-chars"style="background-color: #dfd;">l</span>ayout</span>
components <span class="diff-added-words"style="background-color: #dfd;">(using any
names you choose)</span> and using <span class="diff-added-words"style="background-color:
#dfd;">those</span> different layout types for different pages. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>h2. Nested Layouts <br> <br>Layouts are really just ordinary components,
so they can be nested to any level needed. You can have, for example, a &quot;CommonLayout&quot;
component that provides the peripheral elements for all your pages, and then a more specialized
&quot;AdminLayout&quot; component that provides the layout only for the administrative
pages, and make the AdminLayout component wrap itself in the CommonLayout component. So then
the administrative pages would start with {{&lt;html t:type=&quot;adminLayout&quot;
...&gt;}} and the other pages (and the AdminLayout component itself) would start with
{{&lt;html t:type=&quot;commonLayout&quot; ...&gt;}}. <br> <br>{code:xml|title=AdminLayout.tml}
<br>&lt;html t:type=&quot;commonLayout&quot; xmlns:t=&quot;http://tapestry.apache.org/schema/tapestry_5_1_0.xsd&quot;&gt;
<br> <br>    &lt;h1&gt;Administrative Functions&lt;/h1&gt; <br>
<br>    &lt;t:body/&gt; <br> <br>&lt;/html&gt; <br>{code}
<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <div class='navmenu' style='float:right; background:#eee; margin:3px; padding:3px'><table
class="tableview" width="100%">
            <tr><th style="padding: 3px 3px 3px 0px">Related Articles</th></tr>
                        <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Component+Parameters">Component
Parameters</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Component+Cheat+Sheet">Component
Cheat Sheet</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Templating+and+Markup+FAQ">Templating
and Markup FAQ</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Page+And+Component+Classes+FAQ">Page
And Component Classes FAQ</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Component+Templates">Component
Templates</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Component+Classes">Component
Classes</a>
        
                                            </td>
        </tr>
            </table>
</div>

<p>You may see frequent reference to a <b>Layout Component</b>, but you
won't find it in the <a href="/confluence/display/TAPESTRY/Component+Reference" title="Component
Reference">component reference</a>. The Layout Component is a component <em>that
you create</em> to provide common elements across all of your pages.</p>

<p>In traditional servlet development, you may be familiar with the use of a JSP include
to include a banner across the top of your page and a copyright message across the bottom.
Tapestry doesn't have a mechanism for such includes &#8211; nor does it need one.</p>

<p>Instead, you create a layout component that acts as a template:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>Layout.tml</b></div><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;html <span class="code-keyword">xmlns:t</span>=<span
class="code-quote">"http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"</span>&gt;</span>
    <span class="code-tag">&lt;head&gt;</span>
        <span class="code-tag">&lt;title&gt;</span>My Nifty Web Application<span
class="code-tag">&lt;/title&gt;</span>
    <span class="code-tag">&lt;/head&gt;</span>
    <span class="code-tag">&lt;body&gt;</span>
        <span class="code-tag">&lt;div class=<span class="code-quote">"nav-top"</span>&gt;</span>
            Nifty Web Application
        <span class="code-tag">&lt;/div&gt;</span>
    
        <span class="code-tag">&lt;t:body/&gt;</span>

        <span class="code-tag">&lt;div class=<span class="code-quote">"nav-bottom"</span>&gt;</span>
            (C) 2008 NiftyWebCo, Inc.
        <span class="code-tag">&lt;/div&gt;</span>
    <span class="code-tag">&lt;/body&gt;</span>
<span class="code-tag">&lt;/html&gt;</span>
</pre>
</div></div>

<p>and then each page in your application can wrap itself in that template.</p>

<p>The magic is in the &lt;t:body/&gt; element in the center; this will be replaced
by each page's <em>content</em>, whatever that is.</p>

<p>In a real-world example, the two &lt;div&gt; elements in this example might
contain the typical repeating content you'll see across the pages of a web application: banners
(and banner ads!), menus, login forms and so forth. Often these components get very complex
... in fact, in many applications the Layout component grows to be more complex than almost
any other component.</p>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td>Remember that if your
layout component includes a link to a resource such as an image or a stylesheet, you must
use an <em>absolute</em> URL. The same component will be used for pages in many
different folders, or with many different activation contexts, so relative URLs won't work.</td></tr></table></div>

<p>Layout is a regular component like other, with an ordinary component template. Like
all component templates, it will be stored on the classpath (typically under src/main/resources).</p>

<p>Components must always have a Java class. But in this trivial example, the Layout
component doesn't need any logic:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>Layout.java</b></div><div class="codeContent
panelContent">
<pre class="code-java">
@Import(stylesheet=<span class="code-quote">"context:css/site.css"</span>)
<span class="code-keyword">public</span> class Layout
{
}
</pre>
</div></div>

<p>We use the @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html"
class="external-link" rel="nofollow">Import</a> annotation (in 5.2 or later), as
opposed to directly adding the &lt;link&gt; element to the template, for significant
performance benefits <a href="/confluence/display/TAPESTRY/Assets" title="Assets">described
elsewhere</a>. (For 5.0 and 5.1, use the deprecated @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html"
class="external-link" rel="nofollow">IncludeStyleSheet</a> annotation instead.) </p>


<h2><a name="LayoutComponent-UsingtheLayoutinaPage"></a>Using the Layout
in a Page</h2>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>Welcome.tml</b></div><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;html t:type=<span class="code-quote">"layout"</span>
<span class="code-keyword">xmlns:t</span>=<span class="code-quote">"http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"</span>&gt;</span>

   <span class="code-tag">&lt;h1&gt;</span>Welcome to the Nifty Web Application!<span
class="code-tag">&lt;/h1&gt;</span>

   <span class="code-tag">&lt;p&gt;</span>
        Would you like to <span class="code-tag">&lt;t:pagelink page=<span class="code-quote">"login"</span>&gt;</span>Log
In<span class="code-tag">&lt;/t:pagelink&gt;</span>?
   <span class="code-tag">&lt;/p&gt;</span>
<span class="code-tag">&lt;/html&gt;</span>
</pre>
</div></div>

<p>This is an example of using the Layout component in a page (in this case, Welcome.tml).
To keep our Welcome.tml template relatively preview-able, we are using an &lt;html&gt;
element and the t:type attribute to specify that it is a component.</p>

<p>The &lt;html&gt; tag will be removed, and replaced with the content from
the Layout.tml template (which conveniently starts with an &lt;html&gt; element).
The &lt;t:body&gt; in Layout.tml will be replaced with the page specific content here:
the &lt;h1&gt; and &lt;p&gt; tags.</p>

<p>Any page in the application that follows this pattern, using the Layout component,
will have the same look and feel.</p>

<p>You may find that your application has more than one look and feel: perhaps user
registration pages have one look, while administrative pages have another. This can be accomplished
by having multiple layout components (using any names you choose) and using those different
layout types for different pages.</p>

<h2><a name="LayoutComponent-NestedLayouts"></a>Nested Layouts</h2>

<p>Layouts are really just ordinary components, so they can be nested to any level needed.
You can have, for example, a "CommonLayout" component that provides the peripheral elements
for all your pages, and then a more specialized "AdminLayout" component that provides the
layout only for the administrative pages, and make the AdminLayout component wrap itself in
the CommonLayout component. So then the administrative pages would start with <tt>&lt;html
t:type="adminLayout" ...&gt;</tt> and the other pages (and the AdminLayout component
itself) would start with <tt>&lt;html t:type="commonLayout" ...&gt;</tt>.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>AdminLayout.tml</b></div><div
class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;html t:type=<span class="code-quote">"commonLayout"</span>
<span class="code-keyword">xmlns:t</span>=<span class="code-quote">"http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"</span>&gt;</span>

    <span class="code-tag">&lt;h1&gt;</span>Administrative Functions<span
class="code-tag">&lt;/h1&gt;</span>

    <span class="code-tag">&lt;t:body/&gt;</span>

<span class="code-tag">&lt;/html&gt;</span>
</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Layout+Component">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=22872112&revisedVersion=9&originalVersion=8">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message