Google Git
Sign in
apache / click / click-2.0.x / . / documentation / docs / configuration.html
blob: 44bdd09350b5b447ef3d9400651bcca382374985 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<!--
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>
<!-- saved from url=(0014)about:internet -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<meta name="Author" content="Malcolm Edgar"/>
<meta name="description" lang="en" content="Apache Click Java web application framework"/>
<meta name="keywords" lang="en" content="Apache Click, Click Framework, Java, JEE, J2EE, web application framework, open source"/>
<title>Apache Click</title>
<link rel="stylesheet" type="text/css" href="../help.css"/>
<link rel="stylesheet" type="text/css" href="../syntax-highlighter.css"/>
<style type="text/css">
.items {
margin-bottom: 0.25em;
}
</style>
<script type="text/javascript" src="../syntax-highlighter.js"></script>
</head>
<!--Activate syntax highlighting-->
<body onload="prettyPrint();">
<h1>Configuration</h1>
<p/>
This section discusses how to setup and configure a Click web application and
covers the following topics:
<ol>
<li><a href="#servlet-configuration">Servlet Configuration</a> - how to setup the ClickServlet
</li>
<li><a href="#application-configuration">Application Configuration</a> - how to configure the Click application
descriptor
</li>
<li><a href="#auto-deployed-files">Auto Deployed Files</a> - automatically deployed Click files
</li>
</ol>
<p>&nbsp;</p>
The Click configuration files include:
<table style="margin: 1em">
<tr valign="top">
<td>
<img alt="Click application configuration files" src="../images/config-files.png"/>
</td>
<td>
<ul>
<li>WEB-INF/<a target='topic' href="#application-configuration">click.xml</a>
&nbsp; - &nbsp; Application Configuration (<b>required</b>)
</li>
<li>WEB-INF/<a target='topic' href="#servlet-configuration">web.xml</a>
&nbsp; - &nbsp; Servlet Configuration (<b>required</b>)
</li>
</ul>
</td>
</tr>
</table>
<a name="servlet-configuration" class="heading"></a><h2>1.&nbsp; Servlet Configuration</h2>
For a Click web application to function the
<a target="topic" href="click-api/org/apache/click/ClickServlet.html">ClickServlet</a>
must be configured in the web application's <tt>/WEB-INF/web.xml</tt> file.
A basic web application which maps all <tt>*.htm</tt> requests to a ClickServlet
is provided below.
<pre class="codeConfig">
&lt;web-app&gt;
&lt;servlet&gt;
&lt;servlet-name&gt;<span class="blue">ClickServlet</span>&lt;/servlet-name&gt;
&lt;servlet-class&gt;<span class="red">org.apache.click.ClickServlet</span>&lt;/servlet-class&gt;
&lt;load-on-startup&gt;<span class="red">0</span>&lt;/load-on-startup&gt;
&lt;/servlet&gt;
&lt;servlet-mapping&gt;
&lt;servlet-name&gt;<span class="blue">ClickServlet</span>&lt;/servlet-name&gt;
&lt;url-pattern&gt;<span class="red">*.htm</span>&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;
&lt;/web-app&gt;
</pre>
<h3>1.1&nbsp; Servlet Mapping</h3>
By convention all Click page templates should have a .htm extension, and
the ClickServlet should be mapped to process all *.htm URL requests. With
this convention you have all the static HTML pages use a .html extension
and they will not be processed as Click pages.
<h3>1.2&nbsp; Load On Startup</h3>
Note you should always set <tt>load-on-startup</tt> element to be 0 so the
servlet is initialized when the server is started. This will prevent any
delay for the first client which uses the application.
<p/>
The <tt>ClickServlet</tt> performs as much work as possible at startup to
improve performance later on. The Click start up and caching strategy is
configured with the Click application mode element in the "<tt>click.xml</tt>"
config file, covered next.
<a name="application-configuration" class="heading"></a><h2>2.&nbsp; Application Configuration</h2>
The heart of a Click application is the <tt>click.xml</tt> configuration file.
This file specifies the application pages, headers, the format object and the
applications mode.
<p/>
By default the ClickServlet will attempt to load the application
configuration file using the path: &nbsp; <tt>/WEB-INF/click.xml</tt>
<p/>
If this file is not found under the <tt>WEB-INF</tt> directory, then
ClickServlet will attempt to load it from the classpath as <tt>/click.xml</tt>.
<p/>
See <a target='topic' href="click-dtd.html">Click DTD</a> for the click-app XML definition.
<p/>
A complete Click configuration example is available <a target='topic' href="click-dtd-example.html">here</a>
which can be used as a quick reference when configuring Click.
<p/>
A basic Click app config file is provided below:
<pre class="prettyprint">
&lt;click-app&gt;
&lt;pages package="com.mycorp.page"/&gt;
&lt;mode value="profile"/&gt;
&lt;/click-app&gt;
</pre>
<p/>
An example of an advanced config file is:
<pre class="prettyprint">
&lt;click-app charset="UTF-8" locale="de"&gt;
&lt;pages package="com.mycorp.banking.page"&gt;
&lt;page path="index.htm" classname="Home"/&gt;
&lt;/pages&gt;
&lt;pages package="com.mycorp.common.page"/&gt;
&lt;format classname="com.mycorp.util.Format"/&gt;
&lt;mode value="profile"/&gt;
&lt;log-service classname="org.apache.click.extras.service.Log4JLogService"/&gt;
&lt;/click-app&gt;
</pre>
The rest of this chapter cover Click configuration in detail.
<a name="application-click-app" class="heading"></a><h3>2.1&nbsp; Click App</h3>
The root <span class="red">click-app</span> element defines two application
localization attributes <span class="blue">charset</span> and
<span class="blue">locale</span>.
<pre class="codeDtd">
&lt;!ELEMENT <span class="red">click-app</span> (pages*, headers?, format?, mode?, controls?,
file-upload-service?, log-service?, template-service?)&gt;
&lt;!ATTLIST click-app <span class="blue">charset</span> CDATA #IMPLIED&gt;
&lt;!ATTLIST click-app <span class="blue">locale</span> CDATA #IMPLIED&gt;
</pre>
The <span class="blue">charset</span> attribute defines the character encoding
set for:
<ul style="margin-top:0.5em">
<li class="items">Velocity templates</li>
<li class="items">HttpServletRequest character encoding</li>
<li class="items">Page Content-Type charset, see Page
<a href="click-api/org/apache/click/Page.html#getContentType()">getContentType()</a>
</li>
</ul>
The <span class="blue">locale</span> attribute defines the default application
Locale. If this value is defined it will override Locale returned by the request.
Please see the Context
<a href="click-api/org/apache/click/Context.html#getLocale()">getLocale()</a>
for details.
<p/>
For example the folliwing configuration sets the application character set to
UTF-8 and the default Locale as German (de):
<pre class="codeConfig">
&lt;click-app <span class="blue">charset</span>="<span class="red">UTF-8</span>" <span class="blue">locale</span>="<span class="red">de</span>"&gt;
..
&lt;/click-app&gt;
</pre>
<a name="application-pages" class="heading"></a><h3>2.2&nbsp; Pages</h3>
The first child element of the click-app is the mandatory <tt>pages</tt> element
which defines the list of Click pages.
<pre class="codeDtd">
&lt;!ELEMENT <span class="blue">pages</span> (<span class="red">page</span>*)&gt;
&lt;!ATTLIST pages <span class="blue">package</span> CDATA #IMPLIED&gt;
&lt;!ATTLIST pages <span class="blue">automapping</span> (true|false) "true"&gt;
&lt;!ATTLIST pages <span class="blue">autobinding</span> (true|false) "true"&gt;
</pre>
The pages element can specify a default <span class="blue">package</span>
name which is prepended to the classname of any pages defined.
<p/>
The pages element also defines the <span class="blue">automapping</span> attribute
which is discussed in the
<a href="#application-automapping">Page Automapping</a> topic.
<a name="application-multi-packages" class="heading"></a><h4>2.2.1&nbsp; Multiple Pages Packages</h4>
Click can support multiple pages elements to enable the automapping of multiple
packages.
<pre class="prettyprint">
&lt;click-app&gt;
&lt;pages package="com.mycorp.banking.page"/&gt;
&lt;pages package="com.mycorp.common.page"/&gt;
&lt;/click-app&gt;
</pre>
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.
<a name="application-page" class="heading"></a><h3>2.3&nbsp; Page</h3>
The <span class="red">page</span> element defines the Click application pages.
<pre class="codeDtd">
&lt;!ELEMENT <span class="red">page</span> (<span class="blue">header</span>*)&gt;
&lt;!ATTLIST page <span class="blue">path</span> CDATA #REQUIRED&gt;
&lt;!ATTLIST page <span class="blue">classname</span> CDATA #REQUIRED&gt;
</pre>
Each page <span class="blue">path</span> must be unique, as the Click application maps HTTP requests to the page paths.
<p/>
The Click application will create a new Page instance for the given request using
the configured page <span class="blue">classname</span>. All pages must subclass
<a target="topic" href="click-api/org/apache/click/Page.html">Page</a>
and provide a public no arguments constructor, so they can be instantiated.
<p/>
Pages can also define <span class="blue">header</span> values which are discussed
in the next topic.
<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 <tt>ERROR</tt> message and throw an
<a class="external" target="_blank" href="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/UnavailableException.html">UnavailableException</a>.
If this occurs the click application will be permanently unavailable until the error is fixed
and the web app is restarted.
<a name="application-automapping" class="heading"></a><h4>2.3.1&nbsp; Page Automapping</h4>
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/>
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/>
For example given a page path to class mapping:
<pre class="codeConfig" style="background-color: white;">
<span class="navy">index.htm</span> => <span class="maroon">com.mycorp.page.Home</span>
<span class="navy">search.htm</span> => <span class="maroon">com.mycorp.page.Search</span>
<span class="navy">contacts/contacts.htm</span> => <span class="maroon">com.mycorp.page.contacts.Contacts</span>
<span class="navy">security/login.htm</span> => <span class="maroon">com.mycorp.page.security.Login</span>
<span class="navy">security/logout.htm</span> => <span class="maroon">com.mycorp.page.security.Logout</span>
<span class="navy">security/change-password.htm</span> => <span class="maroon">com.mycorp.page.security.ChangePassword</span>
</pre>
This could be configured manually by setting the <span class="red">automapping</span> attribute to "false"
and using the package prefix, for example:
<pre class="codeConfig">
&lt;click-app&gt;
&lt;pages package="<span class="maroon">com.mycorp.page</span>" <span class="red">automapping</span>="<span class="blue">false</span>"&gt;
&lt;page path="<span class="navy">index.htm</span>" classname="<span class="maroon">Home</span>"/&gt;
&lt;page path="<span class="navy">search.htm</span>" classname="<span class="maroon">Search</span>"/&gt;
&lt;page path="<span class="navy">contacts/contacts.htm</span>" classname="<span class="maroon">contacts.Contacts</span>"/&gt;
&lt;page path="<span class="navy">security/login.htm</span>" classname="<span class="maroon">security.Login</span>"/&gt;
&lt;page path="<span class="navy">security/logout.htm</span>" classname="<span class="maroon">security.Logout</span>"/&gt;
&lt;page path="<span class="navy">security/change-password.htm</span>" classname="<span class="maroon">security.ChangePassword</span>"/&gt;
&lt;/pages&gt;
&lt;/click-app&gt;
</pre>
Using automapping you only need to define the Home page which doesn't automatically
map to index.html.
<pre class="codeConfig">
&lt;click-app&gt;
&lt;pages package="<span class="maroon">com.mycorp.page</span>" <span class="red">automapping</span>="<span class="blue">true</span>"&gt;
&lt;page path="<span class="navy">index.htm</span>" classname="<span class="maroon">Home</span>"/&gt;
&lt;/pages&gt;
&lt;/click-app&gt;
</pre>
Note <span class="red">automapping</span> is true by default, so it could be omitted
from the configuration file.
<p/>
The page template name to classname convention is:
<pre class="codeConfig" style="background-color: white;">
change-password.htm => ChangePassword
change_password.htm => ChangePassword
changePassword.htm => ChangePassword
ChangePassword.htm => ChangePassword
</pre>
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:
<pre class="codeConfig" style="background-color: white;">
customer.htm => CustomerPage
change-password.htm => ChangePasswordPage
</pre>
<a name="application-excludes" class="heading"></a><h4>2.3.2&nbsp; Automapping Excludes</h4>
With Page automapping there can be resources where you don't want automapping
applied. For example when using a JavaScript library with lots of
<tt>.htm</tt> files, you don't want automapping to try and find Page class for
each of these files.
<p/>
In these situations you can use the pages <tt>excludes</tt> element.
<pre class="codeDtd">
&lt;!ELEMENT <span class="red">excludes</span> (#PCDATA)&gt;
&lt;!ATTLIST excludes <span class="blue">pattern</span> CDATA #REQUIRED&gt;
</pre>
For example if our application uses the TinyMCE JavaScript library we could
configure our pages automapping to exclude all <tt>.htm</tt> files under the
<tt>/tiny_mce</tt> directory.
<pre class="codeConfig">
&lt;click-app&gt;
&lt;pages package="com.mycorp.page"&gt;
&lt;<span class="blue">excludes</span> pattern="<span class="red">/tiny_mce/*</span>"/&gt;
&lt;/pages&gt;
&lt;/click-app&gt;
</pre>
The excludes pattern can specify multiple directories or files using a comma
separated notation. For example:
<pre class="codeConfig">
&lt;click-app&gt;
&lt;pages package="com.mycorp.page"&gt;
&lt;<span class="blue">excludes</span> pattern="<span class="red">/dhtml/*, /tiny_mce/*, banner.htm, about.htm</span>"/&gt;
&lt;/pages&gt;
&lt;/click-app&gt;
</pre>
HTM files excluded from Page automapping are handled by an internal Page class
with caching headers enabled.
<a name="application-autobinding" class="heading"></a><h4>2.3.3&nbsp; Page Autobinding</h4>
By default all pages have autobinding enabled. With autobinding enabled the
ClickServlet will automatically:
<ul>
<li class="items">add any public controls to the page, after the page constructor has been invoked</li>
<li class="items">if the public control's name is not defined, its name will be set to the the value its field name</li>
<li class="items">bind any request parameters to public page fields, after page constructor has been invoked.
See <a href="click-api/org/apache/click/ClickServlet.html#processPageRequestParams(org.apache.click.Page)">ClickServlet.processPageRequestParams(Page)</a>
for more details
</li>
<li class="items">add any public page fields to the page model, before rendering</li>
</ul>
For example:
<pre class="prettyprint">
public class EmployeePage extends Page {
public Form employeeForm = new Form();
public Table myTable = new Table();
} </pre>
In the example above the <span class="blue">employeeForm</span> and <span class="blue">myTable</span>
controls were not added to the page. Also note that Form and Table does not have their names defined.
<p/>
When autobinding is enabled, ClickServlet will create a new Page and add the public
controls to the page. In the example above the <span class="blue">employeeForm</span> and
<span class="blue">myTable</span> will be added to the page, as if you had invoked,
<em>addControl(employeeForm)</em> and <em>addControl(myTable)</em>.
<p/>
The control's 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 <span class="blue">employeeForm</span>
while the Table name will set to <span class="blue">myTable</span>.
<p/>
The above example is thus a shorthand way of writing the following:
<pre class="prettyprint">
public class EmployeePage extends Page {
private Form employeeForm = new Form();
private Table myTable = new Table();
public void onInit() {
employeeForm.setName("employeeForm");
addControl(employeeForm);
myTable.setName("myTable");
addControl(myTable);
}
} </pre>
You can turn this behaviour off by setting the autobinding attribute to false, for example:
<pre class="codeConfig">
&lt;click-app&gt;
&lt;pages package="com.mycorp.page" <span class="blue">autobinding</span>="<span class="red">false</span>"/&gt;
&lt;/click-app&gt;
</pre>
<a name="application-headers" class="heading"></a><h3>2.4&nbsp; Headers</h3>
The optional <tt>headers</tt> element defines a list of <tt>header</tt> elements
which are applied to all pages.
<pre class="codeDtd">
&lt;!ELEMENT <span class="blue">headers</span> (<span class="red">header</span>*)&gt;
</pre>
The <tt><span class="red">header</span></tt> element defines header name and value
pairs which are applied to the
<a class="external" target="_blank" href="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/http/HttpServletResponse.html">HttpServletResponse</a>.
<pre class="codeDtd">
&lt;!ELEMENT <span class="red">header</span> (#PCDATA)&gt;
&lt;!ATTLIST header <span class="blue">name</span> CDATA #REQUIRED&gt;
&lt;!ATTLIST header <span class="blue">value</span> CDATA #REQUIRED&gt;
&lt;!ATTLIST header <span class="blue">type</span> (String|Integer|Date) "String"&gt;
</pre>
Page headers are set after the Page has been constructed and before <tt>onInit()</tt> is called.
Pages can then modify their
<a target="topic" href="click-api/org/apache/click/Page.html#headers">headers</a> property using
the <a href="click-api/org/apache/click/Page.html#setHeader(java.lang.String, java.lang.Object)">setHeader()</a>
method.
<h4>2.4.1&nbsp; Browser Caching</h4>
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 <tt>headers</tt>
element in your application:
<pre class="codeConfig">
&lt;click-app&gt;
&lt;pages&gt;
..
&lt;/pages&gt;
&lt;headers&gt;
&lt;header name="<span class="blue">Pragma</span>" value="<span class="blue">no-cache</span>"/&gt;
&lt;header name="<span class="blue">Cache-Control</span>"
value="<span class="blue">no-store, no-cache, must-revalidate, post-check=0, pre-check=0</span>"/&gt;
&lt;header name="<span class="blue">Expires</span>" value="<span class="blue">1</span>" type="<span class="blue">Date</span>"/&gt;
&lt;/headers&gt;
&lt;/click-app&gt;
</pre>
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:
<pre class="codeConfig">
&lt;page path="<span class="blue">login.htm</span>" classname="<span class="blue">com.mycorp.page.Login</span>"&gt;
&lt;header name="<span class="blue">Pragma</span>" value="<span class="blue">no-cache</span>"/&gt;
&lt;header name="<span class="blue">Expires</span>" value="<span class="blue">1</span>" type="<span class="blue">Date</span>"/&gt;
&lt;/page&gt;
</pre>
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.
<pre class="codeConfig">
&lt;page path="<span class="blue">home.htm</span>" classname="<span class="blue">com.mycorp.page.Home</span>"&gt;
&lt;header name="<span class="blue">Cache-Control</span>" value="<span class="blue">max-age=3600, public, must-revalidate</span>"/&gt;
&lt;/page&gt;
</pre>
To apply header values globally define header values in the headers element. For example:
<pre class="codeConfig">
&lt;click-app&gt;
&lt;pages&gt;
..
&lt;/pages&gt;
&lt;headers&gt;
&lt;header name="<span class="blue">Pragma</span>" value="<span class="blue">no-cache</span>"/&gt;
&lt;header name="<span class="blue">Cache-Control</span>"
value="<span class="blue">no-store, no-cache, must-revalidate, post-check=0, pre-check=0</span>"/&gt;
&lt;header name="<span class="blue">Expires</span>" value="<span class="blue">1</span>" type="<span class="blue">Date</span>"/&gt;
&lt;/headers&gt;
&lt;/click-app&gt;
</pre>
<a name="application-format" class="heading"></a><h3>2.5&nbsp; Format</h3>
The optional <tt>format</tt> element defines the Format object classname which
is applied to all pages.
<pre class="codeDtd">
&lt;!ELEMENT <span class="blue">format</span> (#PCDATA)&gt;
&lt;ATTLIST format classname CDATA #FIXED "org.apache.click.util.Format"&gt;
</pre>
By default all Click pages are configured with a
<a target="topic" href="click-api/org/apache/click/util/Format.html">org.apache.click.util.Format</a>
object. The format object is made available in the Velocity page templates using the name
<tt>$<span class="blue">format</span></tt>.
<p/>
To specify a custom format class configure a <tt>format</tt> element in the click-app
descriptor. For example:
<pre class="codeConfig">
&lt;click-app&gt;
..
&lt;<span class="blue">format</span> classname="<span class="red">com.mycorp.util.CustomFormat</span>"/&gt;
&lt;/click-app&gt;
</pre>
<a name="application-mode" class="heading"></a><h3>2.6&nbsp; Mode</h3>
The optional <tt>mode</tt> element defines the application logging and caching mode.
<pre class="codeDtd">
&lt;!ELEMENT mode (#PCDATA)&gt;
&lt;ATTLIST mode value (<span class="blue">production</span>|<span class="blue">profile</span>|<span class="blue">development</span>|<span class="blue">debug</span>|<span class="blue">trace</span>) "development"&gt;
</pre>
By default Click applications run in <tt>development</tt> mode, which switches off page
template caching, and the logging level is set to <tt>INFO</tt>.
<p/>
To change the default application mode configure a mode element in the click-app
descriptor. For example to specify <tt>production</tt> mode you would add the
following mode element:
<pre class="codeConfig">
&lt;click-app&gt;
..
&lt;<span class="blue">mode</span> value="<span class="red">production</span>"&gt;
&lt;/click-app&gt;
</pre>
The application mode configuration can be overridden by setting the system
property <tt>"click.mode"</tt>. This can be use in the scenario of debugging
a problem on a production system, where you change the mode to <tt>trace</tt>
by setting the following system property and restarting the application.
<pre class="codeConfig">
-Dclick.mode=trace
</pre>
The Click Application modes and their settings for Page auto loading,
template caching and logging levels are:
<p>
<table style="border: 1px solid black;" cellspacing="0" cellpadding="6">
<tr style="background-color: navy; color: white;">
<th align="center">Application mode</th>
<th align="center">Page auto loading</th>
<th align="center">Template caching</th>
<th align="center">Click logging level</th>
<th align="center">Velocity logging level</th>
</tr>
<tr>
<td align="center"><tt><span class="blue">production</span></tt></td>
<td align="center">No</td>
<td align="center">Yes</td>
<td align="center">WARN</td>
<td align="center">ERROR</td>
</tr>
<tr>
<td align="center"><tt><span class="blue">profile</span></tt></td>
<td align="center">No</td>
<td align="center">Yes</td>
<td align="center">INFO</td>
<td align="center">ERROR</td>
</tr>
<tr>
<td align="center"><tt><span class="blue">development</span></tt></td>
<td align="center">Yes</td>
<td align="center">No</td>
<td align="center">INFO</td>
<td align="center">ERROR</td>
</tr>
<tr>
<td align="center"><tt><span class="blue">debug</span></tt></td>
<td align="center">Yes</td>
<td align="center">No</td>
<td align="center">DEBUG</td>
<td align="center">ERROR</td>
</tr>
<tr>
<td align="center"><tt><span class="blue">trace</span></tt></td>
<td align="center">Yes</td>
<td align="center">No</td>
<td align="center">TRACE</td>
<td align="center">WARN</td>
</tr>
</table>
<a name="page-auto-loading" class="heading"></a><h4>2.6.1&nbsp; Page Auto Loading</h4>
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 href="#application-automapping">Page Automapping</a> rules.
<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.
<a name="click-logging" class="heading"></a><h4>2.6.2&nbsp; Click and Velocity Logging</h4>
The Click and Velocity runtimes use
<a target="topic" href="click-api/org/apache/click/service/LogService.html">LogService</a>
for logging messages. The default LogService implementation is
<a target="topic" href="click-api/org/apache/click/service/ConsoleLogService.html">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 <tt>trace</tt>:
<pre class="codeConfig" style="padding:1em;background-color:#f0f0f0;">
[Click] [debug] GET http://localhost:8080/quickstart/home.htm
[Click] [trace] invoked: HomePage.&lt;&lt;init&gt;&gt;
[Click] [trace] invoked: HomePage.onSecurityCheck() : true
[Click] [trace] invoked: HomePage.onInit()
[Click] [trace] invoked: HomePage.onGet()
[Click] [trace] invoked: HomePage.onRender()
[Click] [info ] renderTemplate: /home.htm - 6 ms
[Click] [trace] invoked: HomePage.onDestroy()
[Click] [info ] handleRequest: /home.htm - 24 ms </pre>
Any unhandled <tt>Throwable</tt> errors are logged by the ClickServlet.
<p/>
Note that Click Extras also provide log adaptors for <a target="topic" href="extras-api/org/apache/click/extras/service/Log4JLogService.html">Log4J</a>
and the <a target="topic" href="extras-api/org/apache/click/extras/service/JdkLogService.html">JDK Logging API</a>.
<p/>
When an application is not in <tt>production</tt> mode the error page displays
detailed debugging information. When the application mode is <tt>production</tt>
no debug information is displayed to prevent sensitive information being revealed.
This behaviour can be changed by modifying the deployed
<span class="blue"><tt>click/error.htm</tt></span> page template.
<a name="application-controls" class="heading"></a><h3>2.7&nbsp; Controls</h3>
The optional <tt>controls</tt> element defines a list of <tt>control</tt> elements
which will be deployed on application startup.
<pre class="codeDtd">
&lt;!ELEMENT <span class="blue">controls</span> (<span class="red">control</span>*)&gt;
</pre>
The <tt><span class="red">control</span></tt> registers
<a href="click-api/org/apache/click/Control.html">Control</a>
classes which
will have their <a href="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</a>
method invoked when the click application starts.
<pre class="codeDtd">
&lt;!ELEMENT <span class="red">control</span> (#PCDATA)&gt;
&lt;!ATTLIST control <span class="blue">classname</span> CDATA #REQUIRED&gt;
</pre>
For example to have a <tt>CustomField</tt> control deploy its resources on
application startup, you would add the following elements to your
<tt>click.xml</tt> file:
<pre class="codeConfig">
&lt;click-app&gt;
..
&lt;controls&gt;
&lt;<span class="blue">control</span> classname=<span class="red">"com.mycorp.control.CustomField"</span>/&gt;
&lt;/controls&gt;
&lt;/click-app&gt; </pre>
<a name="auto-deployed-files" class="heading"></a><h2>3.&nbsp; Auto Deployed Files</h2>
To make pre-configured resources (templates, stylesheets, etc.) available to web applications,
Click automatically deploys configured classpath resources to the <tt class="blue">/click</tt>
directory at startup (if not already present).
<p/>
You can modify these support files and Click will <b>not</b> overwrite them. These files include:
<ul>
<li>click/error.htm &nbsp; - &nbsp; the Page <a href="pages.html#page-error-handling">Error Handling</a> template</li>
<li>click/control.css &nbsp; - &nbsp; the Controls cascading stylesheet</li>
<li>click/control.js &nbsp; - &nbsp; the Controls JavaScript library</li>
<li>click/not-found.htm &nbsp; - &nbsp; the <a href="pages.html#page-not-found">Page Not Found</a> template</li>
</ul>
<p/>
For example to customize the control styles you can place a customized copy
(or even a brand new version) of <tt>control.css</tt> under the <tt>/click</tt>
folder in your web project:
<pre>
/webapp/click/control.css
</pre>
When Click starts up it will <tt>not</tt> override your copy of <tt>control.css</tt>
with its own default version.
<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 <tt>/click</tt> folder, you will override the default resource.
<p/>
Be aware that some of the more complex controls (checklist, colorpicker, tree),
deploys resources to subfolders under <tt>/click</tt>, for example <tt>/click/checklist/*</tt>.
<p/>
A control's Javadoc will normally indicate what resources are deployed for that control.
<p/>
It is generally easier to work with unpacked WARs and most servlet containers
do just that. However some contains such as WebLogic (at least version 10) does not.
To enable WebLogic to unpack the WAR go to the <em>Admin Console > server node > Web Applications</em>
tab and check the <em>Archived Real Path Enabled</em> parameter.
<p/>
If Click cannot deploy resources because of restricted file system permissions,
warning messages will be logged.
<p/>
If your application server does not unpack the WAR/EAR or has restricted permissions,
you will need to package up these auto deployed files in your web applications WAR file.
To do this you should run you application on a development machine without these restrictions
and then package up the deployed files into the WAR/EAR before deployment.
<a name="deploying-custom-resources" class="heading"></a><h3>3.1&nbsp; Deploying Custom Resources</h3>
<p/>
Click supports two ways of deploying pre-configured resources (templates,
stylesheets, JavaScript etc.) from a Jar to a web applications.
<ol>
<li>
Through a Control's <a href="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</a>
event handler. See the <a href="#application-controls">Controls</a> section above.
</li>
<li>
By packaging the resources (stylesheets, JavaScript, Images etc.) into a special folder called <em>'META-INF/web'</em>.
</li>
</ol>
As option #1 was already discussed above in section <a href="#application-controls">2.7 Controls</a>,
lets look at option #2.
<p/>
When Click starts up, it scans each Jar in the classpath for specially marked
entries starting with 'META-INF/web/'. (Please note that even though Click will
scan the entire classpath it is strongly recommended to host your Jar files inside
your WAR lib folder e.g. WEB-INF/lib. Sharing Jars on the classpath can lead to
class loading issues.)
<p/>
Click will then copy all files found under 'META-INF/web/' to the web application
folder.
<p/>
For example, given a Jar file with the following entries:
<ul>
<li>
META-INF/web/mycorp/edit_customer.js
</li>
<li>
META-INF/web/mycorp/edit_customer.css
</li>
<li>
mycorp/pages/EditCustomerPage.class
</li>
</ul>
Click will copy the files <em>'/mycorp/edit_customer.js'</em> and <em>'/mycorp/edit_customer.css'</em>
to the web application folder.
<p/>
Thus if the web application is called 'webapp', the files will be deployed as
<em>'webapp/mycorp/edit_customer.js'</em> and <em>'webapp/mycorp/edit_customer.css'</em>.
<p/>
Option #2 is especially useful when you need to deploy a large number of
resources from a Jar. Note, only Jars placed under the <em>'WEB-INF/lib'</em> folder will
be deployed.
</body>
</html>