click-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From take...@apache.org
Subject svn commit: r797780 [6/8] - in /incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation: ./ docs/ images/ user-guide/ user-guide/css/ user-guide/images/ user-guide/images/best-practices/ user-guide/images/callouts/ user-guide/images/...
Date Sat, 25 Jul 2009 15:16:02 GMT
Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,197 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>Chapter&nbsp;5.&nbsp;Best Practices</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="index.html" title="Apache Click"><link rel="prev" href="ch04s03.html" title="4.3.&nbsp;Auto Deployed Files"><link rel="next" href="ch05s02.html" title="5.2.&nbsp;Packages and Classes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s03.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div
 ><div><h2 class="title"><a name="chapter-best-practices"></a>Chapter&nbsp;5.&nbsp;Best Practices</h2></div></div></div><div class="toc"><dl><dt><span class="sect1"><a href="ch05.html#security">5.1. Security</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch05.html#declarative-security">5.1.1. Declarative Security</a></span></dt><dt><span class="sect2"><a href="ch05.html#alternatve-security-solutions">5.1.2. Alternative Security solutions</a></span></dt><dt><span class="sect2"><a href="ch05.html#resources">5.1.3. Resources</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch05s02.html">5.2. Packages and Classes</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch05s02.html#page-classes">5.2.1. Page Classes</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch05s03.html">5.3. Page Auto Mapping</a></span></dt><dt><span class="sect1"><a href="ch05s04.html">5.4. Navigation</a></span></dt><dt><span class="sect1"><a href="ch05s05.html">5.5. Templating</
 a></span></dt><dt><span class="sect1"><a href="ch05s06.html">5.6. Menus</a></span></dt><dt><span class="sect1"><a href="ch05s07.html">5.7. Logging</a></span></dt><dt><span class="sect1"><a href="ch05s08.html">5.8. Error Handling</a></span></dt><dt><span class="sect1"><a href="ch05s09.html">5.9. Performance</a></span></dt></dl></div><p>This chapter discusses Best Practices for designing and building Click
