src/site/xdoc/components/general/shell.xml (443 lines of code) (raw):
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2004, 2005 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>
<properties>
<title>Shell</title>
</properties>
<body>
<section name="Shell">
<p>
Provides the outer 'shell' of a page, including the <code><html>, <head></code> and
<code><title></code> tags, but not the <code><body></code> tag (which is typically provided by a
<a href="Body.html">Body</a>
component).
</p>
<p>
Most Tapestry pages will include a Shell component enclosing a
<a href="body.html">Body</a>
component. The Shell is used to resolve the page's HTML stylesheet and the
<a href="body.html">Body</a>
component manages dynamically generated JavaScript.
</p>
<p>
When designing the look and feel of a Tapestry page, include the normal HTML
elements before the Shell component, including a <code><link rel="stylesheet"></code>
element, so that the page will render normally in a web browser, but use a
<code><span jwcid="$content$"></code> around the actual content.
</p>
<p>
<strong>
See also:
<a href="../../apidocs/org/apache/tapestry/html/Shell.html">
org.apache.tapestry.html.Shell
</a>
,
<a href="body.html">Body</a>
,
<a href="../link/pagelink.html">PageLink</a>
</strong>
</p>
<section name="Parameters">
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Required</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>title</td>
<td>String</td>
<td>yes</td>
<td></td>
<td>The title for the page, used to render the <code><title></code> tag.</td>
</tr>
<tr>
<td>raw</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
If false (the default), then HTML characters in the title are escaped.
If true, then value is emitted exactly as is.
</td>
</tr>
<tr>
<td>stylesheet</td>
<td>
<a href="../../apidocs/org/apache/tapestry/IAsset.html">
IAsset
</a>
</td>
<td>no</td>
<td></td>
<td>If provided, then a <code><link></code> to the stylesheet is generated.</td>
</tr>
<tr>
<td>stylesheets</td>
<td>
Array or collection of
<a href="../../apidocs/org/apache/tapestry/IAsset.html">
IAsset
</a>
</td>
<td>no</td>
<td></td>
<td>
If provided, then <code><link></code> elements are created for each stylesheet
asset.
</td>
</tr>
<tr>
<td>doctype</td>
<td>String</td>
<td>no</td>
<td>
HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd"
</td>
<td>
Used to specify the full definition of the DOCTYPE element in the
response page.
</td>
</tr>
<tr>
<td>renderContentType</td>
<td>boolean</td>
<td>no</td>
<td>true</td>
<td>
If true (the default), then a <code><meta></code> tag will be written to set
the content type of the page.
</td>
</tr>
<tr>
<td>disableTapestryMeta</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
When set to true, disables rendering of hidden comment meta content normally
written out which includes the Tapestry version being used as well as total rendering time
that each response takes. This should be used by people not wanting to make their use or version
of any particular framework a widely known item.
</td>
</tr>
<tr>
<td>refresh</td>
<td>int</td>
<td>no</td>
<td></td>
<td>
If provided, then a <code><meta></code> tag will be written to cause a page
refresh. The parameter value is the number of seconds before the
refresh.
</td>
</tr>
<tr>
<td>disableCaching</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
If provided, then a <code><meta></code> tag will be written setting the
content="nocache" value to try and prevent browser caching of page.
</td>
</tr>
<tr>
<td>delegate</td>
<td>
<a href="../../apidocs/org/apache/tapestry/IRender.html">
IRender
</a>
</td>
<td>no</td>
<td></td>
<td>
If specified, the delegate is rendered before the close of the
<code><head></code> tag. Typically, this is used to provide additional
<code><meta></code> tags.
</td>
</tr>
<tr>
<td>renderBaseTag</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
Specifies whether or not to render the html BASE tag element in the
document HEAD.
</td>
</tr>
<tr>
<td>ajaxDelegate</td>
<td>
<a href="../../apidocs/org/apache/tapestry/IRender.html">
IRender
</a>
</td>
<td>no</td>
<td>
<a href="../../apidocs/org/apache/tapestry/dojo/AjaxShellDelegate.html">
AjaxShellDelegate
</a>
</td>
<td>
If specified, allows for the default ajaxDelegate that renders the dojo script
includes to be overriden.
</td>
</tr>
</table>
<p>
Parameters used to configure the default
<a href="../../apidocs/org/apache/tapestry/dojo/AjaxShellDelegate.html">ajaxDelegate</a> :
<span class="info">
<strong>Info:</strong>
<p>If you've bound the ajaxDelegate parameter to a custom value,
the parameters that follow will not be used (usually those
custom delegates will provide different means for configuration). </p>
</span>
</p>
<table>
<tr>
<th>Name</th>
<th>Type</th>
<th>Required</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>browserLogLevel</td>
<td>String - One of [DEBUG,INFO,WARNING,ERROR,CRITICAL]</td>
<td>no</td>
<td>WARNING</td>
<td>
Sets the default browser based javascript log level to use to debug client side
interactions. If you specify an html element id to place the debug content it will be
written there. Otherwise, the default is to write to an element with id "debug", or append to
the document body if none exists.
<p>
See the dojo docs for more information about logging, but the basic idea is that you can write
statements like <code>dojo.log.info("Doing some operation");</code> in javascript and have them
appropriately filtered based on the log level used.
</p>
</td>
</tr>
<tr>
<td>debugEnabled</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
Turns browser level logging completely on/off.
</td>
</tr>
<tr>
<td>debugAtAllCosts</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
Turns off deep context level javascript debugging mode for dojo. This means
that exceptions/debug statements will show you line numbers from the actual
javascript file that generated them instead of the normal default which is
usually bootstrap.js .
<p>
People should be wary of turning this on as it may cause problems under certain
conditions, and you definitely don't ever want this on in production.
</p>
</td>
</tr>
<tr>
<td>debugContainerId</td>
<td>String</td>
<td>no</td>
<td> </td>
<td>
If you have logging turned on, all browser debug content is appended at the end of the
html document.
You can control this behavior by setting this parameter to the html element node id
that you want to receive the debug content.
<p>
For example, if you had an element on your html page with <code>id="myElement"</code> you would
set the debugContainerId to <code>"myElement"</code>.
</p>
</td>
</tr>
<tr>
<td>consoleEnabled</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
Enables/disables the dojo.debug.console functionality which should redirect
most logging messages to your browsers javascript console. (if it supports one).
<p>
The debug console is disabled by default. Currently known supported browsers
are FireFox(having FireBug extension helps a great deal)/Opera/Safari.
</p>
</td>
</tr>
<tr>
<td>preventBackButtonFix</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
Sets the dojo preventBackButtonFix djConfig configuration. This should typically
be avoided but is provided for flexibility.
</td>
</tr>
<tr>
<td>parseWidgets</td>
<td>boolean</td>
<td>no</td>
<td>false</td>
<td>
Tells dojo whether or not to parse widgets by traversing the entire dom node of your
document. It is highly reccomended that you keep this at its default value of false.
</td>
</tr>
<tr>
<td>searchIds</td>
<td>String</td>
<td>no</td>
<td></td>
<td>
Provides a way to have dojo automatically parse a set of html nodes for
widgets without enabling full automatic parsing (which is controlled by the
parseWidgets parameter). Example value: ['node1', 'node2']
</td>
</tr>
<tr>
<td>tapestrySource</td>
<td>
<a href="../../apidocs/org/apache/tapestry/IAsset.html">
IAsset
</a>
</td>
<td>false</td>
<td>classpath:/tapestry/core.js</td>
<td>
Controls what the root source inclusion is for tapestry javascript packages. Override if you
want to replace the built in defaults with a version of your own.
</td>
</tr>
<tr>
<td>dojoSource</td>
<td>
<a href="../../apidocs/org/apache/tapestry/IAsset.html">
IAsset
</a>
</td>
<td>false</td>
<td>classpath:/dojo/dojo.js</td>
<td>
Controls what the root source inclusion is for the dojo javascript packages. Override if you
want to replace the built in defaults with a version of your own.
</td>
</tr>
<tr>
<td>dojoPath</td>
<td>
<a href="../../apidocs/org/apache/tapestry/IAsset.html">
IAsset
</a>
</td>
<td>false</td>
<td>classpath:/dojo/</td>
<td>
Specifies the default path to the root dojo folder, not the dojo.js file itself. This
is used by the <code>djConfig.baseRelativePath</code> javascript configuration property in dojo
to resolve relative resource includes - like widgets/images/js/css/etc..
</td>
</tr>
</table>
<p>
Body:
<strong>allowed</strong>
</p>
<p>
Informal parameters:
<strong>allowed</strong> <em>(informal parameters written to top level html tag)</em>
</p>
<p>
Reserved parameters:
<em>none</em>
</p>
</section>
<section name="Order of Rendered Content">
<ul>
<li>Doctype</li>
<li>Tapestry metadata as comments (optional)</li>
<li><code><html></code> with informal parameters</li>
<li><code><head></code></li>
<li><code><meta></code> related to content generator, caching, content type and refresh (optional)</li>
<li><code><base></code> (optional)</li>
<li><code><title></code></li>
<li>Rendering of delegate parameter</li>
<li>Stylesheets as defined in the stylesheet and stylesheets parameters</li>
<li>Stylesheets and <code><link></code> to documents as discovered
from <a href="style.html">Style</a> and <a href="relation.html">Relation</a> components within the rendered page
</li>
<li>Rendering of ajaxDelegate parameter
<span class="info">
<strong>Info:</strong>
<p>Prior to 4.1.7, the ajaxDelegate would render one step earlier
(before the <a href="style.html">Style</a> and <a href="relation.html">Relation</a> components)
</p>
</span>
</li>
<li>Rendering of any additional content included via <a href="../../apidocs/org/apache/tapestry/html/Shell.html#includeAdditionalContent(java.lang.String)">Shell#includeAdditionalContent(String)</a>
</li>
<li><code></head></code></li>
<li>Rendering of the component's body</li>
<li><code></html></code> and optional comment with the elapsed render time</li>
</ul>
</section>
<section name="Examples">
<p>The Shell component is used here to provide the page's stylesheet and title.</p>
<p>
In this example, the Login.html template is in the login subdirectory of the
root application context. The stylesheet is within the styles directory, below
the root application context.
</p>
<p>login/Login.html:</p>
<source xml:space="preserve">
<html>
<head>
<link rel="stylesheet" type="text/css" href="../styles/style.css"/>
<title>MyCorp Customer Login</title>
</head>
<span jwcid="$content$">
<span jwcid="@Shell" stylesheet="asset:stylesheet" title="MyCorp Customer Login">
<body jwcid="@Body">
<h1>Customer Login</h1>
Welcome to MyCorp's Customer Portal secure login page.
. . .
</body>
</span>
</span>
</html>
</source>
<p>WEB-INF/login/Login.page:</p>
<source xml:space="preserve">
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE page-specification PUBLIC
"-//Apache Software Foundation//Tapestry Specification 4.0//EN"
"http://tapestry.apache.org/dtd/Tapestry_4_0.dtd">
<page-specification>
. . .
<asset name="stylesheet" path="styles/style.css"/>
</page-specification>
</source>
<p>
Note that for page and component specifications stored in the web application
context (even under WEB-INF), relative asset paths are computed from the
<em>root application context directory</em>
.
</p>
</section>
</section>
</body>
</document>