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/02/17 17:53:14 UTC
svn commit: r745145 [1/6] - in /incubator/click/trunk/tools/docbook/src:
docbook/click/ images/ images/best-practices/ images/configuration/
images/controls/ images/introduction/ images/pages/ resources/
Author: sabob
Date: Tue Feb 17 16:53:13 2009
New Revision: 745145
URL: http://svn.apache.org/viewvc?rev=745145&view=rev
Log:
formatted docbook source, customized pdf and html output and added diagrams
Added:
incubator/click/trunk/tools/docbook/src/images/best-practices/
incubator/click/trunk/tools/docbook/src/images/best-practices/packages-classes.png (with props)
incubator/click/trunk/tools/docbook/src/images/configuration/
incubator/click/trunk/tools/docbook/src/images/configuration/config-files.png (with props)
incubator/click/trunk/tools/docbook/src/images/controls/
incubator/click/trunk/tools/docbook/src/images/controls/container-package-class-diagram.png (with props)
incubator/click/trunk/tools/docbook/src/images/controls/control-class-diagram.png (with props)
incubator/click/trunk/tools/docbook/src/images/controls/control-package-class-diagram.png (with props)
incubator/click/trunk/tools/docbook/src/images/controls/control-post-sequence-diagram.png (with props)
incubator/click/trunk/tools/docbook/src/images/external.png (with props)
incubator/click/trunk/tools/docbook/src/images/introduction/hello-world-screenshot.png (with props)
incubator/click/trunk/tools/docbook/src/images/pages/
incubator/click/trunk/tools/docbook/src/images/pages/activity-diagram-small.png (with props)
incubator/click/trunk/tools/docbook/src/images/pages/click-class-diagram.png (with props)
incubator/click/trunk/tools/docbook/src/images/pages/get-sequence-diagram.png (with props)
incubator/click/trunk/tools/docbook/src/images/pages/home-page-screenshot.png (with props)
incubator/click/trunk/tools/docbook/src/resources/
incubator/click/trunk/tools/docbook/src/resources/LICENSE.txt
incubator/click/trunk/tools/docbook/src/resources/post-sequence-diagram.png (with props)
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-introduction.xml
incubator/click/trunk/tools/docbook/src/docbook/click/chapter-pages.xml
incubator/click/trunk/tools/docbook/src/docbook/click/click-book.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=745145&r1=745144&r2=745145&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 Tue Feb 17 16:53:13 2009
@@ -1,621 +1,925 @@
<?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>
+<!--
+ 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.
+-->
+<chapter id="chapter-best-practices" 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="security">Security</link> - use JEE role based security
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="packages-classes">Packages and Classes</link> - project
+ package structures and page classes
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="automapping">Page Auto Mapping</link> - use
+ Convention over Configuration
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="navigation">Navigation</link> - use Page classes
+ to forward and redirect
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="templating">Templating</link> - to standardize your
+ web application
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="menus">Menus</link> - centralize your page navigation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="logging">Logging</link> - use Log4j in a base page
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="error-handling">Error Handling</link> - use custom
+ error page
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="performance">Performance</link> - enhancing page
+ performance
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <sect1 id="security" remap="h2">
+ <title>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 <methodname>onSecurityCheck()</methodname> method for rolling your own
+ programatic security model, the declarative JEE model provides numerous
+ advantages.
+ </para>
+
+ <para>These advantages include:
+ </para>
+
+ <itemizedlist>
<listitem>
- <para><link linkend="best-practices.html-menus">Menus</link> - centralize your page navigation</para>
+ <para> Its an industry standard pattern making development and maintenance
+ easier.
+ </para>
</listitem>
<listitem>
- <para><link linkend="best-practices.html-logging">Logging</link> - use Log4j in a base page</para>
+ <para> Application servers generally provide numerous ways of integration
+ with an organisations security infrastructure, including LDAP directories
+ and relational databases.
+ </para>
</listitem>
<listitem>
- <para><link linkend="best-practices.html-error-handling">Error Handling</link> - use custom error page</para>
+ <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><link linkend="best-practices.html-performance">Performance</link> - enhancing page performance</para>
+ <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>
- </orderedlist>
- <para>Â </para>
- <para>
- <anchor id="best-practices.html-security"/>
+ </itemizedlist>
+
+ <para>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>
- <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>
+
+ <sect2 id="declarative-security" 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.
+ </para>
+
+ <para>
+ For example to secure admin pages, you add a security
+ constraint in your <filename>web.xml</filename> file. This requires users
+ to be in the <varname>admin</varname> role before they can access to any
+ resources under the <symbol>admin</symbol> directory:
+ </para>
+
+ <programlisting><security-constraint>
<web-resource-collection>
- <web-resource-name>admin</web-resource-name>
- <url-pattern>
-/admin/*</url-pattern>
+ <web-resource-name>admin</web-resource-name>
+ <url-pattern><symbol>/admin/*</symbol></url-pattern>
</web-resource-collection>
<auth-constraint>
- <role-name>
-admin</role-name>
+ <role-name><varname>admin</varname></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>
+</security-constraint></programlisting>
+
+ <para>The application user roles are defined in the <filename>web.xml</filename>
+ file as <literal>security-role</literal> elements:
+ </para>
+
+ <programlisting><security-role>
+ <role-name><varname>admin</varname></role-name>
+</security-role></programlisting>
+
+ <para>The Servlet security model supports three different authentication method:</para>
+
+ <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>
+
+ <para>The authentication method is specified in the <login-method> element.
+ For example to use the BASIC authentication method you would specify:
+ </para>
+
+ <programlisting><login-config>
+ <auth-method><varname>BASIC</varname></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>
+</login-config></programlisting>
+
+ <para>To use the FORM method you also need to specify the path to the login
+ page and the login error page:
+ </para>
+
+ <programlisting><login-config>
+ <auth-method><varname>FORM</varname></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-page><symbol>/login.htm</symbol></form-login-page>
+ <form-error-page><symbol>/login.htm?auth-error=true</symbol></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>
+</login-config></programlisting>
-#if ($request.getParameter(
-"auth-error"))
-<div style="margin-bottom:1em;margin-top:1em;color:red;">
+ <para>In your Click <filename>login.htm</filename> page you need to include a
+ special <varname>j_security_check</varname> form which includes the input
+ fields <varname>j_username</varname> and <varname>j_password</varname>.
+ For example:
+ </para>
+
+ <programlisting><!-- login.htm -->
+<command>#if</command> ($request.getParameter("<symbol>auth-error</symbol>"))
+<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>
+<command>#end</command>
-#end
-
-<form method="POST" action="
-j_security_check" name="form">
-<table border="0" style="margin-left:0.25em;">
+<form method="POST" action="<varname>j_security_check</varname>" 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><label>User Name</label><font color="red">*</font></td>
+ <td><input type="text" name="<varname>j_username</varname>" 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>
+ <td><label>User Password</label><font color="red">*</font></td>
+ <td><input type="password" name="<varname>j_password</varname>" 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>
+<script type="text/javascript">
+ document.form.j_username.focus();
+</script></programlisting>
+
+ <para>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.
+ </para>
+
+ <para>Putting this all together below is a <filename>web.xml</filename>
+ 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
+ <filename>/not-authorized.htm</filename> page.
+ </para>
+
+ <programlisting><web-app>
..
<error-page>
<error-code>403</error-code>
- <location>
-/not-authorized.htm</location>
- </error-page>
+ <location><varname>/not-authorized.htm</varname></location>
+ </error-page>
<security-constraint>
<web-resource-collection>
- <web-resource-name>admin</web-resource-name>
- <url-pattern>
-/admin/*</url-pattern>
+ <web-resource-name>admin</web-resource-name>
+ <url-pattern><varname>/admin/*</varname></url-pattern>
</web-resource-collection>
<auth-constraint>
- <role-name>
-admin</role-name>
+ <role-name><symbol>admin</symbol></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-name>user</web-resource-name>
+ <url-pattern><varname>/user/*</varname></url-pattern>
</web-resource-collection>
<auth-constraint>
- <role-name>
-admin</role-name>
- <role-name>
-user</role-name>
+ <role-name><symbol>admin</symbol></role-name>
+ <role-name><symbol>user</symbol></role-name>
</auth-constraint>
</security-constraint>
<login-config>
- <auth-method>
-FORM</auth-method>
+ <auth-method><varname>FORM</varname></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-page><varname>/login.htm</varname></form-login-page>
+ <form-error-page><varname>/login.htm?auth-error=true</varname></form-error-page>
</form-login-config>
</login-config>
<security-role>
- <role-name>
-admin</role-name>
+ <role-name><symbol>admin</symbol></role-name>
</security-role>
<security-role>
- <role-name>
-user</role-name>
+ <role-name><symbol>user</symbol></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;
-
+</web-app></programlisting>
+ </sect2>
+
+ <sect2 id="alternatve-security-solutions" 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.)
+ </para>
+
+ <para>Below are some of the alternative security solutions available:
+ </para>
+
+ <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>
+ </sect2>
+
+ <sect2 id="resources" remap="h4">
+ <title>Resources</title>
+
+ <para>For more information on using security see the resources below:</para>
+
+ <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>
+ </sect2>
+ </sect1>
+
+ <sect1 id="packages-classes" remap="h2">
+ <title>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 <package>page</package> package.
+ This also works very well with the Page automapping feature.
+ </para>
-/**
+ <para>
+ All the projects domain entity classes would be contained under a
+ <package>entity</package> package, and service classes would be contained
+ under a <package>service</package> directory. Note alternative names for the
+ <package>entity</package> package include domain or model. We also typically
+ have a <package>util</package> package for any stray classes which don't quite
+ fit into the other packages.
+ </para>
+
+ <para>In Java, package names are singular by convention, so we have a util
+ package rather than a utils package.
+ </para>
+
+ <para>An example project structure for a MyCorp web application is illustrated
+ below:
+ </para>
+
+ <figure id="example-project-structure">
+ <title>Example project structure</title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/best-practices/packages-classes.png" format="PNG" scale="85"/>
+ </imageobject>
+ </inlinemediaobject>
+ </figure>
+
+ <para>In this example application we use declarative role and path based security.
+ All the pages in the <package>admin</package> package and directory require the
+ <literal>"admin"</literal> role to be access, while all the pages in the
+ <package>user</package> package and directory require the <literal>"user"</literal>
+ role to be accessed.
+ </para>
+
+ <sect2 id="page-classes" 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.
+ </para>
+
+ <para>For example the BasePage below provides access to Spring configured
+ service objects and a Log4J logger object:
+ </para>
+
+ <programlisting>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");
+ 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");
+ public UserService getUserService() {
+ return (UserService) getBean("userService");
}
-
-
-/**
+
+ /**
* Return the page Logger instance.
*
* @return the page Logger instance
*/
-
-public Logger getLogger() {
-
-if (logger ==
-null) {
+ public Logger getLogger() {
+ if (logger == null) {
logger = Logger.getLogger(getClass());
}
-
-return logger;
+ return logger;
}
-
-/**
+ /**
* @see ApplicationContextAware#setApplicationContext(ApplicationContext)
*/
-
-public void setApplicationContext(ApplicationContext 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) {
+ 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>
+}</programlisting>
-public class BorderPage
-extends BasePage {
+ <para>Applications typically use a border template and have a
+ <classname>BorderPage</classname> which extends <classname>BasePage</classname>
+ and defines the template. For example:
+ </para>
-
-/** The root Menu item. */
-
-public Menu rootMenu =
-new Menu();
-
-
-/**
+ <programlisting>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:
+ public String getTemplate() {
+ return "/border-template.htm";
+ }
+}</programlisting>
+
+ <para>Most application pages subclass <classname>BorderPage</classname>, except
+ AJAX pages which have no need for a HTML border template and typically extend
+ <classname>BasePage</classname>. The <classname>BorderPage</classname> class
+ should not include common logic, other than that required for rendering the
+ border template. Common page logic should be defined in the
+ <classname>BasePage</classname> class.
+ </para>
+
+ <para>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 <classname>BorderPage</classname>
+ class above will not be auto mapped to <filename>border-template.htm</filename>.
+ </para>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="automapping" remap="h2">
+ <title>Page Auto Mapping</title>
+
+ <para>You should use the Click page automapping configuration feature.
+ See the <link linkend="application-automapping">Page Automapping</link>
+ topic for details.
+ </para>
+
+ <para>Automapping will save you from having to manually configure URL path to
+ Page class mappings in your <filename>click.xml</filename> file. If you follow
+ this convention it is very easy to maintain and refactor applications.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>An example <filename>click.xml</filename> automapping configuration is
+ provided below (automapping is enabled by default):
+ </para>
+
+ <programlisting><click-app>
+ <pages package="com.mycorp.dashboard.page"/>
+</click-app></programlisting>
+
+ <para>To see how the page templates are mapped to Page classes set the application
+ <link linkend="application-mode">mode</link> to
+ <literal>debug</literal> and at startup the mappings will be listed out. An
+ example Click startup listing is provided below:
+ </para>
+
+ <programlisting>[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>
+[Click] [debug] /user-list.htm -> com.mycorp.dashboard.page.UserList</programlisting>
+ </sect1>
-public class CustomerListPage
-extends Page {
+ <sect1 id="navigation" remap="h2">
+ <title>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.
+ </para>
+
+ <para>To forward to another page using the Page class:
+ </para>
+
+ <programlisting>public class CustomerListPage extends Page {
+
+ public ActionLink customerLink = new ActionLink(this,"onCustomerClick");
-
-public ActionLink customerLink =
-new ActionLink(
-this,
-"onCustomerClick");
-
..
-
-
-public boolean onCustomerClick() {
+
+ public boolean onCustomerClick() {
Integer id = customerLink.getValueInteger();
- Customer customer = getCustomerService().getCustomer(id);
-
+ Customer customer = getCustomerService().getCustomer(id);
+
CustomerDetailPage customerDetailPage = (CustomerDetailPage)
- getContext().createPage(CustomerDetailPage.
-class);
+ getContext().createPage(CustomerDetailPage.class);
customerDetailPage.setCustomer(customer);
setForward(customerDetailPage);
-
-
-return false;
+
+ 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>
+}</programlisting>
-public class CustomerListPage
-extends Page {
+ <para>To redirect to another page using the Page class you can obtain the pages
+ path from the <classname>Context</classname>. In the example below we are passing
+ through the customer id as a request parameter to the target page.
+ </para>
+
+ <programlisting>public class CustomerListPage extends Page {
+
+ public ActionLink customerLink = new ActionLink(this, "onCustomerClick");
-
-public ActionLink customerLink =
-new ActionLink(
-this,
-"onCustomerClick");
-
..
-
-
-public boolean onCustomerClick() {
+
+ public boolean onCustomerClick() {
String id = customerLink.getValueInteger();
-
- String path = getContext().getPagePath(CustomerDetailPage.
-class);
- setRedirect(path +
-"?id=" + id);
-
-
-return false;
+
+ 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>
+}</programlisting>
+
+ <para>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 application home page.
+ </para>
+
+ <programlisting>public boolean onLogoutClick() {
+ getContext().getSession().invalidate();
+
+ setRedirect(HomePage.class);
+
+ return false;
+}</programlisting>
+ </sect1>
+
+ <sect1 id="templating" remap="h2">
+ <title>Templating</title>
+
+ <para>Use Page templating it is highly recommended. Page templates provide
+ numerous advantages including:
+ </para>
+
+ <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>
-#if (
-$menu.isUserInRoles())
+ <para>To see how to use templates see the
+ <link linkend="page-templating">Page Templating</link> topic. Also see the
+ Click <ulink url="examples.html">Examples</ulink> use of page templating.
+ </para>
+
+ </sect1>
+
+ <sect1 id="menus" remap="h2">
+ <title>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 <filename>WEB-INF/menu.xml</filename> file which is very easy to
+ change.
+ </para>
+
+ <para>A 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:
+ </para>
+
+ <literallayout><symbol>#</symbol><varname>writeMenu</varname>(<symbol>$</symbol>rootMenu)</literallayout>
+
+ <para>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 <filename>WEB-INF/menu.xml</filename> file. A good
+ place to define your macros is in the webroot <filename>/macro.vm</filename>
+ file as it is automatically included by Click.
+ </para>
+
+ <para>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>.
+ </para>
+
+ <literallayout><command>#if</command> (<symbol>$</symbol>menu.isUserInRoles())
..
+<command>#end</command></literallayout>
-#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) {
+ <para>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>.
+ </para>
+ </sect1>
+
+ <sect1 id="logging" remap="h2">
+ <title>Logging</title>
+
+ <para> For page logging you should use
+ <ulink url="http://logging.apache.org/log4j/">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.
+ </para>
+
+ <para>The best place to define your logger is in a common base page, for example:
+ </para>
+
+ <programlisting>public class BasePage extends Page {
+
+ protected Logger logger;
+
+ public Logger getLogger() {
+ if (logger == null) {
logger = Logger.getLogger(getClass());
}
-
-return logger;
+ 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>
+}</programlisting>
-public class CustomerListPage
-extends BasePage {
-
-
-public void onGet() {
-
-try {
+ <para>Using this pattern all your application bases should extend
+ <classname>BasePage</classname> so they can use the
+ <methodname>getLogger()</methodname> method.
+ </para>
+
+ <programlisting>public class CustomerListPage extends BasePage {
+
+ public void onGet() {
+ try {
..
-
- }
-catch (Exception e) {
+ } 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>
+}</programlisting>
-public class CustomerListPage
-extends BasePage {
-
-
-public void onGet() {
-
-if (getLogger().isDebugEnabled()) {
+ <para>If you have some very heavy debug statement you should possibly use an
+ <methodname>isDebugEnabled</methodname> switch so it is not invoked if debug is
+ not required.
+ </para>
+
+ <programlisting>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>
+}</programlisting>
+
+ <para>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.
+ </para>
+
+ </sect1>
+
+ <sect1 id="error-handling" remap="h2">
+ <title>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 <filename>WEB-INF/click.xml</filename>.
+ For example:
+ </para>
+
+ <programlisting><pages package="com.mycorp.page" automapping="true"/>
+ <page path="click/error.htm" classname="ErrorPage"/>
+</pages></programlisting>
+
+ <para>Generally applications 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.
+ </para>
+
+ <para>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 <classname>ErrorPage</classname> error logging
+ page is provided below:
+ </para>
-package com.mycorp.page.ErrorPage;
+ <programlisting>package com.mycorp.page.ErrorPage;
..
+public class ErrorPage extends org.apache.click.util.ErrorPage {
-public class ErrorPage
-extends org.apache.click.util.ErrorPage {
-
-
-public void onDestory() {
+ 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 {
+}</programlisting>
+ </sect1>
+
+ <sect1 id="performance" remap="h2">
+ <title>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.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>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>.
+ </para>
+
+ <para>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
+ are not covered here.
+ </para>
+
+ <para>It is worth pointing out that its not necessary to blindly optimize
+ 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.
+ </para>
+
+ <para>There are a couple of tools that are useful in applying Rule #1 and #10:
+ </para>
- private Form form = new Form("form");
+ <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>
+
+ <para>Below are some articles outlining how to use YUICompressor and Ant to
+ concatenate and compress JavaScript and CSS files:
+ </para>
+
+ <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>
+
+ <para>Using one of the approaches above you can concatenate and compress all
+ JavaScript and CSS for your Pages into two separate files, for example
+ <filename>home-page.css</filename>
+ and <filename>home-page.js</filename>. 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.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>Here is an example:</para>
+
+ <programlisting>public class HomePage extends Page {
+
+ private Form form = new Form("form");
public void onInit() {
- form.add(new EmailField("email");
+ form.add(new EmailField("email");
addControl(form);
}
@@ -623,18 +927,23 @@
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 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>");
+ 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.
+ // 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>
+}</programlisting>
+
+ <para>Using the following <filename>border-template.htm</filename>:
+ </para>
+
+ <programlisting><html>
<head>
<title>Click Examples</title>
${cssImports}
@@ -645,21 +954,27 @@
${jsImports}
</body>
-</html>
-</screen> the rendered HTML will include one CSS and one JavaScript import: <screen>
-<html>
+</html></programlisting>
+
+ <para>the rendered HTML will include one CSS and one JavaScript import:</para>
+
+ <programlisting><html>
<head>
<title>Click Examples</title>
- <link type="text/css" rel="stylesheet" href="/click-examples/assets/css/home-page.css" title="Style"/>
+ <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>
+ <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>
+</html></programlisting>
+
+ <para>A live demo is available
+ <ulink url="http://www.avoka.com/click-examples/general/page-imports-example.htm">here</ulink>
+ </para>
+ </sect1>
+</chapter>