You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by ta...@apache.org on 2010/06/03 18:43:54 UTC
svn commit: r951063 [5/11] - in
/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide:
./ css/ images/ images/best-practices/ images/callouts/ images/colorsvg/
images/configuration/ images/controls/ images/introduction/ images/pa...
Added: click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s02.html
URL: http://svn.apache.org/viewvc/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s02.html?rev=951063&view=auto
==============================================================================
--- click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s02.html (added)
+++ click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s02.html Thu Jun 3 16:43:50 2010
@@ -0,0 +1,467 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>4.2. Application Configuration</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.0"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch04.html" title="Chapter 4. Configuration"><link rel="prev" href="ch04.html" title="Chapter 4. Configuration"><link rel="next" href="ch04s03.html" title="4.3. Auto Deployed Files"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.2. Application Configuration</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuration</th><td width="20%" align="right"> <a accesskey="n" href="ch04s03.html">Next</a></td></tr></table><hr></div><div class="sect1"
title="4.2. Application Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="application-configuration"></a>4.2. Application Configuration</h2></div></div></div><p> The heart of a Click application is the <code class="filename">click.xml</code>
+ configuration file. This file specifies the application pages, headers, the
+ format object and the applications mode.
+ </p><p>By default the ClickServlet will attempt to load the application
+ configuration file using the path: <code class="filename">/WEB-INF/click.xml</code>
+ </p><p>If this file is not found under the <code class="literal">WEB-INF</code> directory,
+ then ClickServlet will attempt to load it from the classpath as
+ <code class="filename">/click.xml</code>.
+ </p><p>See <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-dtd.html" target="_blank">Click DTD</a> for the click-app
+ XML definition.
+ </p><p>A complete Click configuration example is available
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-dtd-example.html" target="_blank">here</a> which can be used as a quick
+ reference when configuring Click.
+ </p><p>A basic Click app config file is provided below:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com"><!-- Specify the Java package where Page classes can be found --></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><mode</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"profile"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>An advanced config file would look like this:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">charset</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"UTF-8"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">locale</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"de"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com"><!-- Specify the Java package where Page classes can be found --></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.banking.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"index.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Home"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com"><!-- Specify a second Java package where Page classes can be found --></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.common.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><format</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.util.Format"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><mode</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"profile"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><log-service</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"org.apache.click.extras.service.Log4JLogService"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>The take away point is that there is not much to configure, even for
+ advanced uses.
+ </p><div class="sect2" title="4.2.1. Click App"><div class="titlepage"><div><div><h3 class="title"><a name="click-app"></a>4.2.1. Click App</h3></div></div></div><p>The root <span class="symbol">click-app</span> element defines two application
+ localization attributes <code class="varname">charset</code> and <code class="varname">locale</code>.
+ </p><div class="literallayout"><p><!ELEMENT <span class="symbol">click-app</span> (pages*, headers?, format?, mode?, controls?,<br>
+ file-upload-service?, log-service?, template-service?)><br>
+ <!ATTLIST click-app <code class="varname">charset</code> CDATA #IMPLIED><br>
+ <!ATTLIST click-app <code class="varname">locale</code> CDATA #IMPLIED></p></div><p>The <code class="varname">charset</code> attribute defines the character encoding
+ set for:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Velocity templates</p></li><li class="listitem"><p>HttpServletRequest character encoding</p></li><li class="listitem"><p>Page Content-Type charset, see Page
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Page.html#getContentType()" target="_blank">getContentType()</a>
+ </p></li></ul></div><p>The <code class="varname">locale</code> attribute defines the default application
+ Locale. If this value is defined it will override Locale returned by the request.
+ Please see the Context
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Context.html#getLocale()" target="_blank">getLocale()</a>
+ for details. For example the following configuration sets the application
+ character set to UTF-8 and the default Locale as German (de):
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">charset</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">" UTF-8"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">locale</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"de"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ ..
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre></div><div class="sect2" title="4.2.2. Pages"><div class="titlepage"><div><div><h3 class="title"><a name="application-pages"></a>4.2.2. Pages</h3></div></div></div><p>The first child element of the click-app is the mandatory
+ <code class="literal">pages</code> element which defines the list of Click pages.
+ </p><div class="literallayout"><p><!ELEMENT <code class="varname">pages</code> (<span class="symbol">page</span>*)><br>
+ <!ATTLIST pages <code class="varname">package</code> CDATA #IMPLIED><br>
+ <!ATTLIST pages <code class="varname">automapping</code> (true|false) "true"><br>
+ <!ATTLIST pages <code class="varname">autobinding</code> (default|annotation|none) "default"></p></div><p>The pages element can specify a default <code class="varname">package</code> name
+ which is prepended to the classname of any pages defined.
+ </p><p>The pages element also defines the <code class="varname">automapping</code> and
+ <code class="varname">automapping</code> attributes which is discussed in the
+ <a class="link" href="ch04s02.html#application-automapping" title="4.2.3.1. Page Automapping">Page Automapping</a> and
+ <a class="link" href="ch04s02.html#application-autobinding" title="4.2.3.3. Page Autobinding">Page Autobinding</a> sections
+ respectively.
+ </p><div class="sect3" title="4.2.2.1. Multiple Pages Packages"><div class="titlepage"><div><div><h4 class="title"><a name="application-multiple-packages"></a>4.2.2.1. Multiple Pages Packages</h4></div></div></div><p>Click can support multiple pages elements to enable the automapping
+ of multiple packages.
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.banking.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.common.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>With multiple pages elements, pages are loaded in the order of the page
+ elements, with manual page elements being loaded before automapped pages.
+ Once a page template has been mapped to a Page class it will not be replaced
+ by a subsequent potential match. So pages elements at the top take priority
+ over lower pages elements.
+ </p></div></div><div class="sect2" title="4.2.3. Page"><div class="titlepage"><div><div><h3 class="title"><a name="application-page"></a>4.2.3. Page</h3></div></div></div><p>The page element defines the Click application pages.
+ </p><div class="literallayout"><p><!ELEMENT <span class="symbol">page</span>(<code class="varname">header</code>*)><br>
+ <!ATTLIST page <code class="varname">path</code> CDATA #REQUIRED><br>
+ <!ATTLIST page <code class="varname">classname</code> CDATA #REQUIRED></p></div><p>Each page <code class="varname">path</code> must be unique, as the Click
+ application maps HTTP requests to the page paths.
+ </p><p>The Click application will create a new Page instance for
+ the given request using the configured page <code class="varname">classname</code>.
+ All pages must subclass
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Page.html" target="_blank">Page</a> and provide
+ a public no arguments constructor, so they can be instantiated.
+ </p><p>Pages can also define <code class="varname">header</code> values which are
+ discussed in the next topic.
+ </p><p>When the Click application starts up it will check all the page
+ definitions. If there is a critical configuration error the ClickSerlvet
+ will log an <code class="literal">ERROR</code> message and throw an
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/UnavailableException.html" target="_blank">UnavailableException</a>.
+ If this occurs the click application will be permanently unavailable until
+ the error is fixed and the web app is restarted.
+ </p><div class="sect3" title="4.2.3.1. Page Automapping"><div class="titlepage"><div><div><h4 class="title"><a name="application-automapping"></a>4.2.3.1. Page Automapping</h4></div></div></div><p> Page automapping will automatically configure application pages
+ using a simple set of rules. This enables you to greatly streamline your
+ configuration file as you only need to define pages which don't fit
+ the automapping rules.
+ </p><p>Automapping will attempt to associate each page template (*.htm)
+ and JSP file in the web application (excluding those under the WEB-INF
+ and click directories) to a Page class. Automapped pages are loaded after
+ the manually defined pages are loaded, and manually defined pages takes
+ preference. When automapping is enabled the Click application will log
+ the page mappings when in debug or trace mode.
+ </p><p>For example, given the following page path to class mapping:
+ </p><div class="literallayout"><p>index.htm => <span class="token">com.mycorp.page.Home</span><br>
+search.htm => <span class="token">com.mycorp.page.Search</span><br>
+contacts/contacts.htm => <span class="token">com.mycorp.page.contacts.Contacts</span><br>
+security/login.htm => <span class="token">com.mycorp.page.security.Login</span><br>
+security/logout.htm => <span class="token">com.mycorp.page.security.Logout</span><br>
+security/change-password.htm => <span class="token">com.mycorp.page.security.ChangePassword</span></p></div><p>The above mapping could be configured manually by setting the
+ <span class="symbol">automapping</span> attribute to "false" and using the package
+ prefix, for example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">com.mycorp.page</span>" <span class="symbol">automapping</span>="false">
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"index.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">Home</span>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"search.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">Search</span>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"contacts/contacts.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">contacts.Contacts</span>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"security/login.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">security.Login</span>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"security/logout.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">security.Logout</span>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"security/change-password.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">security.ChangePassword</span>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>By using <span class="symbol">automapping</span> the page paths will automatically
+ map to page classes: (except for Home page which doesn't automatically map
+ to index.html)
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><span class="token">com.mycorp.page</span>" <span class="symbol">automapping</span>="true">
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"index.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Home"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>Note <span class="symbol">automapping</span> is true by default, so it could be
+ omitted from the configuration file.
+ </p><p>The page template name to classname convention is:
+ </p><div class="literallayout"><p>change-password.htm => <span class="token">ChangePassword</span><br>
+change_password.htm => <span class="token">ChangePassword</span><br>
+changePassword.htm => <span class="token">ChangePassword</span><br>
+ChangePassword.htm => <span class="token">ChangePassword</span></p></div><p>When automapping pages, if a class cannot be found Click will attempt
+ to add the 'Page' suffix to the classname if not already present and map
+ this. For example:
+ </p><div class="literallayout"><p>customer.htm => <span class="token">CustomerPage</span><br>
+change-password.htm => <span class="token">ChangePasswordPage</span></p></div></div><div class="sect3" title="4.2.3.2. Automapping Excludes"><div class="titlepage"><div><div><h4 class="title"><a name="application-excludes"></a>4.2.3.2. Automapping Excludes</h4></div></div></div><p>With Page automapping there can be resources where you don't want
+ automapping applied. For example when using a JavaScript library with lots
+ of <code class="literal">.htm</code> files, you don't want automapping to try and
+ find Page class for each of these files. In these situations you can use
+ the pages <span class="symbol">excludes</span> element.
+ </p><div class="literallayout"><p><!ELEMENT <span class="symbol">excludes</span> (#PCDATA)><br>
+ <!ATTLIST excludes <code class="varname">pattern</code> CDATA #REQUIRED></p></div><p>For example if our application uses the TinyMCE JavaScript library
+ we could configure our pages automapping to exclude all <code class="literal">.htm</code>
+ files under the <code class="literal">/tiny_mce</code> directory.
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span class="symbol"><excludes</span> pattern="<code class="varname">/tiny_mce/*</code>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>The excludes pattern can specify multiple directories or files using a
+ comma separated notation. For example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span class="symbol"><excludes</span> pattern="<code class="varname">/dhtml/*, /tiny_mce/*, banner.htm, about.htm</code>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>HTM files excluded from Page automapping are handled by an internal
+ Page class with caching headers enabled.
+ </p></div><div class="sect3" title="4.2.3.3. Page Autobinding"><div class="titlepage"><div><div><h4 class="title"><a name="application-autobinding"></a>4.2.3.3. Page Autobinding</h4></div></div></div><p>Autobinding is a feature that allows certain page fields to be
+ handled in a special way by the ClickServlet. The autobinding attribute
+ can be configured with one of the following values:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> <code class="varname">default</code>: <code class="literal">bindable</code>
+ fields include both <code class="varname">public</code> page fields and fields
+ annotated with the
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/Bindable.html" target="_blank">@Bindable</a>
+ annotation
+ </p></li><li class="listitem"><p> <code class="varname">annotation</code>: <code class="literal">bindable</code>
+ fields are fields annotated with the
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/Bindable.html" target="_blank">@Bindable</a>
+ annotation
+ </p></li><li class="listitem"><p> <code class="varname">none</code>: disables the autobinding feature
+ </p></li></ul></div><p>
+ </p><p>By default all pages have autobinding enabled in
+ <code class="varname">default</code> mode. With autobinding the ClickServlet will
+ automatically:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> add any <code class="literal">bindable</code> controls to the page,
+ after the page constructor has been invoked
+ </p></li><li class="listitem"><p> if the <code class="literal">bindable</code> control name is not defined,
+ its name will be set to the value of its field name
+ </p></li><li class="listitem"><p> bind any request parameters to <code class="literal">bindable</code>
+ page fields, after page constructor has been invoked. See
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/ClickServlet.html#processPageRequestParams(org.apache.click.Page)" target="_blank">ClickServlet.processPageRequestParams(Page)</a>
+ for more details
+ </p></li><li class="listitem"><p> add all <code class="literal">bindable</code> page fields to the page
+ model (this step occurs right before the page is rendered)</p></li></ul></div><p>For example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> EmployeePage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page {
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> Form employeeForm = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Form();
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> Table myTable = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Table();
+
+}</pre><p>Note in the above example that the <code class="varname">employeeForm</code>
+ and <code class="varname">myTable</code> controls were not added to the page. Also
+ note that Form and Table do not have their names defined.
+ </p><p>When autobinding is enabled, ClickServlet will create a new Page
+ and add the public controls to the page. Following the example above the
+ <code class="varname">employeeForm</code> and <code class="varname">myTable</code> will be
+ added to the page, similar to calling
+ <code class="methodname">addControl(employeeForm)</code> and
+ <code class="methodname">addControl(myTable)</code>.
+ </p><p>Furthermore, the control names were not defined so ClickServlet
+ will set their names to the value of their field/variable name. In this
+ case the Form name will be set to <code class="varname">employeeForm</code> while
+ the Table name will set to <code class="varname">myTable</code>.
+ </p><p>The above example is thus a shorthand way of writing the following:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> EmployeePage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page {
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">private</span> Form employeeForm = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Form();
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">private</span> Table myTable = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Table();
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">void</span> onInit() {
+ employeeForm.setName(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"employeeForm"</span>);
+ addControl(employeeForm);
+
+ myTable.setName(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"myTable"</span>);
+ addControl(myTable);
+ }
+}</pre><p>You can turn this behaviour off by setting the <span class="symbol">autobinding</span>
+ attribute to <code class="varname">none</code> for example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span> <span class="symbol">autobinding</span>="<code class="varname">none</code>"/>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre></div><div class="sect3" title="4.2.3.4. Page Autobinding - Using Annotations"><div class="titlepage"><div><div><h4 class="title"><a name="application-autobinding-annotation"></a>4.2.3.4. Page Autobinding - Using Annotations</h4></div></div></div><p>Click provides the
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/Bindable.html" target="_blank">Bindable</a>
+ annotation which enables autobinding of Page fields. The Bindable
+ annotation can bind <code class="varname">private</code>, <code class="varname">protected</code>
+ and <code class="varname">public</code> Page fields.
+ </p><p>By default, Click's autobinding feature operates on both
+ <span class="symbol">public</span> and <span class="symbol">@Bindable</span> fields.
+ To instruct Click to operate only on <span class="symbol">@Bindable</span>
+ annotated fields, you can set the <span class="symbol">autobinding</span>
+ attribute to <code class="varname">annotation</code>, for example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span> <span class="symbol">autobinding</span>="<code class="varname">annotation</code>"/>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>Click won't autobind <code class="literal">public</code> fields anymore.
+ </p><p>Below is an example using the <span class="symbol">@Bindable</span>
+ annotation:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> EmployeePage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page {
+
+ <span class="symbol">@Bindable</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">protected</span> Form employeeForm = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Form();
+
+ <span class="symbol">@Bindable</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">protected</span> Table myTable = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Table();
+
+}</pre></div></div><div class="sect2" title="4.2.4. Headers"><div class="titlepage"><div><div><h3 class="title"><a name="application-headers"></a>4.2.4. Headers</h3></div></div></div><p>The optional <code class="literal">headers</code> element defines a list of
+ <code class="literal">header</code> elements which are applied to all pages.
+ </p><div class="literallayout"><p><!ELEMENT <code class="varname">headers</code> (<span class="symbol">header</span>*)></p></div><p>The <span class="symbol">header</span> element defines header name and value
+ pairs which are applied to the
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/http/HttpServletResponse.html" target="_blank">HttpServletResponse</a>.
+ </p><div class="literallayout"><p><!ELEMENT <span class="symbol">header</span> (#PCDATA)><br>
+ <!ATTLIST header <code class="varname">name</code> CDATA #REQUIRED><br>
+ <!ATTLIST header <code class="varname">value</code> CDATA #REQUIRED><br>
+ <!ATTLIST header <code class="varname">type</code> (String|Integer|Date) "String"></p></div><p>Page headers are set after the Page has been constructed and before
+ <code class="methodname">onInit()</code> is called. Pages can then modify their
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Page.html#headers" target="_blank">headers</a>
+ property using the
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Page.html#setHeader(java.lang.String,%20java.lang.Object)" target="_blank">setHeader()</a>
+ method.
+ </p><div class="sect3" title="4.2.4.1. Browser Caching"><div class="titlepage"><div><div><h4 class="title"><a name="browser-caching"></a>4.2.4.1. Browser Caching</h4></div></div></div><p>Headers are typically used to switch off browser caching. By
+ default Click will use the following no caching header values if you don't
+ define a <code class="literal">headers</code> element in your application:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages></span>
+ ..
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><headers></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Pragma"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"no-cache"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Cache-Control"</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"no-store, no-cache, must-revalidate, post-check=0, pre-check=0"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Expires"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"1"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Date"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></headers></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>Alternatively you can define your headers individually in pages or
+ for all application pages by setting header values. For example to switch
+ off caching in the login page, note the value for a Date type should
+ be a long number value:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"login.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Login"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Pragma"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"no-cache"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Expires"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"1"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Date"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></page></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span></pre><p>If you wanted to enable caching for a particular page you could set
+ the following page cache control header. This will mark the page as cachable
+ for a period of 1 hour after which it should be reloaded.
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"home.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Home"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Cache-Control"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"max-age=3600, public, must-revalidate"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></page></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span></pre><p>To apply header values globally define header values in the headers
+ element. For example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><pages></span>
+ ..
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></pages></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><headers></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Pragma"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"no-cache"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Cache-Control"</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"no-store, no-cache, must-revalidate, post-check=0, pre-check=0"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><header</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Expires"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">value</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"1"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Date"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></headers></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre></div></div><div class="sect2" title="4.2.5. Format"><div class="titlepage"><div><div><h3 class="title"><a name="application-format"></a>4.2.5. Format</h3></div></div></div><p>The optional <code class="literal">format</code> element defines the Format
+ object classname which is applied to all pages.
+ </p><div class="literallayout"><p><!ELEMENT <span class="symbol">format</span> (#PCDATA)><br>
+ <ATTLIST format <code class="varname">classname</code> CDATA #FIXED "org.apache.click.util.Format"></p></div><p>By default all Click pages are configured with a
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/Format.html" target="_blank">org.apache.click.util.Format</a>
+ object. The format object is made available in the Velocity page templates
+ using the name <code class="varname">$format</code>.
+ </p><p>To specify a custom format class configure a <code class="literal">format</code>
+ element in the click-app descriptor. For example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ ..
+ <span class="symbol"><format</span> classname="<code class="varname">com.mycorp.util.CustomFormat</code>"/>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre></div><div class="sect2" title="4.2.6. Mode"><div class="titlepage"><div><div><h3 class="title"><a name="application-mode"></a>4.2.6. Mode</h3></div></div></div><p>The optional <code class="literal">mode</code> element defines the application
+ logging and caching mode.
+ </p><div class="literallayout"><p><!ELEMENT <span class="symbol">mode</span> (#PCDATA)><br>
+ <ATTLIST mode value (<code class="varname">production|profile|development|debug|trace</code>) "development"></p></div><p>By default Click applications run in <code class="literal">development</code> mode,
+ which switches off page template caching, and the logging level is set to
+ <code class="literal">INFO</code>.
+ </p><p>To change the default application mode configure a mode element in the
+ click-app descriptor. For example to specify <code class="literal">production</code>
+ mode you would add the following mode element:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ ..
+ <span class="symbol"><mode</span> value="<code class="varname">production</code>">
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre><p>The application mode configuration can be overridden by setting the
+ system property <code class="literal">"click.mode"</code>. This can be use in the scenario
+ of debugging a problem on a production system, where you change the mode to
+ <code class="literal">trace</code> by setting the following system property and
+ restarting the application.
+ </p><div class="literallayout"><p>-Dclick.mode=trace</p></div><p>The Click Application modes and their settings for Page auto loading,
+ template caching and logging levels are:
+ </p><div class="informaltable"><table style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col><col><col><col><col></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
+ <p>
+ Application mode
+ </p>
+ </th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
+ <p>
+ Page auto loading
+ </p>
+ </th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
+ <p>
+ Template caching
+ </p>
+ </th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
+ <p>
+ Click log level
+ </p>
+ </th><th style="border-bottom: 0.5pt solid ; ">
+ <p>
+ Velocity log level
+ </p>
+ </th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>
+ <span class="bold"><strong>production</strong></span>
+ </p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>No</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>Yes</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>WARN</p>
+ </td><td style="border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>ERROR</p>
+ </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>
+ <span class="bold"><strong>profile</strong></span>
+ </p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>No</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>Yes</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>INFO</p>
+ </td><td style="border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>ERROR</p>
+ </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>
+ <span class="bold"><strong>development</strong></span>
+ </p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>Yes</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>No</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>INFO</p>
+ </td><td style="border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>ERROR</p>
+ </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>
+ <span class="bold"><strong>debug</strong></span>
+ </p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>Yes</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>No</p>
+ </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>DEBUG</p>
+ </td><td style="border-bottom: 0.5pt solid ; " align="center" valign="middle">
+ <p>ERROR</p>
+ </td></tr><tr><td style="border-right: 0.5pt solid ; " align="center" valign="middle">
+ <p>
+ <span class="bold"><strong>trace</strong></span>
+ </p>
+ </td><td style="border-right: 0.5pt solid ; " align="center" valign="middle">
+ <p>Yes</p>
+ </td><td style="border-right: 0.5pt solid ; " align="center" valign="middle">
+ <p>No</p>
+ </td><td style="border-right: 0.5pt solid ; " align="center" valign="middle">
+ <p>TRACE</p>
+ </td><td style="" align="center" valign="middle">
+ <p>WARN</p>
+ </td></tr></tbody></table></div><div class="sect3" title="4.2.6.1. Page Auto Loading"><div class="titlepage"><div><div><h4 class="title"><a name="page-auto-loading"></a>4.2.6.1. Page Auto Loading</h4></div></div></div><p>When Page Auto Loading is enabled any new page templates and classes
+ will be automatically loaded at runtime. These pages are loaded using the
+ <a class="link" href="ch04s02.html#application-automapping" title="4.2.3.1. Page Automapping">Page Automapping</a> rules.
+ </p><p>Page auto loading is a very handy feature for rapid development as
+ you do not have to restart you application server to pick up new pages.
+ </p></div><div class="sect3" title="4.2.6.2. Click and Velocity Logging"><div class="titlepage"><div><div><h4 class="title"><a name="click-logging"></a>4.2.6.2. Click and Velocity Logging</h4></div></div></div><p>The Click and Velocity runtimes use
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/service/LogService.html" target="_blank">LogService</a>
+ for logging messages. The default LogService implementation is
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/service/ConsoleLogService.html" target="_blank">ConsoleLogService</a>
+ which will send messages to the console [System.out]. For example the
+ following logging output is for a HomePage request when the application
+ mode is <code class="literal">trace</code>:
+ </p><div class="literallayout"><p>[Click] [debug] GET http://localhost:8080/quickstart/home.htm<br>
+[Click] [trace] invoked: HomePage.<<init>><br>
+[Click] [trace] invoked: HomePage.onSecurityCheck() : true<br>
+[Click] [trace] invoked: HomePage.onInit()<br>
+[Click] [trace] invoked: HomePage.onGet()<br>
+[Click] [trace] invoked: HomePage.onRender()<br>
+[Click] [info ] renderTemplate: /home.htm - 6 ms<br>
+[Click] [trace] invoked: HomePage.onDestroy()<br>
+[Click] [info ] handleRequest: /home.htm - 24 ms</p></div><p>Any unhandled <code class="literal">Throwable</code> errors are logged by the
+ ClickServlet.
+ </p><p>Note that Click Extras also provide log adaptors for
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/service/Log4JLogService.html" target="_blank">Log4J</a>
+ and the <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/service/JdkLogService.html" target="_blank">JDK Logging API</a>.
+ </p><p>When an application is not in <code class="literal">production</code> mode the
+ error page displays detailed debugging information. When the application
+ mode is <code class="literal">production</code> no debug information is displayed to
+ prevent sensitive information being revealed. This behaviour can be changed
+ by modifying the deployed <code class="filename">click/error.htm</code> page template.
+ </p></div></div><div class="sect2" title="4.2.7. Controls"><div class="titlepage"><div><div><h3 class="title"><a name="application-controls"></a>4.2.7. Controls</h3></div></div></div><p>The optional <code class="literal">controls</code> element defines a list of
+ <code class="literal">control</code> elements which will be deployed on application
+ startup.
+ </p><div class="literallayout"><p><!ELEMENT <code class="varname">controls</code> (<span class="symbol">control</span>*)></p></div><p>The <span class="symbol">control</span> registers
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Control.html" target="_blank">Control</a> classes
+ which will have their <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)" target="_blank">onDeploy()</a>
+ method invoked when the click application starts.
+ </p><div class="literallayout"><p><!ELEMENT <span class="symbol">control</span> (#PCDATA)><br>
+ <!ATTLIST control <code class="varname">classname</code> CDATA #REQUIRED></p></div><p>For example to have a <code class="classname">CustomField</code> control
+ deploy its resources on application startup, you would add the following
+ elements to your <code class="filename">click.xml</code> file:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><click-app></span>
+ ..
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><controls></span>
+ <span class="symbol"><control</span> classname="<code class="varname">com.mycorp.control.CustomField</code>"/>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></controls></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></click-app></span></pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.3. Auto Deployed Files</td></tr></table></div></body></html>
\ No newline at end of file
Propchange: click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s02.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s03.html
URL: http://svn.apache.org/viewvc/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s03.html?rev=951063&view=auto
==============================================================================
--- click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s03.html (added)
+++ click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s03.html Thu Jun 3 16:43:50 2010
@@ -0,0 +1,179 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>4.3. Auto Deployed Files</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.0"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch04.html" title="Chapter 4. Configuration"><link rel="prev" href="ch04s02.html" title="4.2. Application Configuration"><link rel="next" href="ch05.html" title="Chapter 5. Best Practices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.3. Auto Deployed Files</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s02.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuration</th><td width="20%" align="right"> <a accesskey="n" href="ch05.html">Next</a></td></tr></table><hr></div><div class="sect1" titl
e="4.3. Auto Deployed Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="auto-deployed-files"></a>4.3. Auto Deployed Files</h2></div></div></div><p>To make pre-configured resources (templates, stylesheets, etc.)
+ available to web applications, Click automatically deploys configured
+ classpath resources to the <code class="varname">/click</code> directory at startup
+ (if not already present).
+ </p><p>You can modify these support files and Click will
+ <span class="bold"><strong>not</strong></span> overwrite them. These files include:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> click/error.htm - the Page
+ <a class="link" href="ch02s09.html" title="2.9. Error Handling">Error Handling</a> template
+ </p></li><li class="listitem"><p> click/control.css - the Controls cascading stylesheet</p></li><li class="listitem"><p> click/control.js - the Controls JavaScript library</p></li><li class="listitem"><p> click/not-found.htm - the
+ <a class="link" href="ch02s10.html" title="2.10. Page Not Found">Page Not Found</a> template
+ </p></li></ul></div><p>For example to customize the control styles you can place a customized
+ copy (or even a brand new version) of <code class="filename">control.css</code> under
+ the <code class="varname">/click</code> folder in your web project:
+ </p><div class="literallayout"><p>/webapp/click/control.css</p></div><p>When Click starts up it will <span class="bold"><strong>not</strong></span>
+ override your copy of <code class="filename">control.css</code> with its own default
+ version.
+ </p><p>Different controls might deploy different stylesheet, javascript or image
+ files, however the above principle still applies. By placing a customized copy
+ of the stylesheet, javascript or image under the <code class="varname">/click</code> folder,
+ you will override the default resource.
+ </p><p>Be aware that some of the more complex controls (checklist, colorpicker,
+ tree), deploys resources to subfolders under <code class="varname">/click</code>, for
+ example <code class="literal">/click/checklist/*</code>.
+ </p><p>A control's Javadoc will normally indicate what resources are deployed
+ for that control.
+ </p><div class="sect2" title="4.3.1. Deploying resources in a restricted environment"><div class="titlepage"><div><div><h3 class="title"><a name="deploying-restricted-env"></a>4.3.1. Deploying resources in a restricted environment</h3></div></div></div><p>Some environments place restrictions on the file system and
+ Click won't be able to deploy its resources. WebLogic and
+ Google App Engine are examples of such environments. (Note that WebLogic has
+ a property to allow access to the file system. From the Admin Console go
+ to the <span class="emphasis"><em>Server node > Web Applications</em></span>
+ tab and check the <span class="emphasis"><em>Archived Real Path Enabled</em></span> parameter.)
+ </p><p>If Click cannot deploy its resources because of limited file system
+ access or permissions, warning messages will be logged.
+ </p><p><span class="bold"><strong>Note: </strong></span>if your application is
+ running on a <span class="emphasis"><em>Servlet 3.0</em></span> compliant server, there is
+ no need to deploy resources. Servlet 3.0 specifies that if the server
+ cannot find a resource in the root directory of the webapp, it will look
+ for the resource under <span class="emphasis"><em>'META-INF/resources'</em></span>, and if
+ found, serve it up. Click is Servlet 3.0 compliant and packages its
+ resources under <span class="emphasis"><em>'META-INF/resources'</em></span>.
+ </p><p>Click provides a number of options to make resources available
+ in restricted environments which is covered below:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The first option (which will work in all environments) is to deploy
+ the resources at build time. Click ships with an Ant Task
+ called DeployTask that deploys Click static resources to a web
+ application. With this option Click's static resources can be copied
+ to the root directory of your webapp, where you can customize the
+ resources further if needed. The DeployTask can easily be incorporated
+ into your build script.
+ </p><p>Currently the DeployTask is part of the <code class="filename">click-dev-tools-xxx.jar</code>
+ that can be found in your Click distribution under the <span class="emphasis"><em>lib</em></span>
+ folder.
+ </p><p>Here is a basic example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><target</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"deploy"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">description</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Deploy static resources"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><taskdef</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"deploy"</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"org.apache.click.tools.deploy.DeployTask"</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classpath</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"<click-distribution>/lib/click-dev-tasks-1.1.jar"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span> <a class="co" name="co-click-distribution" href="ch04s03.html#ca-click-distribution"><img src="images/callouts/1.gif" alt="1" border="0"></a>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><deploy</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">dir</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"<webapp-root>/WEB-INF"</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">todir</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"<webapp-root>"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span> <a class="co" name="co-webapp-root" href="ch04s03.html#ca-webapp-root"><img src="images/callouts/2.gif" alt="2" border="0"></a>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></target></span> </pre><div class="calloutlist"><table border="0" summary="Callout list"><tr xmlns:fo="http://www.w3.org/1999/XSL/Format"><td valign="top" align="left"><a name="ca-click-distribution"></a><a href="#co-click-distribution"><img src="images/callouts/1.gif" alt="1" border="0"></a> </td><td valign="top" align="left"><p><code class="literal"><click-distribution></code> is the location
+ where Click is installed on your machine, for example:
+ <code class="literal">C:\software\click-2.1.0\</code>.
+ </p></td></tr><tr xmlns:fo="http://www.w3.org/1999/XSL/Format"><td valign="top" align="left"><a name="ca-webapp-root"></a><a href="#co-webapp-root"><img src="images/callouts/2.gif" alt="2" border="0"></a> </td><td valign="top" align="left"><p><code class="literal"><webapp-root></code> is the root directory
+ of your webapp, for example: <code class="literal">C:\dev\my-webapp\</code>.
+ </p></td></tr></table></div><p>We use the <span class="emphasis"><em><deploy></em></span> Ant Task and specify
+ the attributes <code class="varname">dir</code> and <code class="varname">todir</code>.
+ </p><p><code class="varname">dir</code> specifies the <span class="emphasis"><em>source</em></span>
+ directory to scan for JARs and folders containing static resources,
+ while <code class="varname">todir</code> specifies the <span class="emphasis"><em>target</em></span>
+ directory where the resources should be copied to.
+ </p><p><code class="varname">dir</code> should point to your web application's
+ <span class="emphasis"><em>WEB-INF</em></span> folder, since that is where Click's JARs
+ will be located. <code class="varname">todir</code> should point to your web
+ application's root directory, since that is where Click's resources
+ will be served from.
+ </p><p>The DeployTask also supports nested
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://ant.apache.org/manual/CoreTypes/fileset.html" target="_blank">FileSets</a>
+ if you need to deploy resources from multiple source locations. For
+ example:</p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><target</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"deploy"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">description</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Deploy static resources"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><taskdef</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"deploy"</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"org.apache.click.tools.deploy.DeployTask"</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classpath</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"<click-distribution>/lib/click-dev-tasks-1.1.jar"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><deploy</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">todir</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"${dir.webapp}"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><fileset</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">dir</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"<webapp-root>/WEB-INF"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><include</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"**/classes"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><include</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"**/*.jar"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></fileset></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><fileset</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">dir</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"/some/folder/with/jars"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><include</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"lib-with-resources.jar"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><include</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"another-lib-with-resources.jar"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></fileset></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></deploy></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></target></span> </pre><p>The DeployTask also generates an HTML report in the same folder
+ where the build script is executed from. The report will indicate
+ which resources was deployed successfully and which resources
+ in your webapp root directory is outdated. (An outdated resource means
+ that the resource in the <span class="emphasis"><em>click-xxx.jar</em></span> differs
+ from the resource currently present in your webapp root directory.
+ This can happen when upgrading to a new version of Click)
+ </p></li><li class="listitem"><p>Another option is to add a mapping in <span class="emphasis"><em>web.xml</em></span>
+ to inform ClickServlet to serve static resources. This feature is made
+ available through the
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/service/ResourceService.html" target="_blank">ResourceService</a>
+ interface and its default implementation,
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/service/ClickResourceService.html" target="_blank">ClickResourceService</a>.
+ Below is an example:
+ </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><servlet></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><servlet-name></span>ClickServlet<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></servlet-name></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><servlet-class></span>org.apache.click.ClickServlet<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></servlet-class></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><load-on-startup></span>0<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></load-on-startup></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></servlet></span>
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><servlet-mapping></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><servlet-name></span>ClickServlet<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></servlet-name></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><url-pattern></span>*.htm<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></url-pattern></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></servlet-mapping></span>
+
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com"><!-- Inform ClickServlet to serve static resources contained under the /click/*
+ directory directly from Click's JAR files. --></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><servlet-mapping></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><servlet-name></span>ClickServlet<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></servlet-name></span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"><url-pattern></span>/click/*<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></url-pattern></span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag"></servlet-mapping></span></pre><p>With this setup, ClickServlet will serve all static
+ <code class="varname">/click/*</code> resources directly from Click's JAR files.
+ </p><p>One restriction of ClickResourceService is it only serves
+ resources from the <span class="emphasis"><em>/click/*</em></span> folder. So if you use
+ third-party Click libraries that serve their resources from a different
+ folder e.g. <span class="emphasis"><em>/clickclick/*</em></span>, this option won't work
+ out-of-the-box.
+ </p><p>Also note that with this option Click's resources are served
+ directly from the JAR files, you won't be able to customize the resources,
+ if for example you want change the default styling through CSS.
+ </p></li><li class="listitem"><p>Another option is to manually deploy the resources. Click
+ resources are packaged in JARs under the directory
+ <span class="emphasis"><em>META-INF/resources</em></span>. You can use your IDE
+ to navigate into the JARs and copy all the resources from
+ <span class="emphasis"><em>META-INF/resources</em></span> to your webapp root directory.
+ </p><p>For example, to deploy the resources from
+ <span class="emphasis"><em>click-core.jar</em></span>, copy the <span class="emphasis"><em>/click</em></span>
+ folder and its contents to your web application root folder.
+ </p></li><li class="listitem"><p>And finally you can access Click's resources by deploying your
+ application on a development machine where there are no file system
+ restrictions and the WAR/EAR can be unpacked. You can then copy the
+ deployed resources to your webapp root directory.
+ </p></li></ul></div></div><div class="sect2" title="4.3.2. Deploying Custom Resources"><div class="titlepage"><div><div><h3 class="title"><a name="deploying-custom-resources"></a>4.3.2. Deploying Custom Resources</h3></div></div></div><p> Click supports two ways of deploying pre-configured resources
+ (templates, stylesheets, JavaScript etc.) from a Jar to a web application.
+ (This assumes that the environment Click is running in supports having
+ write access to the file system and that the WAR is unpacked.)
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> Through a Control's
+ <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)" target="_blank">onDeploy()</a>
+ event handler. See the <a class="link" href="ch04s02.html#application-controls" title="4.2.7. Controls">Controls</a>
+ section above.
+ </p></li><li class="listitem"><p>By packaging the resources (stylesheets, JavaScript, Images etc.)
+ into a special folder called <span class="emphasis"><em>'META-INF/resources'</em></span>.
+ </p></li></ol></div><p>As option #1 was already discussed above in section
+ <a class="link" href="ch04s02.html#application-controls" title="4.2.7. Controls">Controls</a>, lets look at option #2.
+ </p><p>When Click starts up, it scans each Jar and folder on the classpath
+ for specially marked entries starting with 'META-INF/resources/'. (Please
+ note that even though Click will scan the entire classpath it is strongly
+ recommended to host your Jar files under your WAR lib folder e.g. WEB-INF/lib.
+ Sharing Jars on the classpath can lead to class loading issues.)
+ </p><p>Click will then copy all files found under 'META-INF/resources/' to
+ the root directory of the webapp.
+ </p><p>
+ For example, given a Jar file with the following entries:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>META-INF/resources/mycorp/edit_customer.js</p></li><li class="listitem"><p>META-INF/resources/mycorp/edit_customer.css</p></li><li class="listitem"><p>mycorp/pages/EditCustomerPage.class</p></li></ul></div><p>Click will copy the files <span class="emphasis"><em>'/mycorp/edit_customer.js'</em></span>
+ and <span class="emphasis"><em>'/mycorp/edit_customer.css'</em></span> to the web application
+ folder.
+ </p><p>Thus if the web application is called 'webapp', the files will be
+ deployed as <span class="emphasis"><em>'webapp/mycorp/edit_customer.js'</em></span> and
+ <span class="emphasis"><em>'webapp/mycorp/edit_customer.css'</em></span>.
+ </p><p>Option #2 is the recommended approach for deploying your own
+ resources since it makes the managing and maintenance of resources much
+ easier.
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.2. Application Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Best Practices</td></tr></table></div></body></html>
\ No newline at end of file
Propchange: click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch04s03.html
------------------------------------------------------------------------------
svn:mime-type = text/plain