Author: buildbot
Date: Sat Sep 14 22:20:58 2013
New Revision: 878442
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/javascript.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/javascript.html
==============================================================================
--- websites/production/tapestry/content/javascript.html (original)
+++ websites/production/tapestry/content/javascript.html Sat Sep 14 22:20:58
2013
@@ -0,0 +1,568 @@
+<!DOCTYPE html>
+
+ <!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You 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.
+-->
+<html>
+<head>
+ <meta http-equiv="x-ua-compatible" content="IE=9">
+ <title>
+ JavaScript -- Apache Tapestry
+ </title>
+ <link type="text/css" rel="stylesheet" href="/resources/space.css">
+ <link href="/styles/style.css" rel="stylesheet" type="text/css"/>
+</head>
+<body>
+ <div class="wrapper bs">
+
+<div id="navigation"><div class="nav"><ul class="alternate"
type="square"><li><a shape="rect" href="index.html"
title="Index">Home</a></li><li><a shape="rect" href="getting-started.html"
title="Getting Started">Getting Started</a></li><li><a shape="rect"
href="documentation.html" title="Documentation">Documentation</a></li><li><a
shape="rect" href="download.html" title="Download">Download</a></li><li><a
shape="rect" href="about.html" title="About">About</a></li><li><a shape="rect"
href="community.html" title="Community">Community</a></li><li><a shape="rect"
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
shape="rect" class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
shape="rect" class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul>
+</div>
+</div>
+
+<div id="top">
+<div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em
1em .1em 1em"><p>
+<span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis &
blogs:</span>
+</p><form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form>
+
+</div>
+
+<div class="emblem" style="float:left"><a shape="rect" href="index.html"
title="Index"><span class="image-wrap" style=""><img
src="small-banner.data/tapestry_s.png" style="border: 0px solid
black"></span></a></div>
+<div class="title" style="float:left; margin: 0 0 0 3em"><h1><a shape="rect"
name="SmallBanner-PageTitle"></a>JavaScript</h1></div></div>
+<div class="clearer"></div>
+</div>
+
+<div class="clearer"></div>
+
+ <div id="breadcrumbs">
+ <a href="index.html">Apache Tapestry</a> > <a
href="documentation.html">Documentation</a> > <a
href="user-guide.html">User Guide</a> > <a
href="javascript.html">JavaScript</a>
+ <a class="edit" title="Edit this page (requires approval -- just ask on
the mailing list)"
href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=21792074";>edit</a>
+ </div>
+
+<div id="content">
+<div id="ConfluenceContent"><div class="navmenu" style="float:right;
background:#eee; margin:3px; padding:3px"><table class="tableview"
width="100%"><tr><th colspan="1" rowspan="1" style="padding: 3px 3px 3px
0px">Related Articles</th></tr><tr><td colspan="1" rowspan="1">
+ <span class="icon icon-page"
title="Page">Page:</span>
+ <a shape="rect" href="ajax-and-zones.html">Ajax and
Zones</a>
+
+ </td></tr><tr><td colspan="1"
rowspan="1">
+ <span class="icon icon-page"
title="Page">Page:</span>
+ <a shape="rect" href="javascript.html">JavaScript</a>
+
+ </td></tr><tr><td colspan="1"
rowspan="1">
+ <span class="icon icon-page"
title="Page">Page:</span>
+ <a shape="rect" href="assets.html">Assets</a>
+
+ </td></tr><tr><td colspan="1"
rowspan="1">
+ <span class="icon icon-page"
title="Page">Page:</span>
+ <a shape="rect" href="ajax-components-faq.html">Ajax
Components FAQ</a>
+
+ </td></tr><tr><td colspan="1"
rowspan="1">
+ <span class="icon icon-page"
title="Page">Page:</span>
+ <a shape="rect"
href="component-cheat-sheet.html">Component Cheat Sheet</a>
+
+ </td></tr><tr><td colspan="1"
rowspan="1">
+ <span class="icon icon-page"
title="Page">Page:</span>
+ <a shape="rect" href="javascript-faq.html">JavaScript
FAQ</a>
+
+ </td></tr></table>
+</div>
+
+<p><b>JavaScript</b> is a first-class concept in Tapestry, and sophisticated
JavaScript support is provided right out of the box, including rich <a
shape="rect" href="ajax-and-zones.html" title="Ajax and Zones">AJAX
support</a>, download optimization, client-side logging, and localization.</p>
+
+<p>In production mode, by default, Tapestry will merge JavaScript libraries,
add version numbering, and set a far-future expires header to encourage
aggressive browser caching. Starting with version 5.3, Tapestry can also
automatically minify (compress) JavaScript libraries when in <a shape="rect"
href="configuration.html#Configuration-ConfigurationConfigurationSymbolNames">production
mode</a>.</p>
+
+<p>In addition, as will be described in detail <a shape="rect"
href="#JavaScript-BuiltinLibraries">below</a>, Tapestry comes with the <a
shape="rect" class="external-link" href="http://www.prototypejs.org/";
>Prototype</a> and <a shape="rect" class="external-link"
href="http://script.aculo.us/"; >Scriptaculous</a> libraries, or you can easily
swap in JQuery using a 3rd-party module.</p>
+
+<h1><a shape="rect" name="JavaScript-AddingCustomJavaScript"></a>Adding Custom
JavaScript</h1>
+
+<p>When adding your own custom JavaScript or third-party libraries, just
follow the strategies below to take advantage of Tapestry's JavaScript support
mechanisms.</p>
+
+<p>The recommended practice in Tapestry is to package up any significant
amount of JavaScript as a static JavaScript library, a .js file that can be
downloaded to the client. Keep your in-page JavaScript code to a minimum, just
the few statements needed to initialize objects and reference methods in the
JavaScript libraries.</p>
+
+<h2><a shape="rect"
name="JavaScript-LinkingtoyourJavaScriptlibraries"></a>Linking to your
JavaScript libraries</h2>
+
+<p>Tapestry provides several ways to add a link to a JavaScript library within
your page or component. Although you can use direct <tt><script
type="text/javascript" src="xxx.js"></script></tt> approach, you
should only use it for JavaScript that resides outside of your application. For
JavaScript within your app, Tapestry provides <em>much</em> better ways to do
the same thing. Most users choose the simplest, the @Import annotation
approach.</p>
+
+<div class="navmenu" style="float:right; background:#eee; margin:3px;
padding:0 1em"><p><b>JumpStart Demo:</b> <br clear="none">
+<a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/javascript/javascript";
>JavaScript</a> </p></div>
+
+<h2><a shape="rect" name="JavaScript-Approach1%3A@Import"></a>Approach 1:
@Import</h2>
+
+<p>Use the @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html";>Import</a>
annotation (or @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/IncludeJavaScriptLibrary.html";>IncludeJavaScriptLibrary</a>
in Tapestry 5.0 and 5.1) to include links to JavaScript (and CSS) files in
your page or component. Tapestry ensures that each such file is only referenced
once in your page.</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0"
width="100%"><tbody><tr><td colspan="1" rowspan="1" valign="top"
class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.2 and
later</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+@Import(library={"context:js/jquery.js",
+ "context:js/myeffects.js"})
+public class MyComponent
+{
+ . . .
+}
+]]></script>
+</div></div></td><td colspan="1" rowspan="1" valign="top" class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.0 and
5.1</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+@IncludeJavaScriptLibrary(value={"context:js/jquery.js",
+ "context:js/myeffects.js"})
+public class MyComponent
+{
+ . . .
+}
+]]></script>
+</div></div></td></tr></tbody></table>
+
+<p>@Import may also be applied to individual methods, in which case the import
operation only occurs when the method is invoked.</p>
+
+<p>Note: When specifying a file to import, you'll often use the
<b>context:</b> binding prefix to indicate that the file is stored in the web
application context, and not on the classpath. Relative paths will be on the
classpath, relative to the Java class. See <a shape="rect"
href="component-parameters.html" title="Component Parameters">Component
Parameters</a> for other binding prefix options.</p>
+
+<p>Adding the same JavaScript library multiple times does <em>not</em> create
duplicate links. The subsequent ones are simply ignored. In this way, each
component can add the libraries it needs, without worrying about conflicts with
other components.</p>
+
+<h2><a shape="rect"
name="JavaScript-Approach2%3AJavaScriptSupport"></a>Approach 2:
JavaScriptSupport</h2>
+
+<p>Alternatively, you can use <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html";>JavaScriptSupport</a>
(for Tapestry 5.2 or later) or <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/RenderSupport.html";>RenderSupport</a>
(for Tapestry 5.0 and 5.1) to include a JavaScript library in your page or
component. JavaScriptSupport and RenderSupport are <a shape="rect"
href="environmental-services.html" title="Environmental Services">environmental
services</a> that include a number of methods that will be used by components,
or by services that are called from components. For example:</p>
+
+<h3><a shape="rect"
name="JavaScript-The%7B%7BimportJavaScriptLibrary%7D%7Dmethod"></a>The
<tt>importJavaScriptLibrary</tt> method</h3>
+
+<p>The <tt>importJavaScriptLibrary</tt> method (or <tt>addScriptLink</tt> for
Tapestry 5.0 and 5.1) adds a link to a JavaScript library. A component can
inject such a script and pass one or more of assets to this method:</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0"
width="100%"><tbody><tr><td colspan="1" rowspan="1" valign="top"
class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>Tapestry 5.2 and
later</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Inject @Path("context:/js/myeffects.js")
+ private Asset myEffects;
+
+ @Environmental
+ private JavaScriptSupport javaScriptSupport;
+
+ void setupRender()
+ {
+ javaScriptSupport.importJavaScriptLibrary(myEffects);
+ }
+]]></script>
+</div></div></td><td colspan="1" rowspan="1" valign="top" class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>Tapestry 5.1 and
earlier</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Inject @Path("context:/js/myeffects.js")
+ private Asset myEffects;
+
+ @Environmental
+ private RenderSupport renderSupport;
+
+ void setupRender()
+ {
+ renderSupport.addScriptLink(myEffects);
+ }
+]]></script>
+</div></div></td></tr></tbody></table>
+
+<p>Tapestry will ensure that the necessary <link> elements are added to
the <em>top</em> of the document (in the <head> element). With Tapestry
5.3 and later the new elements are inserted at the bottom of the <head>
element; in versions before 5.3 they appear at the top of the <head>
element).</p>
+
+<p>As with the annotation approach, adding the same asset multiple times does
<em>not</em> create duplicate links.</p>
+
+<p>The <tt>setupRender</tt> method (the name is specifically linked to a <a
shape="rect" href="component-rendering.html" title="Component Rendering">render
phase</a>) is the correct place to inform the JavaScriptSupport (or
RenderSupport) service that the library is needed.</p>
+
+<div class="navmenu" style="float:right; background:#eee; margin:3px;
padding:0 1em"><p><b>JumpStart Demo:</b> <br clear="none">
+<a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/javascript/reusable";
>Reusable JavaScript</a> </p></div>
+
+<h3><a shape="rect" name="JavaScript-The%7B%7BaddScript%7D%7Dmethod"></a>The
<tt>addScript</tt> method</h3>
+
+<p>The <tt>addScript</tt> method is used when you need to add some JavaScript
code directly to the page. This will be inserted at the <em>bottom of the
document</em>, and will only be executed when the document has finished loading
on the client (i.e., from the window.onload event handler).</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0"
width="100%"><tbody><tr><td colspan="1" rowspan="1" valign="top"
class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>Tapestry 5.2 and
later</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+void afterRender()
+{
+ javaScriptSupport.addScript(
+ "$('%s').observe('click', hideMe());",
+ container.getClientId());
+}
+]]></script>
+</div></div></td><td colspan="1" rowspan="1" valign="top" class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>Tapestry 5.1 and
earlier</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+void afterRender()
+{
+ javaScriptSupport.addScript(String.format(
+ "$('%s').observe('click', hideMe());",
+ container.getClientId()));
+}
+]]></script>
+</div></div></td></tr></tbody></table>
+
+<p>When calling the method, the format string can include standard
substitutions (such as '%s') for arguments. This saves you the trouble of
calling String.format() yourself. (For Tapestry 5.1 and earlier, you must call
String.format() yourself.) In any case, the formatted JavaScript is added to
the script block in the rendered output.</p>
+
+<h3><a shape="rect" name="JavaScript-InjectingJavaScriptSupport"></a>Injecting
JavaScriptSupport</h3>
+
+<p>JavaScriptSupport (like RenderSupport before it) is an
<em>environmental</em> object, so you will normally inject it via the @<a
shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Environmental.html";>Environmental</a>
annotation:</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0"
width="100%"><tbody><tr><td colspan="1" rowspan="1" valign="top"
class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.2 and
later</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Environmental
+ private JavaScriptSupport javaScriptSupport;
+]]></script>
+</div></div></td><td colspan="1" rowspan="1" valign="top" class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.0 and
5.1</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Environmental
+ private RenderSupport renderSupport;
+]]></script>
+</div></div></td></tr></tbody></table>
+
+<p>The @Environmental annotation only works inside components, but
occasionally you may want to inject JavaScriptSupport (or RenderSupport) into a
service. Fortunately, a proxy has been set up to allow the use of @Inject
instead:</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0"
width="100%"><tbody><tr><td colspan="1" rowspan="1" valign="top"
class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.2 and
later</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Inject
+ private JavaScriptSupport javaScriptSupport;
+]]></script>
+</div></div></td><td colspan="1" rowspan="1" valign="top" class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.0 and
5.1</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Inject
+ private RenderSupport renderSupport;
+]]></script>
+</div></div></td></tr></tbody></table>
+
+<p>... or, in a service implementation constructor:</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0"
width="100%"><tbody><tr><td colspan="1" rowspan="1" valign="top"
class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.2 and
later</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ public MyServiceImpl(JavaScriptSupport support)
+ {
+ . . .
+ }
+]]></script>
+</div></div></td><td colspan="1" rowspan="1" valign="top" class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>For Tapestry 5.0 and
5.1</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ public MyServiceImpl(RenderSupport support)
+ {
+ . . .
+ }
+]]></script>
+</div></div></td></tr></tbody></table>
+
+<p>Inside a component, you should use @Environmental, to highlight the fact
that RenderSupport (like most environmental objects) is only available during
rendering, not during action requests.</p>
+
+<h1><a shape="rect"
name="JavaScript-CombiningJavaScriptlibraries"></a>Combining JavaScript
libraries</h1>
+
+
+
+<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="/images/confluence/information.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1"
rowspan="1"><b>Added in 5.1.0.2</b><br clear="none"></td></tr></table></div>
+<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid
#D8E4F1;"></div>
+<p>In production mode, Tapestry automatically <em>combines</em> JavaScript
libraries. A single request (for a <em>virtual asset</em>) will retrieve the
combined content of all referenced JavaScript library files.</p>
+
+<p>Note: starting with Tapestry 5.2, JavaScript libraries are only combined if
they are part of a JavaScript Stack (see below).</p>
+
+<p>This is a very useful feature, as it reduces the number of requests needed
to present a page to the user. It can be disabled, however, by setting the
SymbolConstants.COMBINE_SCRIPTS <a shape="rect" href="configuration.html"
title="Configuration">configuration symbol</a> to false in your application's
module class (normally AppModule.java). By default it is enabled when in
production mode and disabled otherwise.</p>
+
+<p>As elsewhere, if the client browser supports gzip compression, the combined
JavaScript will be compressed.</p>
+
+<h1><a shape="rect"
name="JavaScript-MinifyingJavaScriptlibraries"></a>Minifying JavaScript
libraries</h1>
+
+
+
+<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="/images/confluence/information.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1"
rowspan="1"><b>Added in 5.3</b><br clear="none"></td></tr></table></div>
+<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid
#D8E4F1;"></div>
+<p>In production mode, Tapestry can automatically <em>minify</em>
(intelligently compresses) JavaScript libraries (and CSS) when the application
starts up. This can significantly decrease the size of static content that the
browser needs to download.</p>
+
+<p>Minification is accomplished using the ResourceMinimizer service. A YUI
Compressor-based implementation is available, but this can be overridden.</p>
+
+<p>IMPORTANT NOTE: The tapestry-core module only provides the empty
infrastructure for supporting minification; the actual logic is supplied in the
tapestry-yuicompressor module. To use it, you'll need to update your
dependencies to include this module.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>Maven pom.xml
(partial)</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: xml; gutter: false"
type="syntaxhighlighter"><![CDATA[
+<dependency>
+ <groupId>org.apache.tapestry</groupId>
+ <artifactId>tapestry-yuicompressor</artifactId>
+ <version>${tapestry-release-version}</version>
+</dependency>
+]]></script>
+</div></div>
+
+<p>Gradle would be similar, of course. If you aren't using something like
Maven or Gradle, you'll have to download the jar and its dependency
(com.yahoo.platform.yui: yuicompressor) yourself.</p>
+
+<p>Minification can be disabled by setting the
SymbolConstants.MINIFICATION_ENABLED <a shape="rect" href="configuration.html"
title="Configuration">configuration symbol</a> to false in your application's
module class (usually AppModule.java). By default it is enabled when in
production mode and disabled otherwise.</p>
+
+<p>Please test your applications well: the YUI Compressor code can be somewhat
finicky about the application server and JDK version.</p>
+
+<h1><a shape="rect" name="JavaScript-ClientsideLogging"></a>Client-side
Logging</h1>
+
+
+
+<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="/images/confluence/forbidden.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1"
rowspan="1"><b>Deprecated since 5.3</b><br clear="none"></td></tr></table></div>
+<div style="border-right: 20px solid #ffcccc;border-left: 20px solid
#ffcccc;"></div>
+
+<p>In versions prior to 5.3, Tapestry uses a modified version of the <a
shape="rect" class="external-link"
href="http://www.gscottolson.com/blackbirdjs/"; >Blackbird</a> JavaScript
console. The Tapestry object includes three functions: debug, warn and
error.</p>
+
+<p>Each of these functions take a message and an optional pattern; if the
pattern is provided, the message is <a shape="rect" class="external-link"
href="http://prototypejs.org/api/string/interpolate"; >interpolated</a> on the
pattern. The final message is displayed in the Blackbird console, which will
make itself visible automatically.</p>
+
+<p>In production mode, debug messages will be filtered out (they will not be
visible until the user presses F2 to display the console, and then clicks the
grayed out icon for debug messages). In development mode, debug messages are
not filtered out.</p>
+
+<p>Example usage:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ Tapestry.debug("Field id is #{id}, value is #{value}", field);
+
+ Tapestry.error("Server is not available.");
+
+]]></script>
+</div></div>
+
+<p>With Tapestry 5.3 and later the Blackbird console has been removed; just
use the standard console logging features (e.g. <tt>console.log()</tt>) built
into modern browsers.</p>
+
+<h1><a shape="rect" name="JavaScript-HandlingSlowPageLoads"></a>Handling Slow
Page Loads</h1>
+
+<p>If your page loads slowly (typically, because of scripts loaded from
external sites), you may see a race condition where the user can click on a
link before an event handler for that link has been wired up.</p>
+
+<p>The client-side function <tt>Tapestry.waitForPage()</tt> can be used in an
element's onclick handler to force a wait for the page to fully load. In this
race condition, the screen will dim and a message will appear advising the user
to wait a moment; once the page is fully loaded, this modal dialog will be
removed.</p>
+
+<p>The correct usage is:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ <a href="..." onclick="javascript:Tapestry.waitForPage(event);"> ...
</a>
+]]></script>
+</div></div>
+
+<p>The constant <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupConstants.html";>MarkupConstants.WAIT_FOR_PAGE</a>
contains the part of this snippet inside the quotes.</p>
+
+<h1><a shape="rect" name="JavaScript-TheStandardTapestryLibrary"></a>The
Standard Tapestry Library</h1>
+
+<p>Tapestry's client-side support, the standard Tapestry library, consists of
<tt>tapestry.js</tt>, which has dependencies on Prototype and on Scriptaculous
Effects. tapestry.js, along with its dependencies. The tapestry.js library is
automatically added to the page when your code adds any other JavaScript or
JavaScript library.</p>
+
+<h2><a shape="rect" name="JavaScript-TapestryNamespace"></a>Tapestry
Namespace</h2>
+
+<p>Tapestry defines a number of object and classes inside the Tapestry
namespace.</p>
+
+<p>It also adds a handful of methods to the Form class, and to Form elements.
These are mostly related to input validation and determining element
visibility.</p>
+
+<h2><a shape="rect" name="JavaScript-TheTapestryObject%24T%28%29"></a>The
Tapestry Object $T()</h2>
+
+
+
+<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="/images/confluence/forbidden.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1"
rowspan="1"><b>Deprecated since 5.2 (no replacement)</b><br
clear="none"></td></tr></table></div>
+<div style="border-right: 20px solid #ffcccc;border-left: 20px solid
#ffcccc;"></div>
+
+<p>The standard library adds a new function, <tt>$T()</tt>. This function is
used much like Prototype's <tt>$()</tt>, except that instead of returning a DOM
object, it returns a hash (an initially empty JavaScript object) that is
associated with the DOM object. This hash is known as <em>the Tapestry
object</em>.</p>
+
+<p>You may pass in an object id (as a string) or an object reference. The
Tapestry Object is created on first invocation. Note: you'll see it as a
property name _tapestry on the DOM object (which may be useful when
debugging).</p>
+
+<p>When Tapestry adds information to a DOM object, it does so in the Tapestry
object. This helps avoid name conflicts, and groups all Tapestry-added
properties into one place which is much easier to debug.</p>
+
+<p>For example, you might store a value for an element in one place:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ $T(myid).fadeDuration = .5;
+]]></script>
+</div></div>
+
+<p>Then use it somewhere else:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ new Effect.Fade($(myId), { duration: $T(myid).fadeDuration });
+]]></script>
+</div></div>
+
+
+<h1><a shape="rect" name="JavaScript-AjaxComponentsandMixins"></a>Ajax
Components and Mixins</h1>
+
+<p>Tapestry provides easy-to-use support for <em>Ajax</em>, the technique of
using JavaScript to dynamically updating parts of a web page with content from
the server without redrawing the whole page. See <a shape="rect"
href="ajax-and-zones.html" title="Ajax and Zones">Ajax and Zones</a> for
details.</p>
+
+<h1><a shape="rect" name="JavaScript-BuiltinLibraries"></a>Built-in
Libraries</h1>
+
+<div class="navmenu" style="float:right; width:30%; background:#eee;
margin:3px; padding:3px"><p><font color="green"><b>Alternatives to
Prototype</b></font><br clear="none">
+Tapestry also works well with other JavaScript libraries, such as JQuery and
ExtJS:</p>
+<ul><li><b><a shape="rect" class="external-link"
href="https://github.com/got5/tapestry5-jquery"; >Tapestry5-Jquery
module</a></b> – Using JQuery <em>instead of</em> Prototype</li><li><a
shape="rect" class="external-link"
href="http://wiki.apache.org/tapestry/Tapestry5HowToIntegrateJQuery";>Tapestry5HowToIntegrateJQuery</a>
– Using JQuery <em>in addition to</em> Prototype</li><li><a shape="rect"
class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-999";>TAP5-999</a> tracks work
underway to introduce an agnostic tapestry.js layer to allow switching from
Prototype to JQuery. See <a shape="rect" href="javascript-rewrite.html"
title="JavaScript Rewrite">JavaScript Rewrite</a> for more info.</li><li><a
shape="rect" class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-1364";>TAPS-1364</a> lists some
starting points for ExtJS integration</li></ul>
+</div>
+
+<p>Tapestry comes with the <a shape="rect" class="external-link"
href="http://www.prototypejs.org/"; >Prototype</a> and <a shape="rect"
class="external-link" href="http://script.aculo.us/"; >Scriptaculous</a>
libraries ... no extra download is required. Tapestry will automatically link
into your pages the prototype.js, scriptaculous.js, and effects.js libraries,
as well as the Tapestry library, tapestry.js (which largely consists of support
for form input validation). Starting with Tapestry 5.3, <a shape="rect"
class="external-link" href="http://documentcloud.github.com/underscore/";
>Underscore</a> is also included.</p>
+
+<h2><a shape="rect"
name="JavaScript-PrototypeandScriptaculousVersions"></a>Prototype and
Scriptaculous Versions</h2>
+
+<div class="table-wrap">
+<table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"> Tapestry 5.3.5 </th><td colspan="1" rowspan="1"
class="confluenceTd"> Prototype 1.7.1 </td><td colspan="1" rowspan="1"
class="confluenceTd"> Scriptaculous 1.9 </td><td colspan="1" rowspan="1"
class="confluenceTd"> Underscore 1.1.7 </td></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"> Tapestry 5.3+ </th><td colspan="1"
rowspan="1" class="confluenceTd"> Prototype 1.7 </td><td colspan="1"
rowspan="1" class="confluenceTd"> Scriptaculous 1.9 </td><td colspan="1"
rowspan="1" class="confluenceTd"> Underscore 1.1.7 </td></tr><tr><th
colspan="1" rowspan="1" class="confluenceTh"> Tapestry 5.2.6 </th><td
colspan="1" rowspan="1" class="confluenceTd"> Prototype 1.7 </td><td
colspan="1" rowspan="1" class="confluenceTd"> Scriptaculous 1.9
</td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"> Tapestry 5.2
</th><td colspan="1" rowspan="1" class="confluenceTd"> Prototype 1.6.1 </td><td
cols
pan="1" rowspan="1" class="confluenceTd"> Scriptaculous 1.8.2
</td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"> Tapestry 5.1
</th><td colspan="1" rowspan="1" class="confluenceTd"> Prototype 1.6.0.3
</td><td colspan="1" rowspan="1" class="confluenceTd"> Scriptaculous 1.8.2
</td></tr><tr><th colspan="1" rowspan="1" class="confluenceTh"> Tapestry 5.0
</th><td colspan="1" rowspan="1" class="confluenceTd"> Prototype 1.6.0 </td><td
colspan="1" rowspan="1" class="confluenceTd"> Scriptaculous 1.8.0
</td></tr></tbody></table>
+</div>
+
+
+<p>Tapestry uses a modified version of the main Scriptaculous library,
scriptaculous.js, with the library's default <a shape="rect"
class="external-link"
href="http://wiki.script.aculo.us/scriptaculous/show/Usage"; >autoloading</a>
behavior turned off. This lets Tapestry and Tapestry components control which
Scriptaculus scripts are loaded, rather than having <em>all</em> of them loaded
unnecessarily.</p>
+
+<p>If you need access to other Scriptaculous libraries, you can provide them
as follows:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Inject @Path("${tapestry.scriptaculous}/dragdrop.js")
+ private Asset dragDropLibrary;
+
+ @Environmental
+ private JavaScriptSupport javaScriptSupport;
+
+ void setupRender()
+ {
+ javaScriptSupport.addScriptLink(dragDropLibrary);
+ }
+
+]]></script>
+</div></div>
+
+<p>The Asset is injected, using the ${tapestry.scriptaculous} <a shape="rect"
href="symbols.html" title="Symbols">symbol</a> to reference the location of the
Scriptaculous library.</p>
+
+<p>Even though the dragdrop.js library is stored inside a JAR file, Tapestry
ensures that it can be accessed from the client web browser. A Tapestry URL
within the virtual folder "/assets" is created; the file will be given a
version number (the application version number if not specified more
specifically) and will be sent to the browser with a far-future expires header
(to encourage the browser to cache the file aggressively).</p>
+
+<h1><a shape="rect" name="JavaScript-JavaScriptStacks"></a>JavaScript
Stacks</h1>
+
+
+<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="/images/confluence/information.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1"
rowspan="1"><b>Added in 5.2</b><br clear="none"></td></tr></table></div>
+<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid
#D8E4F1;"></div>
+
+<p>Tapestry allows you to define groups of related JavaScript libraries and
stylesheets as "stacks". The built-in "core" stack is used to define the core
JavaScript libraries needed by Tapestry (currently, this includes Prototype and
Scriptaculous, as well as Tapestry-specific libraries). Other component
libraries may define additional stacks for related sets of resources, for
example, to bundle together some portion of the ExtJS or YUI libraries.</p>
+
+<p>A <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptStack.html";>JavaScriptStack</a>
can be thought of as a generalization of Tapestry 5.1's ClientInfrastructure,
which exists now to define the "core" JavaScript stack.</p>
+
+<p>JavaScript assets of a stack may (when enabled) be exposed to the client as
a single URL (identifying the stack by name). The individual assets are
combined into a single virtual asset, which is then streamed to the client.</p>
+
+
+<p>To group several static resources together in a single stack, you must
create a new implementation of the JavaScriptStack interface . This interface
has four methods:</p>
+
+<ul class="alternate" type="square"><li><b>getStylesheets</b> : This method
will return a list of stylesheet files (StylesheetLink-type object)
associated to this stack</li></ul>
+
+
+<ul class="alternate" type="square"><li><b>getJavaScriptLibraries</b> : This
method will return a list of javascript files (Asset-type object) associated
to this stack</li></ul>
+
+
+<ul class="alternate" type="square"><li><b>getStacks</b> : It is also possible
to make a stack dependant of other stacks. All the stacks defined in this
method will be loaded before the current stack.</li></ul>
+
+
+<ul class="alternate" type="square"><li><b>getInitialization</b> : this method
makes it possible to call a JavaScript initialization for the stack. Tapestry
will automatically add this initialization to the page that imports the
stacks.</li></ul>
+
+
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>myStack.java</b></div><div
class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+public class myStack implements JavaScriptStack {
+
+ private final AssetSource assetSource;
+
+ public myStack (final AssetSource assetSource)
+ {
+ this.assetSource = assetSource;
+ }
+
+ public String getInitialization()
+ {
+ return null;
+ }
+
+
+
+ public List<Asset> getJavaScriptLibraries()
+ {
+ List<Asset> ret = new ArrayList<Asset>();
+
+ ret.add(assetSource.getContextAsset("static/js/jquery.js", null));
+
+ ret.add(assetSource.getContextAsset("static/js/jquery.ui.core.js",
null));
+
+ return ret;
+ }
+
+ public List<StylesheetLink> getStylesheets()
+ {
+ List<StylesheetLink> ret = new ArrayList<StylesheetLink>();
+
+ ret.add(new
StylesheetLink(assetSource.getContextAsset("static/css/style.css", null)));
+
+ return ret;
+ }
+
+ public List<String> getStacks()
+ {
+ return Collections.emptyList();
+ }
+
+}
+]]></script>
+</div></div>
+
+<p>When your new Stack is created, you have to define it in your AppModule.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>AppModule.java</b></div><div
class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+@Contribute(JavaScriptStackSource.class)
+public static void addMyStack (MappedConfiguration<String,
JavaScriptStack> configuration)
+{
+ configuration.addInstance("MyNewStack", myStack.class);
+}
+]]></script>
+</div></div>
+
+<p>You can now use it in your pages and components, by using the @Import
annotation or the JavaScriptSupport service :</p>
+
+<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0"
width="100%"><tbody><tr><td colspan="1" rowspan="1" valign="top"
class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>With @Import</b></div><div
class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+ @Import(stack="MyNewStack")
+ public class myPage {
+ }
+]]></script>
+</div></div></td><td colspan="1" rowspan="1" valign="top" class="confluenceTd">
+<div class="code panel" style="border-width: 1px;"><div class="codeHeader
panelHeader" style="border-bottom-width: 1px;"><b>With
JavaScriptSupport</b></div><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
+@Inject
+private JavaScriptSupport js;
+
+@SetupRender
+public void importStack(){
+ js.importStack("MyNewStack");
+}
+]]></script>
+</div></div></td></tr></tbody></table></div>
+</div>
+
+<div class="clearer"></div>
+<div id="footer">
+<div id="footer"><p>Apache Tapestry, Tapestry, Apache, the Apache feather
logo, and the Apache Tapestry project logo are trademarks of The Apache
Software Foundation.<br clear="none">
+<script type="text/javascript">
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-400821-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript';
ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
+ })();
+</script></p></div>
+</div>
+ <div id="comments_thread"></div>
+ <script type="text/javascript"
src="https://comments.apache.org/show_comments.lua?site=tapestry&page=http://tapestry.apache.org/javascript.html";
async="true">
+ </script>
+ <noscript>
+ <iframe width="100%" height="500"
src="https://comments.apache.org/iframe.lua?site=tapestry&page=http://tapestry.apache.org/javascript.html";></iframe>
+ </noscript>
+ </div>
+</body>
+</html>