+  applications.
+  </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security"></a>5.1.&nbsp;Security</h2></div></div></div><p> For application security it is highly recommended that you use the
+    declarative JEE Servlet path role based security model. While Click pages
+    provide an <code class="methodname">onSecurityCheck()</code> method for rolling your own
+    programatic security model, the declarative JEE model provides numerous
+    advantages.
+    </p><p>These advantages include:
+    </p><div class="itemizedlist"><ul type="disc"><li><p> Its an industry standard pattern making development and maintenance
+          easier.
+        </p></li><li><p> Application servers generally provide numerous ways of integration
+          with an organisations security infrastructure, including LDAP directories
+          and relational databases.
+        </p></li><li><p> 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.
+        </p></li><li><p> 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.
+        </p></li></ul></div><p>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.
+    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="declarative-security"></a>5.1.1.&nbsp;Declarative Security</h3></div></div></div><p> 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.
+      </p><p>
+      For example to secure admin pages, you add a security
+      constraint in your <code class="filename">web.xml</code> file. This requires users
+      to be in the <code class="varname">admin</code> role before they can access to any
+      resources under the <span class="symbol">admin</span> directory:
+      </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;security-constraint&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;web-resource-collection&gt;</span>
+      <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;web-resource-name&gt;</span>admin<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/web-resource-name&gt;</span>
+      <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;url-pattern&gt;</span><span class="symbol">/admin/*</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/url-pattern&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/web-resource-collection&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;auth-constraint&gt;</span>
+      <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;role-name&gt;</span><code class="varname">admin</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/role-name&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/auth-constraint&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/security-constraint&gt;</span></pre><p>The application user roles are defined in the <code class="filename">web.xml</code>
+      file as <code class="literal">security-role</code> elements:
+      </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;security-role&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;role-name&gt;</span><code class="varname">admin</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/role-name&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/security-role&gt;</span></pre><p>The Servlet security model supports three different authentication method:</p><div class="itemizedlist"><ul type="disc"><li><p>
+            <code class="literal">BASIC</code>  - 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.
+          </p></li><li><p>
+            <code class="literal">DIGEST</code>  - 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.
+          </p></li><li><p>
+            <code class="literal">FORM</code>  - 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.
+          </p></li></ul></div><p>The authentication method is specified in the &lt;login-method&gt; element.
+      For example to use the BASIC authentication method you would specify:
+      </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;login-config&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;auth-method&gt;</span><code class="varname">BASIC</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/auth-method&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;realm-name&gt;</span>Admin Realm<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/realm-name&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/login-config&gt;</span></pre><p>To use the FORM method you also need to specify the path to the login
+      page and the login error page:
+      </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;login-config&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;auth-method&gt;</span><code class="varname">FORM</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/auth-method&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;realm-name&gt;</span>Secure Realm<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/realm-name&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;form-login-config&gt;</span>
+      <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;form-login-page&gt;</span><span class="symbol">/login.htm</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/form-login-page&gt;</span>
+      <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;form-error-page&gt;</span><span class="symbol">/login.htm?auth-error=true</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/form-error-page&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/form-login-config&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/login-config&gt;</span></pre><p>In your Click <code class="filename">login.htm</code> page you need to include a
+      special <code class="varname">j_security_check</code> form which includes the input
+      fields <code class="varname">j_username</code> and <code class="varname">j_password</code>.
+      For example:
+      </p><pre class="programlisting"><span class="command"><strong>#if</strong></span> ($request.getParameter("<span class="symbol">auth-error</span>"))
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;div</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">style</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"margin-bottom:1em;margin-top:1em;color:red;"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&gt;</span>
+  Invalid User Name or Password, please try again.<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;br/&gt;</span>
+  Please ensure Caps Lock is off.
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/div&gt;</span>
+<span class="command"><strong>#end</strong></span>
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;form</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">method</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"POST"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">action</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><code class="varname">j_security_check</code>" name="form"&gt;
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;table</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">border</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"0"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">style</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"margin-left:0.25em;"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&gt;</span>
+ <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;tr&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;td&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;label&gt;</span>User Name<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/label&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;font</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">color</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"red"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&gt;</span>*<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/font&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/td&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;td&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;input</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"text"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><code class="varname">j_username</code>" maxlength="20" style="width:150px;"/&gt;<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/td&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;td&gt;</span>&amp;nbsp;<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/td&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/tr&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;tr&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;td&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;label&gt;</span>User Password<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/label&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;font</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">color</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"red"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&gt;</span>*<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/font&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/td&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;td&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;input</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"password"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">name</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"</span><code class="varname">j_password</code>" maxlength="20" style="width:150px;"/&gt;<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/td&gt;</span>
+   <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;td&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;input</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"image"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">src</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"$context/images/login.png"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">title</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Click to Login"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/td&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/tr&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/table&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/form&gt;</span>
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;script</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"text/javascript"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&gt;</span>
+  document.form.j_username.focus();
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/script&gt;</span></pre><p>When using FORM based authentication do <span class="bold"><strong>NOT</strong></span>
+      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.
+      </p><p>Putting this all together below is a <code class="filename">web.xml</code>
+      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
+      <code class="filename">/not-authorized.htm</code> page.
+      </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;web-app&gt;</span>
+
+    ..
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;error-page&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;error-code&gt;</span>403<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/error-code&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;location&gt;</span><code class="varname">/not-authorized.htm</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/location&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/error-page&gt;</span>
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;security-constraint&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;web-resource-collection&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;web-resource-name&gt;</span>admin<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/web-resource-name&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;url-pattern&gt;</span><code class="varname">/admin/*</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/url-pattern&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/web-resource-collection&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;auth-constraint&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;role-name&gt;</span><span class="symbol">admin</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/role-name&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/auth-constraint&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/security-constraint&gt;</span>
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;security-constraint&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;web-resource-collection&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;web-resource-name&gt;</span>user<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/web-resource-name&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;url-pattern&gt;</span><code class="varname">/user/*</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/url-pattern&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/web-resource-collection&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;auth-constraint&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;role-name&gt;</span><span class="symbol">admin</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/role-name&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;role-name&gt;</span><span class="symbol">user</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/role-name&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/auth-constraint&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/security-constraint&gt;</span>
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;login-config&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;auth-method&gt;</span><code class="varname">FORM</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/auth-method&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;realm-name&gt;</span>Secure Zone<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/realm-name&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;form-login-config&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;form-login-page&gt;</span><code class="varname">/login.htm</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/form-login-page&gt;</span>
+            <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;form-error-page&gt;</span><code class="varname">/login.htm?auth-error=true</code><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/form-error-page&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/form-login-config&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/login-config&gt;</span>
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;security-role&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;role-name&gt;</span><span class="symbol">admin</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/role-name&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/security-role&gt;</span>
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;security-role&gt;</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;role-name&gt;</span><span class="symbol">user</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/role-name&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/security-role&gt;</span>
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/web-app&gt;</span></pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="alternatve-security-solutions"></a>5.1.2.&nbsp;Alternative Security solutions</h3></div></div></div><p> There are also alternative security solutions that provide extra
+      features not available in JEE, such as RememberMe functionality, better
+      resource mapping and <code class="literal">Post Logon Page</code> support.
+      (<code class="literal">Post Logon Page</code> 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.)
+      </p><p>Below are some of the alternative security solutions available:
+      </p><div class="itemizedlist"><ul type="disc"><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://static.springframework.org/spring-security/site/index.html" target="_blank">Spring Security</a>
+          </p></li><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://securityfilter.sourceforge.net/" target="_blank">SecurityFilter</a>
+          </p></li><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://www.jsecurity.org/" target="_blank">JSecurity</a>
+          </p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="resources"></a>5.1.3.&nbsp;Resources</h3></div></div></div><p>For more information on using security see the resources below:</p><div class="itemizedlist"><ul type="disc"><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://stc.cis.brown.edu/~stc/Projects/Shibboleth/Version-3/Checklist/Tomcat-Authn/FormBasedAuthentication.pdf" target="_blank">
+                  Form Based Authentication
+            </a>  by Louis E. Mauget
+          </p></li><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://java.sun.com/products/servlet/download.html" target="_blank">Servlet Specification</a>
+              by Sun Microsystems
+          </p></li><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://en.wikipedia.org/wiki/Basic_authentication_scheme" target="_blank">
+                    Basic authentication scheme
+            </a>
+          </p></li><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://en.wikipedia.org/wiki/Digest_access_authentication" target="_blank">
+                    Digest authentication scheme
+            </a>
+          </p></li><li><p>
+            <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://en.wikipedia.org/wiki/Https" target="_blank">Https URI scheme</a>
+          </p></li></ul></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s03.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.3.&nbsp;Auto Deployed Files&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.2.&nbsp;Packages and Classes</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s02.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s02.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s02.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s02.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,107 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.2.&nbsp;Packages and Classes</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="next" href="ch05s03.html" title="5.3.&nbsp;Page Auto Mapping"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.2.&nbsp;Packages and Classes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s03.html">Next</a></td></tr></table><hr></div><div class="sect1" l
 ang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packages-classes"></a>5.2.&nbsp;Packages and Classes</h2></div></div></div><p> 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 <span class="package">page</span> package.
+    This also works very well with the Page automapping feature.
+    </p><p>
+    All the projects domain entity classes would be contained under a
+    <span class="package">entity</span> package, and service classes would be contained
+    under a <span class="package">service</span> directory. Note alternative names for the
+    <span class="package">entity</span> package include domain or model. We also typically
+    have a <span class="package">util</span> package for any stray classes which don't quite
+    fit into the other packages.
+    </p><p>In Java, package names are singular by convention, so we have a util
+    package rather than a utils package.
+    </p><p>An example project structure for a MyCorp web application is illustrated
+    below:
+    </p><div class="figure"><a name="example-project-structure"></a><div class="figure-contents"><span class="inlinemediaobject"><img src="images/best-practices/packages-classes.png" alt="Example project structure"></span></div><p xmlns:fo="http://www.w3.org/1999/XSL/Format" class="title"><i>Figure&nbsp;5.1.&nbsp;Example project structure</i></p></div><br class="figure-break"><p>In this example application we use declarative role and path based security.
+    All the pages in the <span class="package">admin</span> package and directory require the
+    <code class="literal">"admin"</code> role to be access, while all the pages in the
+    <span class="package">user</span> package and directory require the <code class="literal">"user"</code>
+    role to be accessed.
+    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="page-classes"></a>5.2.1.&nbsp;Page Classes</h3></div></div></div><p>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.
+      </p><p>For example the BasePage below provides access to Spring configured
+      service objects and a Log4J logger object:
+      </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> BasePage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">implements</span> ApplicationContextAware {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/** The Spring application context. */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">protected</span> ApplicationContext applicationContext;
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/** The page Logger instance. */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">protected</span> Logger logger;
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/**
+     * Return the Spring configured Customer service.
+     *
+     * @return the Spring configured Customer service
+     */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> CustomerService getCustomerService() {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> (CustomerService) getBean(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"customerService"</span>);
+    }
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/**
+     * Return the Spring configured User service.
+     *
+     * @return the Spring configured User service
+     */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> UserService getUserService() {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> (UserService) getBean(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"userService"</span>);
+    }
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/**
+     * Return the page Logger instance.
+     *
+     * @return the page Logger instance
+     */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> Logger getLogger() {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">if</span> (logger == null) {
+            logger = Logger.getLogger(getClass());
+        }
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> logger;
+    }
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/**
+     * @see ApplicationContextAware#setApplicationContext(ApplicationContext)
+     */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">void</span> setApplicationContext(ApplicationContext applicationContext)  {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">this</span>.applicationContext = applicationContext;
+    }
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/**
+     * 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
+     */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> Object getBean(String beanName) {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> applicationContext.getBean(beanName);
+    }
+
+}</pre><p>Applications typically use a border template and have a
+      <code class="classname">BorderPage</code> which extends <code class="classname">BasePage</code>
+      and defines the template. For example:
+      </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> BorderPage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> BasePage {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/** The root Menu item. */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> Menu rootMenu = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Menu();
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">/**
+     * @see Page#getTemplate()
+     */</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> String getTemplate() {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"/border-template.htm"</span>;
+    }
+}</pre><p>Most application pages subclass <code class="classname">BorderPage</code>, except
+      AJAX pages which have no need for a HTML border template and typically extend
+      <code class="classname">BasePage</code>. The <code class="classname">BorderPage</code> class
+      should not include common logic, other than that required for rendering the
+      border template. Common page logic should be defined in the
+      <code class="classname">BasePage</code> class.
+      </p><p>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 <code class="classname">BorderPage</code>
+      class above will not be auto mapped to <code class="filename">border-template.htm</code>.
+      </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;5.&nbsp;Best Practices&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.3.&nbsp;Page Auto Mapping</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s02.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s03.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s03.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s03.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s03.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,23 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.3.&nbsp;Page Auto Mapping</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05s02.html" title="5.2.&nbsp;Packages and Classes"><link rel="next" href="ch05s04.html" title="5.4.&nbsp;Navigation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.3.&nbsp;Page Auto Mapping</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s02.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s04.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><di
 v class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="automapping"></a>5.3.&nbsp;Page Auto Mapping</h2></div></div></div><p>You should use the Click page automapping configuration feature.
