You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by sa...@apache.org on 2009/01/21 23:10:26 UTC
svn commit: r736438 [1/2] - in
/incubator/click/trunk/tools/docbook/src/docbook/click:
chapter-best-practices.xml chapter-configuration.xml chapter-controls.xml
chapter-pages.xml
Author: sabob
Date: Wed Jan 21 14:10:25 2009
New Revision: 736438
URL: http://svn.apache.org/viewvc?rev=736438&view=rev
Log:
initial conversion done by Gilberto
Modified:
incubator/click/trunk/tools/docbook/src/docbook/click/chapter-best-practices.xml
incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml
incubator/click/trunk/tools/docbook/src/docbook/click/chapter-controls.xml
incubator/click/trunk/tools/docbook/src/docbook/click/chapter-pages.xml
Modified: incubator/click/trunk/tools/docbook/src/docbook/click/chapter-best-practices.xml
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/src/docbook/click/chapter-best-practices.xml?rev=736438&r1=736437&r2=736438&view=diff
==============================================================================
--- incubator/click/trunk/tools/docbook/src/docbook/click/chapter-best-practices.xml (original)
+++ incubator/click/trunk/tools/docbook/src/docbook/click/chapter-best-practices.xml Wed Jan 21 14:10:25 2009
@@ -1,10 +1,665 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="chapter-best-practices">
- <title>Best Practices</title>
-
- <section id="section-security">
- <title>Security</title>
-
- </section>
-
-</chapter>
\ No newline at end of file
+<?xml version='1.0' encoding='UTF-8'?>
+ <chapter remap="h1">
+ <title>Best Practices</title>
+ <para> This section discusses Best Practices for designing and building Click application. The following topics are covered: </para>
+ <orderedlist>
+ <listitem>
+ <para><link linkend="best-practices.html-security">Security</link> - use JEE role based security</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-packages-classes">Packages and Classes</link> - project package structures and page classes</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-automapping">Page Auto Mapping</link> - use Convention over Configuration</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-navigation">Navigation</link> - use Page classes to forward and redirect</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-templating">Templating</link> - to standardize your web application</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-menus">Menus</link> - centralize your page navigation</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-logging">Logging</link> - use Log4j in a base page</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-error-handling">Error Handling</link> - use custom error page</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="best-practices.html-performance">Performance</link> - enhancing page performance</para>
+ </listitem>
+ </orderedlist>
+ <para>Â </para>
+ <para>
+ <anchor id="best-practices.html-security"/>
+ </para>
+ <indexterm>
+ <primary>security</primary>
+ </indexterm>
+ <sect1 remap="h2">
+ <title>1. Security</title>
+ <para> For application security it is highly recommended that you use the declarative JEE Servlet path role based security model. While Click pages provide an <literal>onSecurityCheck()</literal> method for rolling your own programatic security model, the declarative JEE model provides numerous advantages. These advantages include: <itemizedlist>
+ <listitem>
+ <para> Its an industry standard pattern making development and maintenance easier.</para>
+ </listitem>
+ <listitem>
+ <para> Application servers generally provide numerous ways of integration with an organisations security infrastructure, including LDAP directories and relational databases.</para>
+ </listitem>
+ <listitem>
+ <para> Servlet security model support users bookmarking pages. When users go to access these pages later, the container will automatically authenticate them before allowing them to access the resource.</para>
+ </listitem>
+ <listitem>
+ <para> Using this security model you can keep your Page code free of security concerns. This makes you code more reusable, or at least easier to write.</para>
+ </listitem>
+ </itemizedlist>
+ If your application has very fine grained or complex security requirements you may need to combine both the JEE declarative security model and a programmatic security model to meet your needs. In these cases its recommended you use declarative security for course grained access and programmatic security for finner grained access control. </para>
+ <sect2 remap="h4">
+ <title>Declarative Security</title>
+ <para> The declarative JEE Servlet security model requires users to be authenticated and in the right roles before they can access secure resources. Relative to many of the JEE specifications the Servlet security model is surprisingly simple. For example to secure admin pages, you add a security constraint in your <literal>web.xml</literal> file. This requires users to be in the admin role before they can access to any resources under the admin directory: <screen>
+<security-constraint>
+ <web-resource-collection>
+ <web-resource-name>admin</web-resource-name>
+ <url-pattern>
+/admin/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>
+admin</role-name>
+ </auth-constraint>
+</security-constraint>
+</screen> The application user roles are defined in the <literal>web.xml</literal> file as <literal>security-role</literal> elements: <screen>
+<security-role>
+ <role-name>
+admin</role-name>
+</security-role>
+</screen> The Servlet security model supports three different authentication method: <itemizedlist>
+ <listitem>
+ <para><literal>BASIC</literal> - only recommended for internal applications where security is not important. This is the easiest authentication method, which simply displays a dialog box to users requiring them to authenticate before accessing secure resources. The BASIC method is relatively unsecure as the username and password are posted to the server as a Base64 encoded string.</para>
+ </listitem>
+ <listitem>
+ <para><literal>DIGEST</literal> - recommended for internal applications with a moderate level of security. As with BASIC authentication, this method simply displays a dialog box to users requiring them to authenticate before accessing secure resources. Not all application servers support DIGEST authentication, with only more recent versions of Apache Tomcat supporting this method.</para>
+ </listitem>
+ <listitem>
+ <para><literal>FORM</literal> - recommended applications for where you need a customised login page. For applications requiring a high level of security it is recommended that you use the FORM method over HTTPS.</para>
+ </listitem>
+ </itemizedlist>
+ The authentication method is specified in the <login-method> element. For example to use the BASIC authentication method you would specify: <screen>
+<login-config>
+ <auth-method>
+BASIC</auth-method>
+ <realm-name>Admin Realm</realm-name>
+</login-config>
+</screen> To use the FORM method you also need to specify the path to the login page and the login error page: <screen>
+<login-config>
+ <auth-method>
+FORM</auth-method>
+ <realm-name>Secure Realm</realm-name>
+ <form-login-config>
+ <form-login-page>
+/login.htm</form-login-page>
+ <form-error-page>
+/login.htm?auth-error=true</form-error-page>
+ </form-login-config>
+</login-config>
+</screen> In your Click <literal>login.htm</literal> page you need to include a special j_security_check form which includes the input fields j_username and j_password. For example: <screen>
+
+#if ($request.getParameter(
+"auth-error"))
+<div style="margin-bottom:1em;margin-top:1em;color:red;">
+ Invalid User Name or Password, please try again.<br/>
+ Please ensure Caps Lock is off.
+</div>
+
+#end
+
+<form method="POST" action="
+j_security_check" name="form">
+<table border="0" style="margin-left:0.25em;">
+ <tr>
+ <td><label>User Name</label><font color="red">*</font></td>
+ <td><input type="text" name="
+j_username" maxlength="20" style="width:150px;"/></td>
+ <td>&nbsp;</td>
+ </tr>
+ <tr>
+ <td><label>User Password</label><font color="red">*</font></td>
+ <td><input type="password" name="
+j_password" maxlength="20" style="width:150px;"/></td>
+ <td><input type="image" src="$context/images/login.png" title="Click to Login"/></td>
+ </tr>
+</table>
+</form>
+
+<script type="text/javascript">
+ document.form.j_username.focus();
+</script>
+</screen> When using FORM based authentication do <emphasis role="bold">NOT</emphasis> put application logic in a Click Login Page class, as the role of this page is to simply render the login form. If you attempt to put navigation logic in your Login Page class, the JEE Container may simply ignore it or throw errors. Putting this all together below is a <literal>web.xml</literal> snippet which features security constraints for pages under the admin path and the user path. This configuration uses the FORM method for authentication, and will also redirect unauthorized (403) requests to the <literal>/not-authorized.htm</literal> page. <screen>
+<web-app>
+
+ ..
+
+ <error-page>
+ <error-code>403</error-code>
+ <location>
+/not-authorized.htm</location>
+ </error-page>
+
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>admin</web-resource-name>
+ <url-pattern>
+/admin/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>
+admin</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>user</web-resource-name>
+ <url-pattern>
+/user/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>
+admin</role-name>
+ <role-name>
+user</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <login-config>
+ <auth-method>
+FORM</auth-method>
+ <realm-name>Secure Zone</realm-name>
+ <form-login-config>
+ <form-login-page>
+/login.htm</form-login-page>
+ <form-error-page>
+/login.htm?auth-error=true</form-error-page>
+ </form-login-config>
+ </login-config>
+
+ <security-role>
+ <role-name>
+admin</role-name>
+ </security-role>
+
+ <security-role>
+ <role-name>
+user</role-name>
+ </security-role>
+
+</web-app>
+</screen></para>
+ </sect2>
+ <sect2 remap="h4">
+ <title>Alternative Security solutions</title>
+ <para> There are also alternative security solutions that provide extra features not available in JEE, such as RememberMe functionality, better resource mapping and <literal>Post Logon Page</literal> support. (<literal>Post Logon Page</literal> support allows one to specify a default URL where the user will be forwarded after successful login. This feature allows one to embed a login form in all non-secure pages and after successful authentication the user will be forwarded to their home page.) Below are some of the alternative security solutions available: <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://static.springframework.org/spring-security/site/index.html">Spring Security</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://securityfilter.sourceforge.net/">SecurityFilter</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.jsecurity.org/">JSecurity</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+</para>
+ </sect2>
+ <sect2 remap="h4">
+ <title>Resources</title>
+ <para> For more information on using security see the resources below: <itemizedlist>
+ <listitem>
+ <para><ulink url="http://stc.cis.brown.edu/~stc/Projects/Shibboleth/Version-3/Checklist/Tomcat-Authn/FormBasedAuthentication.pdf">Form Based Authentication</ulink> by Louis E. Mauget</para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://java.sun.com/products/servlet/download.html">Servlet Specification</ulink> by Sun Microsystems</para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://en.wikipedia.org/wiki/Basic_authentication_scheme">Basic authentication scheme</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://en.wikipedia.org/wiki/Digest_access_authentication">Digest authentication scheme</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://en.wikipedia.org/wiki/Https">Https URI scheme</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+<anchor id="best-practices.html-packages-classes"/><indexterm>
+ <primary>packages-classes</primary>
+ </indexterm>
+</para>
+ </sect2>
+ </sect1>
+ <sect1 remap="h2">
+ <title>2. Packages and Classes</title>
+ <para> An excellent way to design your project package structure is the classify packages initially by technology. So in a Click application all of our pages would be contained under a <literal>page</literal> package. This also works very well with the Page automapping feature. All the projects domain entity classes would be contained under a <literal>entity</literal> package, and service classes would be contained under a <literal>service</literal> directory. Note alternative names for the <literal>entity</literal> package include domain or model. We also typically have a <literal>util</literal> package for any stray classes which don't quite fit into the other packages. In Java package names are singular by convention, so we have a util package rather than an utils package. An example project structure for a MyCorp web application is illustrated below: <blockquote>
+ <para>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="./../images/packages-classes.png" format="PNG"/>
+ </imageobject>
+ </inlinemediaobject>
+ </para>
+ </blockquote>
+ In this example application we use declarative role and path based security. All the pages in the <literal>admin</literal> package and directory require the <literal>"admin"</literal> role to be access, while all the pages in the <literal>user</literal> package and directory require the <literal>"user"</literal> role to be accessed. </para>
+ <sect2 remap="h4">
+ <title>Page Classes</title>
+ <para> A best practice when developing application Page classes is to place common methods in a base page class. This is typically used for providing access methods to application services and logger objects. For example the BasePage below provides access to Spring configured service objects and a Log4J logger object: <screen>
+
+public class BasePage
+extends Page
+implements ApplicationContextAware {
+
+
+/** The Spring application context. */
+
+protected ApplicationContext applicationContext;
+
+
+/** The page Logger instance. */
+
+protected Logger logger;
+
+
+/**
+ * Return the Spring configured Customer service.
+ *
+ * @return the Spring configured Customer service
+ */
+
+public CustomerService getCustomerService() {
+
+return (CustomerService) getBean(
+"customerService");
+ }
+
+
+/**
+ * Return the Spring configured User service.
+ *
+ * @return the Spring configured User service
+ */
+
+public UserService getUserService() {
+
+return (UserService) getBean(
+"userService");
+ }
+
+
+/**
+ * Return the page Logger instance.
+ *
+ * @return the page Logger instance
+ */
+
+public Logger getLogger() {
+
+if (logger ==
+null) {
+ logger = Logger.getLogger(getClass());
+ }
+
+return logger;
+ }
+
+
+/**
+ * @see ApplicationContextAware#setApplicationContext(ApplicationContext)
+ */
+
+public void setApplicationContext(ApplicationContext applicationContext) {
+ this.applicationContext = applicationContext;
+ }
+
+
+/**
+ * Return the configured Spring Bean for the given name.
+ *
+ * @param beanName the configured name of the Java Bean
+ * @return the configured Spring Bean for the given name
+ */
+
+public Object getBean(String beanName) {
+ return applicationContext.getBean(beanName);
+ }
+
+}
+</screen> Applications typically use a border template and have a <literal>BorderPage</literal> which extends <literal>BasePage</literal> and defines the template. For example: <screen>
+
+public class BorderPage
+extends BasePage {
+
+
+/** The root Menu item. */
+
+public Menu rootMenu =
+new Menu();
+
+
+/**
+ * @see Page#getTemplate()
+ */
+
+public String getTemplate() {
+
+return
+"/border-template.htm";
+ }
+}
+</screen> Most application pages subclass <literal>BorderPage</literal>, except AJAX pages which have no need for a HTML border template and typically extend <literal>BasePage</literal>. The <literal>BorderPage</literal> class should not include common logic, other than that required for rendering the border template. Common page logic should be defined in the <literal>BasePage</literal> class. To prevent these base Page classes being auto mapped, and becoming directly acessible web pages, ensure that there are no page templates which could match their class name. For example the <literal>BorderPage</literal> class above will not be auto mapped to border-template.htm. <anchor id="best-practices.html-automapping"/><indexterm>
+ <primary>automapping</primary>
+ </indexterm>
+</para>
+ </sect2>
+ </sect1>
+ <sect1 remap="h2">
+ <title>3. Page Auto Mapping</title>
+ <para> You should use the Click page automapping configuration feature. See the <ulink url="configuration.html#application-automapping">Page Automapping</ulink> topic for details. Automapping will save you from having to manually configure URL path to Page class mappings in your <literal>click.xml</literal> file. If you follow this convention it is very easy to maintain and refactor applications. You can also quickly determine what the corresponding Page class is for a page HTML template and visa versa, and if you use the ClickIDE Eclipse plugin you can switch between a page's class and template by pressing Ctrl+Alt+S. An example <literal>click.xml</literal> automapping configuration is provided below (automapping is enabled by default): <screen>
+<click-app>
+ <pages
+package="
+com.mycorp.dashboard.page"/>
+</click-app>
+</screen> To see how the page templates are mapped to Page classes set the application <ulink url="configuration.html#application-mode">mode</ulink> to <literal>debug</literal> and at startup the mappings will be listed out. An example Click startup listing is provided below: <screen>
+[Click] [debug] automapped pages:
+[Click] [debug] /category-tree.htm -> com.mycorp.dashboard.page.CategoryTree
+[Click] [debug] /process-list.htm -> com.mycorp.dashboard.page.ProcessList
+[Click] [debug] /user-list.htm -> com.mycorp.dashboard.page.UserList
+</screen><anchor id="best-practices.html-navigation"/><indexterm>
+ <primary>navigation</primary>
+ </indexterm>
+</para>
+ </sect1>
+ <sect1 remap="h2">
+ <title>4. Navigation</title>
+ <para> When navigating between Pages using forwards and redirects, you should refer to the target page using the Page class rather than using path. This provides you compile time checking and will save you from having to update path strings in Java code if you move pages about. To forward to another page using the Page class: <screen>
+
+public class CustomerListPage
+extends Page {
+
+
+public ActionLink customerLink =
+new ActionLink(
+this,
+"onCustomerClick");
+
+ ..
+
+
+public boolean onCustomerClick() {
+ Integer id = customerLink.getValueInteger();
+ Customer customer = getCustomerService().getCustomer(id);
+
+ CustomerDetailPage customerDetailPage = (CustomerDetailPage)
+ getContext().createPage(CustomerDetailPage.
+class);
+
+ customerDetailPage.setCustomer(customer);
+ setForward(customerDetailPage);
+
+
+return false;
+ }
+}
+</screen> To redirect to another page using the Page class you can obtain the pages path from the <literal>Context</literal>. In the example below we are passing through the customer id as a request parameter to the target page. <screen>
+
+public class CustomerListPage
+extends Page {
+
+
+public ActionLink customerLink =
+new ActionLink(
+this,
+"onCustomerClick");
+
+ ..
+
+
+public boolean onCustomerClick() {
+ String id = customerLink.getValueInteger();
+
+ String path = getContext().getPagePath(CustomerDetailPage.
+class);
+ setRedirect(path +
+"?id=" + id);
+
+
+return false;
+ }
+}
+</screen> A quick way of redirecting to another page is to simply refer to the target class. The example below logs a user out, by invalidating their session, and then redirects them to the applications home page. <screen>
+
+public boolean onLogoutClick() {
+ getContext().getSession().invalidate();
+
+ setRedirect(HomePage.
+class);
+
+
+return false;
+ }
+</screen><anchor id="best-practices.html-templating"/><indexterm>
+ <primary>templating</primary>
+ </indexterm>
+</para>
+ </sect1>
+ <sect1 remap="h2">
+ <title>5. Templating</title>
+ <para> Use Page templating it is highly recommended. Page templates provide numerous advantages including: <itemizedlist>
+ <listitem>
+ <para> greatly reduce the amount of HTML you need to maintain</para>
+ </listitem>
+ <listitem>
+ <para> ensure you have a common look and feel across your application</para>
+ </listitem>
+ <listitem>
+ <para> make global application changes very easy</para>
+ </listitem>
+ </itemizedlist>
+ To see how to use templates see the <ulink url="pages.html#page-templating">Page Templating</ulink> topic. Also see the Click <ulink url="examples.html">Examples</ulink> use of page templating. <anchor id="best-practices.html-menus"/><indexterm>
+ <primary>menus</primary>
+ </indexterm>
+</para>
+ </sect1>
+ <sect1 remap="h2">
+ <title>6. Menus</title>
+ <para> For many applications using the <ulink url="extras-api/org/apache/click/extras/control/Menu.html">Menu</ulink> control to centralize application navigation is very useful. Menus are defined in a <literal>WEB-INF/menu.xml</literal> file which is very easy to change. An menu is typically defined in the a page border template so they are available through out the application. The Menu control does not support HTML rendering, so you need to define a Velocity macro to programmatically render the menu. You would call the macro in your border template with code like this: <screen>
+
+#
+writeMenu(
+$rootMenu)
+</screen> An advantage of using a macro to render your menu is that you can reuse the code across different applications, and to modify an applications menu you simply need to edit the <literal>WEB-INF/menu.xml</literal> file. A good place to define your macros is in the webroot <literal>/macro.vm</literal> file as it is automatically included by Click. Using macros you can create dynamic menu behaviour such as only rendering menu items a user is authorized to access with <ulink url="extras-api/org/apache/click/extras/control/Menu.html#isUserInRoles()">isUserInRoles()</ulink>. <screen>
+
+#if (
+$menu.isUserInRoles())
+ ..
+
+#end
+</screen> You can also use JavaScript to add dynamic behaviour such as drop down menus, for example see the Menu page in Click <ulink url="examples.html">Examples</ulink>. <anchor id="best-practices.html-logging"/><indexterm>
+ <primary>logging</primary>
+ </indexterm>
+</para>
+ </sect1>
+ <sect1 remap="h2">
+ <title>7. Logging</title>
+ <para> For page logging you should use <ulink url="http://logging.apache.org/log4j/docs/">Log4j</ulink> library. An alternative library is the <ulink url="http://jakarta.apache.org/commons/logging/">Commons Logging</ulink>. If you are using Commons Logging please be aware that there have been class loader issues with this library on some application servers. If you are using Commons Logging please make sure you have the latest version. The best place to define your logger is in a common base page, for example: <screen>
+
+public class BasePage
+extends Page {
+
+
+protected Logger logger;
+
+
+public Logger getLogger() {
+
+if (logger ==
+null) {
+ logger = Logger.getLogger(getClass());
+ }
+
+return logger;
+ }
+}
+</screen> Using this pattern all your application bases should extend <literal>BasePage</literal> so they can use the <literal>getLogger()</literal> method. <screen>
+
+public class CustomerListPage
+extends BasePage {
+
+
+public void onGet() {
+
+try {
+ ..
+
+ }
+catch (Exception e) {
+ getLogger().error(e);
+ }
+ }
+}
+</screen> If you have some very heavy debug statement you should possibly use an <literal>isDebugEnabled</literal> switch so it is not invoked if debug is not required. <screen>
+
+public class CustomerListPage
+extends BasePage {
+
+
+public void onGet() {
+
+if (getLogger().isDebugEnabled()) {
+ String msg = ..
+
+ getLogger().debug(msg);
+ }
+
+ ..
+ }
+}
+</screen> Please note the Click logging facility is not designed for application use, and is for Click internal use only. When Click is running in <literal>production</literal> mode it will not produce any logging output. <anchor id="best-practices.html-error-handling"/><indexterm>
+ <primary>error-handling</primary>
+ </indexterm>
+</para>
+ </sect1>
+ <sect1 remap="h2">
+ <title>8. Error Handling</title>
+ <para> In Click unhandled errors are directed to the <ulink url="click-api/org/apache/click/util/ErrorPage.html">ErrorPage</ulink> for display. If applications require additional error handling they can create and register a custom error page in <literal>WEB-INF/click.xml</literal>. For example: <screen>
+<pages package="
+com.mycorp.page" automapping="true"/>
+ <page path="
+click/error.htm" classname="
+ErrorPage"/>
+</pages>
+</screen> Generally application handle transactional errors using service layer code or via a servlet <ulink url="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/Filter.html">Filter</ulink> and would not need to include error handling logic in an error page. Potential uses for a custom error page include custom logging. For example if an application requires unhandled errors to be logged to an application log (rather than System.out) then a custom <ulink url="click-api/org/apache/click/util/ErrorPage.html">ErrorPage</ulink> could be configured. An example <literal>ErrorPage</literal> error logging page is provided below: <screen>
+
+package com.mycorp.page.ErrorPage;
+..
+
+
+public class ErrorPage
+extends org.apache.click.util.ErrorPage {
+
+
+public void onDestory() {
+ Logger.getLogger(getClass()).error(getError());
+ }
+}
+</screen><anchor id="best-practices.html-performance"/><indexterm>
+ <primary>performance</primary>
+ </indexterm>
+</para>
+ </sect1>
+ <sect1 remap="h2">
+ <title>9. Performance</title>
+ <para> Yahoo published a list of <ulink url="http://developer.yahoo.com/performance/rules.html">best practices</ulink> for improving web application performance. Click Framework provides a <ulink url="extras-api/org/apache/click/extras/filter/PerformanceFilter.html">PerformanceFilter</ulink> which caters for some of these rules. However not all rules can be easily automated. This section will outline ways to apply rules which are not covered by the PerformanceFilter namely, <ulink url="http://developer.yahoo.com/performance/rules.html#num_http">#1 - Minimize HTTP Requests (by combining files)</ulink> and <ulink url="http://developer.yahoo.com/performance/rules.html#minify">#10 - Minify Javascript and CSS</ulink>. Rule #1 also mentions <ulink url="http://alistapart.com/articles/sprites">CSS Sprites</ulink>, a method for combining multiple images into a single master image. CSS Sprites is not covered here. It is worth pointing out that its not necessary to blindly optimi
ze every page in your application. Instead concentrate on popular pages, for example a web site's <emphasis>Home Page</emphasis> would be a good candidate. There are a couple of tools that are useful in applying Rule #1 and #10: <itemizedlist>
+ <listitem>
+ <para><ulink url="http://developer.yahoo.com/yui/compressor/">YUICompressor</ulink> - minifies and compresses JavaScript and CSS files so less bytes have to be transferred across the wire.</para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://code.google.com/p/javaflight-code/">Ant Task for YUICompressor</ulink> - an Ant task that uses YUICompressor to compress JavaScript and CSS files.</para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://www.crockford.com/javascript/jsmin.html">JSMin</ulink> - similar to YUICompressor but only minifies (remove whitespace and newlines) JavaScript files and does no compression at all. An advantage of JSMin over YUICompressor is that its faster and can be used at runtime to minify JavaScript, while YUICompressor is most often used at build time.</para>
+ </listitem>
+ </itemizedlist>
+ Below are some articles outlining how to use YUICompressor and Ant to concatenate and compress JavaScript and CSS files: <itemizedlist>
+ <listitem>
+ <para><ulink url="http://www.julienlecomte.net/blog/2007/09/16/">Article</ulink> explaining how to use Ant and YUICompressor for compression.</para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://javaflight.blogspot.com/2008/01/introducing-yui-compressor-ant-task.html">Article</ulink> outlining how to use a special YUICompressor Ant Task for compression.</para>
+ </listitem>
+ </itemizedlist>
+ Using one of the approaches above you can concatenate and compress all JavaScript and CSS for your Pages into two separate files, for example <literal>home-page.css</literal> and <literal>home-page.js</literal>. Note that the two files must include all the JavaScript and CSS that is generated by the Page and its Controls. Then you can instruct Click to <emphasis>only</emphasis> include the two compressed files, home-page.css and home-page.js. Click makes use of the utility class <ulink url="click-api/org/apache/click/util/PageImports.html">PageImports</ulink> to include the CSS and JavaScript. PageImports exposes the method <ulink url="click-api/org/apache/click/util/PageImports.html#setInitialized(boolean)">setInitialized(boolean)</ulink>, which controls when PageImports are fully initialized. Once PageImports have been initialized, no other CSS and JavaScript will be included. Knowing this one can override <ulink url="click-api/org/apache/click/Page.html#getPageImports()"
>Page.getPageImports()</ulink>, and import the necessary JavaScript and CSS files and then set PageImports to <literal>initialized</literal>, forcing PageImports to skip other CSS and JavaScript files. Here is an example: <screen>
+ public class HomePage extends Page {
+
+ private Form form = new Form("form");
+
+ public void onInit() {
+ form.add(new EmailField("email");
+ addControl(form);
+ }
+
+ public void getPageImports () {
+ PageImports pageImports = super.getPageImports();
+ String contextPath = getContext().getRequest().getContextPath();
+
+ String cssInclude = contextPath + "/assets/css/home-page.css";
+ pageImports.addImport("<link type=\"text/javascript\" href=\"" + cssInclude + "\"/>");
+
+ String jsInclude = contextPath + "/assets/js/home-page.js";
+ pageImports.addImport("<script type=\"text/javascript\" src=\"" + jsInclude + "\"></script>");
+
+ // Set pageImports to initialized so that no other CSS and JavaScript files will be included.
+ pageImports.setInitialized(true);
+ }
+}
+</screen> Using the following <literal>border-template.htm</literal>: <screen>
+<html>
+ <head>
+ <title>Click Examples</title>
+ ${cssImports}
+ </head>
+ <body>
+
+ ...
+
+ ${jsImports}
+ </body>
+</html>
+</screen> the rendered HTML will include one CSS and one JavaScript import: <screen>
+<html>
+ <head>
+ <title>Click Examples</title>
+ <link type="text/css" rel="stylesheet" href="/click-examples/assets/css/home-page.css" title="Style"/>
+ </head>
+ <body>
+
+ ...
+
+ <script type="text/javascript" src="/click-examples/assets/js/home-page.js"></script>
+ </body>
+</html>
+</screen> A live demo is available <ulink url="http://www.avoka.com/click-examples/general/page-imports-example.htm">here</ulink></para>
+ </sect1>
+ </chapter>
+
Modified: incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml?rev=736438&r1=736437&r2=736438&view=diff
==============================================================================
--- incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml (original)
+++ incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml Wed Jan 21 14:10:25 2009
@@ -1,10 +1,702 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="chapter-configuration">
- <title>Configuration</title>
-
- <section id="section-servlet-configuration">
- <title>Servlet Configuration</title>
-
- </section>
-
-</chapter>
\ No newline at end of file
+<?xml version='1.0' encoding='UTF-8'?>
+ <chapter remap="h1">
+ <title>Configuration</title>
+ <para> This section discusses how to setup and configure a Click web application and covers the following topics: </para>
+ <orderedlist>
+ <listitem>
+ <para><link linkend="configuration.html-servlet-configuration">Servlet Configuration</link> - how to setup the ClickServlet</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="configuration.html-application-configuration">Application Configuration</link> - how to configure the Click application descriptor</para>
+ </listitem>
+ <listitem>
+ <para><link linkend="configuration.html-auto-deployed-files">Auto Deployed Files</link> - automatically deployed Click files</para>
+ </listitem>
+ </orderedlist>
+ <para>Â </para>
+ <para> The Click configuration files include: </para>
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="50*"/>
+ <colspec colname="c2" colwidth="50*"/>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="./../images/config-files.png" format="PNG"/>
+ </imageobject>
+ </inlinemediaobject>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para> WEB-INF/<link linkend="configuration.html-application-configuration">click.xml</link> Â - Â Application Configuration (<emphasis role="bold">required</emphasis>)</para>
+ </listitem>
+ <listitem>
+ <para> WEB-INF/<link linkend="configuration.html-servlet-configuration">web.xml</link> Â - Â Servlet Configuration (<emphasis role="bold">required</emphasis>)</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ <anchor id="configuration.html-servlet-configuration"/>
+ </para>
+ <indexterm>
+ <primary>servlet-configuration</primary>
+ </indexterm>
+ <sect1 remap="h2">
+ <title>1. Servlet Configuration</title>
+ <para> For a Click web application to function the <ulink url="click-api/org/apache/click/ClickServlet.html">ClickServlet</ulink> must be configured in the web application's <literal>/WEB-INF/web.xml</literal> file. A basic web application which maps all <literal>*.htm</literal> requests to a ClickServlet is provided below. <screen>
+<web-app>
+
+ <servlet>
+ <servlet-name>
+ClickServlet</servlet-name>
+ <servlet-class>
+org.apache.click.ClickServlet</servlet-class>
+ <load-on-startup>
+0</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>
+ClickServlet</servlet-name>
+ <url-pattern>
+*.htm</url-pattern>
+ </servlet-mapping>
+
+</web-app>
+</screen></para>
+ <sect2 remap="h3">
+ <title>1.1Â Servlet Mapping</title>
+ <para> 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. </para>
+ </sect2>
+ <sect2 remap="h3">
+ <title>1.2Â Load On Startup</title>
+ <para> Note you should always set <literal>load-on-startup</literal> 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. The <literal>ClickServlet</literal> 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 "<literal>click.xml</literal>" config file, covered next. <anchor id="configuration.html-application-configuration"/><indexterm>
+ <primary>application-configuration</primary>
+ </indexterm>
+</para>
+ </sect2>
+ </sect1>
+ <sect1 remap="h2">
+ <title>2. Application Configuration</title>
+ <para> The heart of a Click application is the <literal>click.xml</literal> configuration file. This file specifies the application pages, headers, the format object and the applications mode. By default the ClickServlet will attempt to load the application configuration file using the path: Â <literal>/WEB-INF/click.xml</literal> If this file is not found under the <literal>WEB-INF</literal> directory, then ClickServlet will attempt to load it from the classpath as <literal>/click.xml</literal>. See <ulink url="click-dtd.html">Click DTD</ulink> for the click-app XML definition. A complete Click configuration example is available <ulink url="click-dtd-example.html">here</ulink> which can be used as a quick reference when configuring Click. A basic Click app config file is provided below: <screen>
+<click-app>
+
+ <pages package="com.mycorp.page"/>
+
+ <mode value="profile"/>
+
+</click-app>
+</screen> An example of an advanced config file is: <screen>
+<click-app charset="UTF-8" locale="de">
+
+ <pages package="com.mycorp.banking.page">
+ <page path="index.htm" classname="com.mycorp.page.Home"/>
+ </pages>
+
+ <pages package="com.mycorp.common.page"/>
+
+ <format classname="com.mycorp.util.Format"/>
+
+ <mode value="profile"/>
+
+ <log-service classname="org.apache.click.extras.service.Log4JLogService"/>
+
+</click-app>
+</screen><anchor id="configuration.html-application-click-app"/><indexterm>
+ <primary>application-click-app</primary>
+ </indexterm>
+</para>
+ <sect2 remap="h3">
+ <title>2.1Â Click App</title>
+ <para> The root click-app element defines two application localization attributes charset and locale. <screen>
+<!ELEMENT
+click-app (pages*, headers?, format?, mode?, controls?,
+ file-upload-service?, log-service?, template-service?)>
+ <!ATTLIST click-app
+charset CDATA #IMPLIED>
+ <!ATTLIST click-app
+locale CDATA #IMPLIED>
+</screen> The charset attribute defines the character encoding set for: <itemizedlist>
+ <listitem>
+ <para> Velocity templates</para>
+ </listitem>
+ <listitem>
+ <para> HttpServletRequest character encoding</para>
+ </listitem>
+ <listitem>
+ <para> Page Content-Type charset, see Page <ulink url="click-api/org/apache/click/Page.html#getContentType()">getContentType()</ulink></para>
+ </listitem>
+ </itemizedlist>
+ The locale attribute defines the default application Locale. If this value is defined it will override Locale returned by the request. Please see the Context <ulink url="click-api/org/apache/click/Context.html#getLocale()">getLocale()</ulink> for details. For example the folliwing configuration sets the application character set to UTF-8 and the default Locale as German (de): <screen>
+<click-app
+charset="
+UTF-8"
+locale="
+de">
+ ..
+</click-app>
+</screen><anchor id="configuration.html-application-pages"/><indexterm>
+ <primary>application-pages</primary>
+ </indexterm>
+</para>
+ </sect2>
+ <sect2 remap="h3">
+ <title>2.2Â Pages</title>
+ <para> The first child element of the click-app is the mandatory <literal>pages</literal> element which defines the list of Click pages. <screen>
+<!ELEMENT
+pages (
+page*)>
+ <!ATTLIST pages
+package CDATA #IMPLIED>
+ <!ATTLIST pages
+automapping (true|false) "true">
+ <!ATTLIST pages
+autobinding (true|false) "true">
+</screen> The pages element can specify a default package name which is prepended to the classname of any pages defined. The pages element also defines the automapping attribute which is discussed in the <link linkend="configuration.html-application-automapping">Page Automapping</link> topic. <anchor id="configuration.html-application-multi-packages"/><indexterm>
+ <primary>application-multi-packages</primary>
+ </indexterm>
+</para>
+ <sect3 remap="h4">
+ <title>2.2.1Â Multiple Pages Packages</title>
+ <para> Click can support multiple pages elements to enable the automapping of multiple packages. <screen>
+<click-app>
+
+ <pages package="com.mycorp.banking.page"/>
+
+ <pages package="com.mycorp.common.page"/>
+
+</click-app>
+</screen> 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. <anchor id="configuration.html-application-page"/><indexterm>
+ <primary>application-page</primary>
+ </indexterm>
+</para>
+ </sect3>
+ </sect2>
+ <sect2 remap="h3">
+ <title>2.3Â Page</title>
+ <para> The page element defines the Click application pages. <screen>
+<!ELEMENT
+page (
+header*)>
+ <!ATTLIST page
+path CDATA #REQUIRED>
+ <!ATTLIST page
+classname CDATA #REQUIRED>
+</screen> Each page path must be unique, as the Click application maps HTTP requests to the page paths. The Click application will create a new Page instance for the given request using the configured page classname. All pages must subclass <ulink url="click-api/org/apache/click/Page.html">Page</ulink> and provide a public no arguments constructor, so they can be instantiated. Pages can also define header values which are discussed in the next topic. 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 <literal>ERROR</literal> message and throw an <ulink url="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/UnavailableException.html">UnavailableException</ulink>. If this occurs the click application will be permanently unavailable until the error is fixed and the web app is restarted. <anchor id="configuration.html-application-automapping"/><indexterm>
+ <primary>application-automapping</primary>
+ </indexterm>
+</para>
+ <sect3 remap="h4">
+ <title>2.3.1Â Page Automapping</title>
+ <para> 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. 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. For example given a page path to class mapping: <screen>
+
+index.htm =>
+com.mycorp.page.Home
+
+search.htm =>
+com.mycorp.page.Search
+
+contacts/contacts.htm =>
+com.mycorp.page.contacts.Contacts
+
+security/login.htm =>
+com.mycorp.page.security.Login
+
+security/logout.htm =>
+com.mycorp.page.security.Logout
+
+security/change-password.htm =>
+com.mycorp.page.security.ChangePassword
+</screen> This could be configured manually by setting the automapping attribute to "false" and using the package prefix, for example: <screen>
+<click-app>
+ <pages package="
+com.mycorp.page"
+automapping="
+false">
+ <page path="
+index.htm" classname="
+Home"/>
+ <page path="
+search.htm" classname="
+Search"/>
+ <page path="
+contacts/contacts.htm" classname="
+contacts.Contacts"/>
+ <page path="
+security/login.htm" classname="
+security.Login"/>
+ <page path="
+security/logout.htm" classname="
+security.Logout"/>
+ <page path="
+security/change-password.htm" classname="
+security.ChangePassword"/>
+ </pages>
+</click-app>
+</screen> Using automapping you only need to define the Home page which doesn't automatically map to index.html. <screen>
+<click-app>
+ <pages package="
+com.mycorp.page"
+automapping="
+true">
+ <page path="
+index.htm" classname="
+Home"/>
+ </pages>
+</click-app>
+</screen> Note automapping is true by default, so it could be omitted from the configuration file. The page template name to classname convention is: <screen>
+change-password.htm => ChangePassword
+change_password.htm => ChangePassword
+changePassword.htm => ChangePassword
+ChangePassword.htm => ChangePassword
+</screen> 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: <screen>
+customer.htm => CustomerPage
+change-password.htm => ChangePasswordPage
+</screen><anchor id="configuration.html-application-excludes"/><indexterm>
+ <primary>application-excludes</primary>
+ </indexterm>
+</para>
+ </sect3>
+ <sect3 remap="h4">
+ <title>2.3.2Â Automapping Excludes</title>
+ <para> With Page automapping there can be resources where you don't want automapping applied. For example when using a JavaScript library with lots of <literal>.htm</literal> 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 <literal>excludes</literal> element. <screen>
+<!ELEMENT
+excludes (#PCDATA)>
+ <!ATTLIST excludes
+pattern CDATA #REQUIRED>
+</screen> For example if our application uses the TinyMCE JavaScript library we could configure our pages automapping to exclude all <literal>.htm</literal> files under the <literal>/tiny_mce</literal> directory. <screen>
+<click-app>
+ <pages package="com.mycorp.page">
+ <
+excludes pattern="
+/tiny_mce/*"/>
+ </pages>
+</click-app>
+</screen> The excludes pattern can specify multiple directories or files using a comma separated notation. For example: <screen>
+<click-app>
+ <pages package="com.mycorp.page">
+ <
+excludes pattern="
+/dhtml/*, /tiny_mce/*, banner.htm, about.htm"/>
+ </pages>
+</click-app>
+</screen> HTM files excluded from Page automapping are handled by an internal Page class with caching headers enabled. <anchor id="configuration.html-application-autobinding"/><indexterm>
+ <primary>application-autobinding</primary>
+ </indexterm>
+</para>
+ </sect3>
+ <sect3 remap="h4">
+ <title>2.3.3Â Page Autobinding</title>
+ <para> By default all pages have autobinding enabled. With autobinding enabled the ClickServlet will automatically: <itemizedlist>
+ <listitem>
+ <para> add any public controls to the page, after the page constructor has been invoked</para>
+ </listitem>
+ <listitem>
+ <para> if the public control's name is not defined, its name will be set to the the value its field name</para>
+ </listitem>
+ <listitem>
+ <para> bind any request parameters to public page fields, after page constructor has been invoked. See <ulink url="click-api/org/apache/click/ClickServlet.html#processPageRequestParams(org.apache.click.Page)">ClickServlet.processPageRequestParams(Page)</ulink> for more details</para>
+ </listitem>
+ <listitem>
+ <para> add any public page fields to the page model, before rendering</para>
+ </listitem>
+ </itemizedlist>
+ For example: <screen>
+public class EmployeePage extends Page {
+
+ public Form employeeForm = new Form();
+
+ public Table myTable = new Table();
+
+}
+</screen> In the example above the employeeForm and myTable controls were not added to the page. Also note that Form and Table does not have their names defined. When autobinding is enabled, ClickServlet will create a new Page and add the public controls to the page. In the example above the employeeForm and myTable will be added to the page, as if you had invoked, <emphasis>addControl(employeeForm)</emphasis> and <emphasis>addControl(myTable)</emphasis>. 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 employeeForm while the Table name will set to myTable. The above example is thus a shorthand way of writing the following: <screen>
+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);
+ }
+}
+</screen> You can turn this behaviour off by setting the autobinding attribute to false, for example: <screen>
+<click-app>
+ <pages package="com.mycorp.page"
+autobinding="
+false"/>
+</click-app>
+</screen><anchor id="configuration.html-application-headers"/><indexterm>
+ <primary>application-headers</primary>
+ </indexterm>
+</para>
+ </sect3>
+ </sect2>
+ <sect2 remap="h3">
+ <title>2.4Â Headers</title>
+ <para> The optional <literal>headers</literal> element defines a list of <literal>header</literal> elements which are applied to all pages. <screen>
+<!ELEMENT
+headers (
+header*)>
+</screen> The <literal>header</literal> element defines header name and value pairs which are applied to the <ulink url="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/http/HttpServletResponse.html">HttpServletResponse</ulink>. <screen>
+<!ELEMENT
+header (#PCDATA)>
+ <!ATTLIST header
+name CDATA #REQUIRED>
+ <!ATTLIST header
+value CDATA #REQUIRED>
+ <!ATTLIST header
+type (String|Integer|Date) "String">
+</screen> Page headers are set after the Page has been constructed and before <literal>onInit()</literal> is called. Pages can then modify their <ulink url="click-api/org/apache/click/Page.html#headers">headers</ulink> property using the <ulink url="click-api/org/apache/click/Page.html#setHeader(java.lang.String,%20java.lang.Object)">setHeader()</ulink> method. </para>
+ <sect3 remap="h4">
+ <title>2.4.1Â Browser Caching</title>
+ <para> 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 <literal>headers</literal> element in your application: <screen>
+<click-app>
+ <pages>
+ ..
+ </pages>
+ <headers>
+ <header name="
+Pragma" value="
+no-cache"/>
+ <header name="
+Cache-Control"
+ value="
+no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/>
+ <header name="
+Expires" value="
+1" type="
+Date"/>
+ </headers>
+</click-app>
+</screen> 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: <screen>
+<page path="
+login.htm" classname="
+com.mycorp.page.Login">
+ <header name="
+Pragma" value="
+no-cache"/>
+ <header name="
+Expires" value="
+1" type="
+Date"/>
+</page>
+</screen> 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. <screen>
+<page path="
+home.htm" classname="
+com.mycorp.page.Home">
+ <header name="
+Cache-Control" value="
+max-age=3600, public, must-revalidate"/>
+</page>
+</screen> To apply header values globally define header values in the headers element. For example: <screen>
+<click-app>
+ <pages>
+ ..
+ </pages>
+ <headers>
+ <header name="
+Pragma" value="
+no-cache"/>
+ <header name="
+Cache-Control"
+ value="
+no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/>
+ <header name="
+Expires" value="
+1" type="
+Date"/>
+ </headers>
+</click-app>
+</screen><anchor id="configuration.html-application-format"/><indexterm>
+ <primary>application-format</primary>
+ </indexterm>
+</para>
+ </sect3>
+ </sect2>
+ <sect2 remap="h3">
+ <title>2.5Â Format</title>
+ <para> The optional <literal>format</literal> element defines the Format object classname which is applied to all pages. <screen>
+<!ELEMENT
+format (#PCDATA)>
+ <ATTLIST format classname CDATA #FIXED "org.apache.click.util.Format">
+</screen> By default all Click pages are configured with a <ulink url="click-api/org/apache/click/util/Format.html">org.apache.click.util.Format</ulink> object. The format object is made available in the Velocity page templates using the name <literal>$format</literal>. To specify a custom format class configure a <literal>format</literal> element in the click-app descriptor. For example: <screen>
+<click-app>
+ ..
+ <
+format classname="
+com.mycorp.util.CustomFormat"/>
+</click-app>
+</screen><anchor id="configuration.html-application-mode"/><indexterm>
+ <primary>application-mode</primary>
+ </indexterm>
+</para>
+ </sect2>
+ <sect2 remap="h3">
+ <title>2.6Â Mode</title>
+ <para> The optional <literal>mode</literal> element defines the application logging and caching mode. <screen>
+<!ELEMENT mode (#PCDATA)>
+ <ATTLIST mode value (
+production|
+profile|
+development|
+debug|
+trace) "development">
+</screen> By default Click applications run in <literal>development</literal> mode, which switches off page template caching, and the logging level is set to <literal>INFO</literal>. To change the default application mode configure a mode element in the click-app descriptor. For example to specify <literal>production</literal> mode you would add the following mode element: <screen>
+<click-app>
+ ..
+ <
+mode value="
+production">
+</click-app>
+</screen> The application mode configuration can be overridden by setting the system property <literal>"click.mode"</literal>. This can be use in the scenario of debugging a problem on a production system, where you change the mode to <literal>trace</literal> by setting the following system property and restarting the application. <screen>
+-Dclick.mode=trace
+</screen> The Click Application modes and their settings for Page auto loading, template caching and logging levels are: <informaltable frame="none">
+ <tgroup cols="5">
+ <colspec colname="c1" colwidth="20*"/>
+ <colspec colname="c2" colwidth="20*"/>
+ <colspec colname="c3" colwidth="20*"/>
+ <colspec colname="c4" colwidth="20*"/>
+ <colspec colname="c5" colwidth="20*"/>
+ <tbody>
+ <row>
+ <entry align="center" valign="middle">
+ <para>
+ <emphasis role="bold">Application mode</emphasis>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>
+ <emphasis role="bold">Page auto loading</emphasis>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>
+ <emphasis role="bold">Template caching</emphasis>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>
+ <emphasis role="bold">Click logging level</emphasis>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>
+ <emphasis role="bold">Velocity logging level</emphasis>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry align="center" valign="middle">
+ <para>
+ <literal>production</literal>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>No</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>Yes</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>WARN</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>ERROR</para>
+ </entry>
+ </row>
+ <row>
+ <entry align="center" valign="middle">
+ <para>
+ <literal>profile</literal>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>No</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>Yes</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>INFO</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>ERROR</para>
+ </entry>
+ </row>
+ <row>
+ <entry align="center" valign="middle">
+ <para>
+ <literal>development</literal>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>Yes</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>No</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>INFO</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>ERROR</para>
+ </entry>
+ </row>
+ <row>
+ <entry align="center" valign="middle">
+ <para>
+ <literal>debug</literal>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>Yes</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>No</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>DEBUG</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>ERROR</para>
+ </entry>
+ </row>
+ <row>
+ <entry align="center" valign="middle">
+ <para>
+ <literal>trace</literal>
+ </para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>Yes</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>No</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>TRACE</para>
+ </entry>
+ <entry align="center" valign="middle">
+ <para>WARN</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+<anchor id="configuration.html-page-auto-loading"/><indexterm>
+ <primary>page-auto-loading</primary>
+ </indexterm>
+</para>
+ <sect3 remap="h4">
+ <title>2.6.1Â Page Auto Loading</title>
+ <para> When Page Auto Loading is enabled any new page templates and classes will be automatically loaded at runtime. These pages are loaded using the <link linkend="configuration.html-application-automapping">Page Automapping</link> rules. 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. <anchor id="configuration.html-click-logging"/><indexterm>
+ <primary>click-logging</primary>
+ </indexterm>
+</para>
+ </sect3>
+ <sect3 remap="h4">
+ <title>2.6.2Â Click and Velocity Logging</title>
+ <para> The Click and Velocity runtimes use <ulink url="click-api/org/apache/click/service/LogService.html">LogService</ulink> for logging messages. The default LogService implementation is <ulink url="click-api/org/apache/click/service/ConsoleLogService.html">ConsoleLogService</ulink> 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 <literal>trace</literal>: <screen>
+[Click] [debug] GET http://localhost:8080/quickstart/home.htm
+[Click] [trace] invoked: HomePage.<<init>>
+[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
+</screen> Any unhandled <literal>Throwable</literal> errors are logged by the ClickServlet. Note that Click Extras also provide log adaptors for <ulink url="extras-api/org/apache/click/extras/service/Log4JLogService.html">Log4J</ulink> and the <ulink url="extras-api/org/apache/click/extras/service/JdkLogService.html">JDK Logging API</ulink>. When an application is not in <literal>production</literal> mode the error page displays detailed debugging information. When the application mode is <literal>production</literal> no debug information is displayed to prevent sensitive information being revealed. This behaviour can be changed by modifying the deployed <literal>click/error.htm</literal> page template. <anchor id="configuration.html-application-controls"/><indexterm>
+ <primary>application-controls</primary>
+ </indexterm>
+</para>
+ </sect3>
+ </sect2>
+ <sect2 remap="h3">
+ <title>2.7Â Controls</title>
+ <para> The optional <literal>controls</literal> element defines a list of <literal>control</literal> elements which will be deployed on application startup. <screen>
+<!ELEMENT
+controls (
+control*)>
+</screen> The <literal>control</literal> registers <ulink url="click-api/org/apache/click/Control.html">Control</ulink> classes which will have their <ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink> method invoked when the click application starts. <screen>
+<!ELEMENT
+control (#PCDATA)>
+ <!ATTLIST control
+classname CDATA #REQUIRED>
+</screen> For example to have a <literal>CustomField</literal> control deploy its resources on application startup, you would add the following elements to your <literal>click.xml</literal> file: <screen>
+<click-app>
+ ..
+
+ <controls>
+ <
+control classname=
+"com.mycorp.control.CustomField"/>
+ </controls>
+</click-app>
+</screen><anchor id="configuration.html-auto-deployed-files"/><indexterm>
+ <primary>auto-deployed-files</primary>
+ </indexterm>
+</para>
+ </sect2>
+ </sect1>
+ <sect1 remap="h2">
+ <title>3. Auto Deployed Files</title>
+ <para> To make pre-configured resources (templates, stylesheets, etc.) available to web applications, Click automatically deploys configured classpath resources to the <literal>/click</literal> directory at startup (if not already present). You can modify these support files and Click will <emphasis role="bold">not</emphasis> overwrite them. These files include: <itemizedlist>
+ <listitem>
+ <para> click/error.htm  -  the Page <ulink url="pages.html#page-error-handling">Error Handling</ulink> template</para>
+ </listitem>
+ <listitem>
+ <para> click/control.css  -  the Controls cascading stylesheet</para>
+ </listitem>
+ <listitem>
+ <para> click/control.js  -  the Controls JavaScript library</para>
+ </listitem>
+ <listitem>
+ <para> click/not-found.htm  -  the <ulink url="pages.html#page-not-found">Page Not Found</ulink> template</para>
+ </listitem>
+ </itemizedlist>
+ 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 <emphasis>Admin Console > server node > Web Applications</emphasis> tab and check the <emphasis>Archived Real Path Enabled</emphasis> parameter. If Click cannot deploy resources because of restricted file system permissions, warning messages will be logged. 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. <anchor id="configuration.html-deploying-custom-resources"/><indexterm>
+ <primary>deploying-custom-resources</primary>
+ </indexterm>
+</para>
+ <sect2 remap="h3">
+ <title>3.1Â Deploying Custom Resources</title>
+ <para> Click supports two ways of deploying pre-configured resources (templates, stylesheets, JavaScript etc.) from a Jar to a web applications. <orderedlist>
+ <listitem>
+ <para> Through a Control's <ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink> event handler. See the <link linkend="configuration.html-application-controls">Controls</link> section above.</para>
+ </listitem>
+ <listitem>
+ <para> By packaging the resources (stylesheets, JavaScript, Images etc.) into a special folder called <emphasis>'META-INF/web'</emphasis>.</para>
+ </listitem>
+ </orderedlist>
+ As option #1 was already discussed above in section <link linkend="configuration.html-application-controls">2.7 Controls</link>, lets look at option #2. 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.) Click will then copy all files found under 'META-INF/web/' to the web application folder. For example, given a Jar file with the following entries: <itemizedlist>
+ <listitem>
+ <para> META-INF/web/mycorp/edit_customer.js</para>
+ </listitem>
+ <listitem>
+ <para> META-INF/web/mycorp/edit_customer.css</para>
+ </listitem>
+ <listitem>
+ <para> mycorp/pages/EditCustomerPage.class</para>
+ </listitem>
+ </itemizedlist>
+ Click will copy the files <emphasis>'/mycorp/edit_customer.js'</emphasis> and <emphasis>'/mycorp/edit_customer.css'</emphasis> to the web application folder. Thus if the web application is called 'webapp', the files will be deployed as <emphasis>'webapp/mycorp/edit_customer.js'</emphasis> and <emphasis>'webapp/mycorp/edit_customer.css'</emphasis>. Option #2 is especially useful when you need to deploy a large number of resources from a Jar. Note, only Jars placed under the <emphasis>'WEB-INF/lib'</emphasis> folder will be deployed. </para>
+ </sect2>
+ </sect1>
+ </chapter>