+    See the <a class="link" href="ch04s02.html#application-automapping" title="4.2.3.1.&nbsp;Page Automapping">Page Automapping</a>
+    topic for details.
+    </p><p>Automapping will save you from having to manually configure URL path to
+    Page class mappings in your <code class="filename">click.xml</code> file. If you follow
+    this convention it is very easy to maintain and refactor applications.
+    </p><p>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.
+    </p><p>An example <code class="filename">click.xml</code> automapping configuration is
+    provided below (automapping is enabled by default):
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;click-app&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.dashboard.page"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/click-app&gt;</span></pre><p>To see how the page templates are mapped to Page classes set the application
+    <a class="link" href="ch04s02.html#application-mode" title="4.2.6.&nbsp;Mode">mode</a> to
+    <code class="literal">debug</code> and at startup the mappings will be listed out. An
+    example Click startup listing is provided below:
+    </p><div class="literallayout"><p>[Click]&nbsp;[debug]&nbsp;automapped&nbsp;pages:<br>
+[Click]&nbsp;[debug]&nbsp;/category-tree.htm&nbsp;-&gt;&nbsp;com.mycorp.dashboard.page.CategoryTree<br>
+[Click]&nbsp;[debug]&nbsp;/process-list.htm&nbsp;-&gt;&nbsp;com.mycorp.dashboard.page.ProcessList<br>
+[Click]&nbsp;[debug]&nbsp;/user-list.htm&nbsp;-&gt;&nbsp;com.mycorp.dashboard.page.UserList</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s02.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.2.&nbsp;Packages and Classes&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.4.&nbsp;Navigation</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s03.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s04.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s04.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s04.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s04.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,52 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.4.&nbsp;Navigation</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05s03.html" title="5.3.&nbsp;Page Auto Mapping"><link rel="next" href="ch05s05.html" title="5.5.&nbsp;Templating"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.4.&nbsp;Navigation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s03.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s05.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepag
 e"><div><div><h2 class="title" style="clear: both"><a name="navigation"></a>5.4.&nbsp;Navigation</h2></div></div></div><p> 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.
+    </p><p>To forward to another page using the Page class:
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> CustomerListPage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> ActionLink customerLink = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> ActionLink(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">this</span>,<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"onCustomerClick"</span>);
+
+    ..
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">boolean</span> onCustomerClick() {
+        Integer id = customerLink.getValueInteger();
+        Customer customer = getCustomerService().getCustomer(id);
+
+        CustomerDetailPage customerDetailPage = (CustomerDetailPage)
+            getContext().createPage(CustomerDetailPage.<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span>);
+
+        customerDetailPage.setCustomer(customer);
+        setForward(customerDetailPage);
+
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> false;
+    }
+}</pre><p>To redirect to another page using the Page class you can obtain the pages
+    path from the <code class="classname">Context</code>. In the example below we are passing
+    through the customer id as a request parameter to the target page.
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> CustomerListPage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> ActionLink customerLink = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> ActionLink(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">this</span>, <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"onCustomerClick"</span>);
+
+    ..
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">boolean</span> onCustomerClick() {
+        String id = customerLink.getValueInteger();
+
+        String path = getContext().getPagePath(CustomerDetailPage.<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span>);
+        setRedirect(path + <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"?id="</span> + id);
+
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> false;
+    }
+}</pre><p>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.
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">boolean</span> onLogoutClick() {
+    getContext().getSession().invalidate();
+
+    setRedirect(HomePage.<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span>);
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> false;
+}</pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s03.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.3.&nbsp;Page Auto Mapping&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.5.&nbsp;Templating</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s04.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s05.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s05.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s05.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s05.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,8 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.5.&nbsp;Templating</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05s04.html" title="5.4.&nbsp;Navigation"><link rel="next" href="ch05s06.html" title="5.6.&nbsp;Menus"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.5.&nbsp;Templating</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s04.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s06.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div
 ><h2 class="title" style="clear: both"><a name="templating"></a>5.5.&nbsp;Templating</h2></div></div></div><p>Use Page templating it is highly recommended. Page templates provide
+    numerous advantages including:
+    </p><div class="itemizedlist"><ul type="disc"><li><p>greatly reduce the amount of HTML you need to maintain</p></li><li><p>ensure you have a common look and feel across your application</p></li><li><p>make global application changes very easy</p></li></ul></div><p>To see how to use templates see the
+    <a class="link" href="ch02s06.html" title="2.6.&nbsp;Page Templating">Page Templating</a> topic. Also see the
+    Click <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../examples.html" target="_blank">Examples</a> use of page templating.
+    </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s04.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.4.&nbsp;Navigation&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.6.&nbsp;Menus</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s05.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s06.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s06.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s06.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s06.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,25 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.6.&nbsp;Menus</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05s05.html" title="5.5.&nbsp;Templating"><link rel="next" href="ch05s07.html" title="5.7.&nbsp;Logging"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.6.&nbsp;Menus</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s05.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s07.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 cla
 ss="title" style="clear: both"><a name="menus"></a>5.6.&nbsp;Menus</h2></div></div></div><p> For many applications using the
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/control/Menu.html" target="_blank">Menu</a>
+    control to centralize application navigation is very useful. Menus are
+    defined in a <code class="filename">WEB-INF/menu.xml</code> file which is very easy to
+    change.
+    </p><p>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:
+    </p><div class="literallayout"><p><span class="symbol">#</span><code class="varname">writeMenu</code>(<span class="symbol">$</span>rootMenu)</p></div><p>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 <code class="filename">WEB-INF/menu.xml</code> file. A good
+    place to define your macros is in the webroot <code class="filename">/macro.vm</code>
+    file as it is automatically included by Click.
+    </p><p>Using macros you can create dynamic menu behaviour such as only rendering
+    menu items a user is authorized to access with
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/control/Menu.html#isUserInRoles()" target="_blank">isUserInRoles()</a>.
+    </p><div class="literallayout"><p><span class="command"><strong>#if</strong></span>&nbsp;(<span class="symbol">$</span>menu.isUserInRoles())<br>
+&nbsp;&nbsp;&nbsp;..<br>
+<span class="command"><strong>#end</strong></span></p></div><p>You can also use JavaScript to add dynamic behaviour such as drop down menus,
+      for example see the Menu page in Click
+      <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../examples.html" target="_blank">Examples</a>.
+    </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s05.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.5.&nbsp;Templating&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.7.&nbsp;Logging</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s06.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s07.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s07.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s07.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s07.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,70 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.7.&nbsp;Logging</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05s06.html" title="5.6.&nbsp;Menus"><link rel="next" href="ch05s08.html" title="5.8.&nbsp;Error Handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.7.&nbsp;Logging</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s06.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s08.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><
 h2 class="title" style="clear: both"><a name="logging"></a>5.7.&nbsp;Logging</h2></div></div></div><p> 
+    For application logging you should use one of the well established 
+    logging libraries such as Java Util Logging (JUL) or Log4J.
+    </p><p>
+    The library you use will largely depend upon the application server you are targeting.
+    For Apache Tomcat or RedHat JBoss the  
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://logging.apache.org/log4j/" target="_blank">Log4j</a> library is a good 
+    choice. While for the IBM WebSphere or Oracle WebLogic application servers Java Util
+    Logging is better choice as this library is better supported.
+    </p><p>
+    If you have to target multiple application servers you should consider using the
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://www.slf4j.org/" target="_blank">SLF4J</a> library which uses compile time bindings
+    to an underlying logging implementation. 
+    </p><p>
+    As a general principle you should
+    probably avoid <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://jakarta.apache.org/commons/logging/" target="_blank">Commons Logging</a> 
+    because of the class loading issues associated with it. If you are using
+    Commons Logging please make sure you have the latest version.
+    </p><p>
+    It is a best place to define a logger method in a common base page, for example:
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> BasePage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">protected</span> Logger logger;
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> Logger getLogger() {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">if</span> (logger == null) {
+            logger = Logger.getLogger(getClass());
+        }
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> logger;
+    }
+}</pre><p>Using this pattern all your application bases should extend
+    <code class="classname">BasePage</code> so they can use the
+    <code class="methodname">getLogger()</code> method.
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> CustomerListPage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> BasePage {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">void</span> onGet() {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">try</span> {
+            ..
+        } <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">catch</span> (Exception e) {
+            getLogger().error(e);
+        }
+    }
+}</pre><p>If you have some very heavy debug statement you should possibly use an
+    <code class="methodname">isDebugEnabled</code> switch so it is not invoked if debug is
+    not required.
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> CustomerListPage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> BasePage {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">void</span> onGet() {
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">if</span> (getLogger().isDebugEnabled()) {
+            String msg = ..
+
+            getLogger().debug(msg);
+        }
+
+        ..
+    }
+}</pre><p>
+    Please note the Click logging facility is not designed for application use,
+    and is for Click internal use only. When Click is running in
+    <code class="literal">production</code> mode it will not produce any logging output.
+    By default Click logs to the console using
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/service/ConsoleLogService.html" target="_blank">ConsoleLogService</a>. 
+    </p><p>
+    If you need to configure Click to log to an alternative destination please configure a LogService such as
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/service/JdkLogService.html" target="_blank">JdkLogService</a>,
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/service/Log4JLogService.html" target="_blank">Log4JLogService</a> or
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/service/Slf4jLogService.html" target="_blank">Slf4jLogService</a>.
+    </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s06.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.6.&nbsp;Menus&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.8.&nbsp;Error Handling</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s07.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s08.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s08.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s08.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s08.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,28 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.8.&nbsp;Error Handling</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05s07.html" title="5.7.&nbsp;Logging"><link rel="next" href="ch05s09.html" title="5.9.&nbsp;Performance"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.8.&nbsp;Error Handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s07.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch05s09.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage
 "><div><div><h2 class="title" style="clear: both"><a name="error-handling"></a>5.8.&nbsp;Error Handling</h2></div></div></div><p> In Click unhandled errors are directed to the
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/ErrorPage.html" target="_blank">ErrorPage</a>
+    for display. If applications require additional error handling they can create
+    and register a custom error page in <code class="filename">WEB-INF/click.xml</code>.
+    For example:
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;pages</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">package</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"com.mycorp.page"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">automapping</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"annotation"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;page</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">path</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"click/error.htm"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">classname</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"ErrorPage"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/pages&gt;</span></pre><p>Generally applications handle transactional errors using service layer code
+    or via a servlet
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/Filter.html" target="_blank">Filter</a>
+    and would not need to include error handling logic in an error page.
+    </p><p>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
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/ErrorPage.html" target="_blank">ErrorPage</a>
+    could be configured. An example <code class="classname">ErrorPage</code> error logging
+    page is provided below:
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">package</span> com.mycorp.page.ErrorPage;
+..
+
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> ErrorPage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> org.apache.click.util.ErrorPage {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">void</span> onDestory() {
+        Logger.getLogger(getClass()).error(getError());
+    }
+}</pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s07.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch05s09.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.7.&nbsp;Logging&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;5.9.&nbsp;Performance</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s08.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s09.html
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s09.html?rev=797780&view=auto
==============================================================================
--- incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s09.html (added)
+++ incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s09.html Sat Jul 25 15:15:49 2009
@@ -0,0 +1,113 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.9.&nbsp;Performance</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_8247"><link rel="home" href="index.html" title="Apache Click"><link rel="up" href="ch05.html" title="Chapter&nbsp;5.&nbsp;Best Practices"><link rel="prev" href="ch05s08.html" title="5.8.&nbsp;Error Handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5.9.&nbsp;Performance</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s08.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;Best Practices</th><td width="20%" align="right">&nbsp;</td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="performance"></a>5.9.&nbsp;Performance</h2></div></d
 iv></div><p>Yahoo published a list of
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://developer.yahoo.com/performance/rules.html" target="_blank">best practices</a>
+    for improving web application performance.
+    </p><p>Click Framework provides a
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../extras-api/org/apache/click/extras/filter/PerformanceFilter.html" target="_blank">PerformanceFilter</a>
+    which caters for some of these rules. However not all rules can be easily automated.
+    </p><p>This section outlines how to apply some important rules which are not
+    covered by the PerformanceFilter namely,
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://developer.yahoo.com/performance/rules.html#num_http" target="_blank">Minimize HTTP Requests (by combining files)</a>
+    and <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://developer.yahoo.com/performance/rules.html#minify" target="_blank">Minify JavaScript and CSS</a>.
+    </p><p>The Rule, <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://developer.yahoo.com/performance/rules.html#num_http" target="_blank">Minimize HTTP Requests</a>,
+    also mentions <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://alistapart.com/articles/sprites" target="_blank">CSS Sprites</a>,
+    a method for combining multiple images into a single master image. CSS Sprites
+    can boost performance when your application has many images, however it is
+    harder to create and maintain. Note that CSS Sprites is not covered here.
+    </p><p>It is worth pointing out that its not necessary to optimize
+    every page in your application. Instead concentrate on popular pages, for
+    example a web site's <span class="emphasis"><em>Home Page</em></span> would be a good
+    candidate.
+    </p><p>There are a couple of tools that are useful in applying the rules
+    "Minimize HTTP Requests" and "Minify JavaScript and CSS":
+    </p><div class="itemizedlist"><ul type="disc"><li><p>
+          <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://developer.yahoo.com/yui/compressor/" target="_blank">YUICompressor</a>
+            - minifies and compresses JavaScript and CSS files so less bytes have to
+            be transferred across the wire.
+        </p></li><li><p>
+          <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://code.google.com/p/javaflight-code/" target="_blank">Ant Task for YUICompressor</a>
+            - an Ant task that uses YUICompressor to compress JavaScript and CSS files.
+        </p></li><li><p>
+          <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://www.crockford.com/javascript/jsmin.html" target="_blank">JSMin</a>
+            - 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.
+        </p></li></ul></div><p>Below are some articles outlining how to use YUICompressor and Ant to
+    concatenate and compress JavaScript and CSS files:
+    </p><div class="itemizedlist"><ul type="disc"><li><p>
+          <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://www.julienlecomte.net/blog/2007/09/16/" target="_blank">Article</a>
+            explaining how to use Ant and YUICompressor for compression.
+        </p></li><li><p>
+          <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://javaflight.blogspot.com/2008/01/introducing-yui-compressor-ant-task.html" target="_blank">Article</a>
+            outlining how to use a special YUICompressor Ant Task for compression.
+        </p></li></ul></div><p>Using one of the approaches above you can concatenate and compress all
+    JavaScript and CSS for your Pages into two separate files, for example
+    <code class="filename">home-page.css</code>
+    and <code class="filename">home-page.js</code>. 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 <span class="emphasis"><em>only</em></span> include the two
+    compressed files, home-page.css and home-page.js.
+    </p><p>Click makes use of the utility class
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/PageImports.html" target="_blank">PageImports</a>
+    to include the CSS and JavaScript. PageImports exposes the method
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/util/PageImports.html#setInitialized(boolean)" target="_blank">setInitialized(boolean)</a>,
+    which controls when PageImports are fully initialized. Once PageImports have
+    been initialized, no other CSS and JavaScript will be included.
+    </p><p>Knowing this one can override
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="../../click-api/org/apache/click/Page.html#getPageImports()" target="_blank">Page.getPageImports()</a>,
+    and import the necessary JavaScript and CSS files and then set PageImports to
+    <code class="literal">initialized</code>, forcing PageImports to skip other CSS and
+    JavaScript files.
+    </p><p>Here is an example:</p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">class</span> HomePage <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">extends</span> Page {
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">private</span> Form form = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> Form(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"form"</span>);
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">void</span> onInit() {
+        form.add(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> EmailField(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"email"</span>);
+        addControl(form);
+    }
+
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">public</span> PageImports getPageImports () {
+        PageImports pageImports = <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">super</span>.getPageImports();
+
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">// Add the Page Css to the PageImports</span>
+        pageImports.add(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> CssImport(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"/assets/css/home-page.css"</span>));
+
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">// Add the Page JS to the PageImports</span>
+        pageImports.add(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">new</span> JsImport(<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="str">"/assets/js/home-page.js"</span>));
+
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">// Set pageImports to initialized so that no other Css and JavaScript</span>
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="com">// files will be included.</span>
+        pageImports.setInitialized(true);
+        
+        <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="kwd">return</span> pageImports;
+    }
+}</pre><p>Using the following <code class="filename">border-template.htm</code>:
+    </p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;html&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;head&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;title&gt;</span>Click Examples<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/title&gt;</span>
+    ${headElements}
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/head&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;body&gt;</span>
+
+  ...
+
+  ${jsElements}
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/body&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/html&gt;</span></pre><p>the rendered HTML will include one CSS and one JavaScript import:</p><pre class="programlisting"><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;html&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;head&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;title&gt;</span>Click Examples<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/title&gt;</span>
+    <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;link</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"text/css"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">rel</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"stylesheet"</span>
+          <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">href</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"/click-examples/assets/css/home-page.css"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">title</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"Style"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">/&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/head&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;body&gt;</span>
+
+  ...
+
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;script</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">type</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"text/javascript"</span> <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="atn">src</span>=<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="pln">"/click-examples/assets/js/home-page.js"</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&gt;</span><span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/script&gt;</span>
+  <span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/body&gt;</span>
+<span xmlns:fo="http://www.w3.org/1999/XSL/Format" class="tag">&lt;/html&gt;</span></pre><p>A live demo is available
+    <a xmlns:fo="http://www.w3.org/1999/XSL/Format" class="external" href="http://www.avoka.com/click-examples/general/page-imports-example.htm" target="_blank">here</a>
+    </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s08.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right">&nbsp;</td></tr><tr><td width="40%" align="left" valign="top">5.8.&nbsp;Error Handling&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s09.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message