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/05 17:39:47 UTC
svn commit: r741172 [1/2] - in
/incubator/click/trunk/tools/docbook/src/docbook/click:
chapter-configuration.xml chapter-controls.xml chapter-introduction.xml
Author: sabob
Date: Thu Feb 5 16:39:47 2009
New Revision: 741172
URL: http://svn.apache.org/viewvc?rev=741172&view=rev
Log:
updated docbook
Modified:
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
Modified: incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml?rev=741172&r1=741171&r2=741172&view=diff
==============================================================================
--- incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml (original)
+++ incubator/click/trunk/tools/docbook/src/docbook/click/chapter-configuration.xml Thu Feb 5 16:39:47 2009
@@ -1,19 +1,19 @@
<?xml version='1.0' encoding='UTF-8'?>
- <chapter remap="h1">
+<chapter id="chapter-configuration" remap="h1">
<title>Configuration</title>
<para> This section discusses how to setup and configure a Click web application and covers the following topics: </para>
<orderedlist>
<listitem>
- <para><link linkend="configuration.html-servlet-configuration">Servlet Configuration</link> - how to setup the ClickServlet</para>
+ <para><link linkend="servlet-configuration">Servlet Configuration</link> - how to setup the ClickServlet</para>
</listitem>
<listitem>
- <para><link linkend="configuration.html-application-configuration">Application Configuration</link> - how to configure the Click application descriptor</para>
+ <para><link linkend="application-configuration">Application Configuration</link> - how to configure the Click application descriptor</para>
</listitem>
<listitem>
- <para><link linkend="configuration.html-auto-deployed-files">Auto Deployed Files</link> - automatically deployed Click files</para>
+ <para><link linkend="auto-deployed-files">Auto Deployed Files</link> - automatically deployed Click files</para>
</listitem>
</orderedlist>
- <para>Â </para>
+ <para> </para>
<para> The Click configuration files include: </para>
<informaltable frame="none">
<tgroup cols="2">
@@ -25,7 +25,7 @@
<para>
<inlinemediaobject>
<imageobject>
- <imagedata fileref="./../images/config-files.png" format="PNG"/>
+ <imagedata fileref="images/configuration/config-files.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
@@ -34,10 +34,10 @@
<para>
<itemizedlist>
<listitem>
- <para> WEB-INF/<link linkend="configuration.html-application-configuration">click.xml</link> Â - Â Application Configuration (<emphasis role="bold">required</emphasis>)</para>
+ <para> WEB-INF/<link linkend="application-configuration">click.xml</link> - Application Configuration (<emphasis role="bold">required</emphasis>)</para>
</listitem>
<listitem>
- <para> WEB-INF/<link linkend="configuration.html-servlet-configuration">web.xml</link> Â - Â Servlet Configuration (<emphasis role="bold">required</emphasis>)</para>
+ <para> WEB-INF/<link linkend="servlet-configuration">web.xml</link> - Servlet Configuration (<emphasis role="bold">required</emphasis>)</para>
</listitem>
</itemizedlist>
</para>
@@ -46,15 +46,10 @@
</tbody>
</tgroup>
</informaltable>
- <para>
- <anchor id="configuration.html-servlet-configuration"/>
- </para>
- <indexterm>
- <primary>servlet-configuration</primary>
- </indexterm>
- <sect1 remap="h2">
- <title>1. Servlet Configuration</title>
- <para> For a Click web application to function the <ulink url="click-api/org/apache/click/ClickServlet.html">ClickServlet</ulink> must be configured in the web application's <literal>/WEB-INF/web.xml</literal> file. A basic web application which maps all <literal>*.htm</literal> requests to a ClickServlet is provided below. <screen>
+
+ <sect1 id="servlet-configuration" remap="h2">
+ <title>1. Servlet Configuration - how to setup the ClickServlet</title>
+ <para> For a Click web application to function the <ulink url="click-api/org/apache/click/ClickServlet.html">ClickServlet</ulink> must be configured in the web application's <literal>/WEB-INF/web.xml</literal> file. A basic web application which maps all <literal>*.htm</literal> requests to a ClickServlet is provided below. <programlisting>
<web-app>
<servlet>
@@ -65,40 +60,58 @@
<load-on-startup>
0</load-on-startup>
</servlet>
-
+
<servlet-mapping>
<servlet-name>
ClickServlet</servlet-name>
<url-pattern>
*.htm</url-pattern>
</servlet-mapping>
-
+
</web-app>
-</screen></para>
- <sect2 remap="h3">
- <title>1.1Â Servlet Mapping</title>
- <para> By convention all Click page templates should have a .htm extension, and the ClickServlet should be mapped to process all *.htm URL requests. With this convention you have all the static HTML pages use a .html extension and they will not be processed as Click pages. </para>
+</programlisting></para>
+ <sect2 id="servlet-mapping" remap="h3">
+ <title>1.1 Servlet Mapping</title>
+ <para> By convention all Click page templates should have a .htm extension,
+ and the ClickServlet should be mapped to process all *.htm URL requests.
+ With this convention you have all the static HTML pages use a .html extension
+ and they will not be processed as Click pages. </para>
</sect2>
- <sect2 remap="h3">
- <title>1.2Â Load On Startup</title>
- <para> Note you should always set <literal>load-on-startup</literal> element to be 0 so the servlet is initialized when the server is started. This will prevent any delay for the first client which uses the application. The <literal>ClickServlet</literal> performs as much work as possible at startup to improve performance later on. The Click start up and caching strategy is configured with the Click application mode element in the "<literal>click.xml</literal>" config file, covered next. <anchor id="configuration.html-application-configuration"/><indexterm>
- <primary>application-configuration</primary>
- </indexterm>
-</para>
+ <sect2 id="load-on-startup" remap="h3">
+ <title>1.2 Load On Startup</title>
+ <para> Note you should always set <literal>load-on-startup</literal> element
+ to be 0 so the servlet is initialized when the server is started. This will
+ prevent any delay for the first client which uses the application. The
+ <literal>ClickServlet</literal> performs as much work as possible at startup
+ to improve performance later on. The Click start up and caching strategy is
+ configured with the Click application mode element in the
+ "<literal>click.xml</literal>" config file, covered next.
+ </para>
</sect2>
</sect1>
- <sect1 remap="h2">
- <title>2. Application Configuration</title>
- <para> The heart of a Click application is the <literal>click.xml</literal> configuration file. This file specifies the application pages, headers, the format object and the applications mode. By default the ClickServlet will attempt to load the application configuration file using the path: Â <literal>/WEB-INF/click.xml</literal> If this file is not found under the <literal>WEB-INF</literal> directory, then ClickServlet will attempt to load it from the classpath as <literal>/click.xml</literal>. See <ulink url="click-dtd.html">Click DTD</ulink> for the click-app XML definition. A complete Click configuration example is available <ulink url="click-dtd-example.html">here</ulink> which can be used as a quick reference when configuring Click. A basic Click app config file is provided below: <screen>
-<click-app>
+
+ <sect1 id="application-configuration" remap="h2">
+ <title>2. Application Configuration</title>
+ <para> The heart of a Click application is the <literal>click.xml</literal>
+ configuration file. This file specifies the application pages, headers,
+ the format object and the applications mode. By default the ClickServlet
+ will attempt to load the application configuration file using the path:
+ <literal>/WEB-INF/click.xml</literal> If this file is not found under the
+ <literal>WEB-INF</literal> directory, then ClickServlet will attempt to load it
+ from the classpath as <literal>/click.xml</literal>. See <ulink url="click-dtd.html">Click DTD</ulink>
+ for the click-app XML definition. A complete Click configuration example is
+ available <ulink url="click-dtd-example.html">here</ulink> which can be used
+ as a quick reference when configuring Click. A basic Click app config file is
+ provided below: <programlisting>
+<click-app>
<pages package="com.mycorp.page"/>
-
+
<mode value="profile"/>
-
-</click-app>
-</screen> An example of an advanced config file is: <screen>
-<click-app charset="UTF-8" locale="de">
+
+</click-app>
+</programlisting> An example of an advanced config file is: <programlisting>
+<click-app charset="UTF-8" locale="de">
<pages package="com.mycorp.banking.page">
<page path="index.htm" classname="com.mycorp.page.Home"/>
@@ -107,27 +120,26 @@
<pages package="com.mycorp.common.page"/>
<format classname="com.mycorp.util.Format"/>
-
+
<mode value="profile"/>
-
+
<log-service classname="org.apache.click.extras.service.Log4JLogService"/>
-
-</click-app>
-</screen><anchor id="configuration.html-application-click-app"/><indexterm>
- <primary>application-click-app</primary>
- </indexterm>
-</para>
- <sect2 remap="h3">
- <title>2.1Â Click App</title>
- <para> The root click-app element defines two application localization attributes charset and locale. <screen>
-<!ELEMENT
-click-app (pages*, headers?, format?, mode?, controls?,
+
+</click-app>
+</programlisting>
+</para>
+
+ <sect2 id="application-click-app" remap="h3">
+ <title>2.1 Click App</title>
+ <para> The root click-app element defines two application localization attributes charset and locale. <programlisting>
+<!ELEMENT
+click-app (pages*, headers?, format?, mode?, controls?,
file-upload-service?, log-service?, template-service?)>
- <!ATTLIST click-app
+ <!ATTLIST click-app
charset CDATA #IMPLIED>
- <!ATTLIST click-app
+ <!ATTLIST click-app
locale CDATA #IMPLIED>
-</screen> The charset attribute defines the character encoding set for: <itemizedlist>
+</programlisting> The charset attribute defines the character encoding set for: <itemizedlist>
<listitem>
<para> Velocity templates</para>
</listitem>
@@ -138,90 +150,104 @@
<para> Page Content-Type charset, see Page <ulink url="click-api/org/apache/click/Page.html#getContentType()">getContentType()</ulink></para>
</listitem>
</itemizedlist>
- The locale attribute defines the default application Locale. If this value is defined it will override Locale returned by the request. Please see the Context <ulink url="click-api/org/apache/click/Context.html#getLocale()">getLocale()</ulink> for details. For example the folliwing configuration sets the application character set to UTF-8 and the default Locale as German (de): <screen>
-<click-app
+ The locale attribute defines the default application Locale. If this value is defined it will override Locale returned by the request. Please see the Context <ulink url="click-api/org/apache/click/Context.html#getLocale()">getLocale()</ulink> for details. For example the folliwing configuration sets the application character set to UTF-8 and the default Locale as German (de): <programlisting>
+<click-app
charset="
-UTF-8"
+UTF-8"
locale="
-de">
+de">
..
-</click-app>
-</screen><anchor id="configuration.html-application-pages"/><indexterm>
- <primary>application-pages</primary>
- </indexterm>
+</click-app>
+</programlisting>
</para>
</sect2>
- <sect2 remap="h3">
- <title>2.2Â Pages</title>
- <para> The first child element of the click-app is the mandatory <literal>pages</literal> element which defines the list of Click pages. <screen>
-<!ELEMENT
+
+ <sect2 id="application-pages" remap="h3">
+ <title>2.2 Pages</title>
+ <para> The first child element of the click-app is the mandatory <literal>pages</literal> element which defines the list of Click pages. <programlisting>
+<!ELEMENT
pages (
-page*)>
- <!ATTLIST pages
+page*)>
+ <!ATTLIST pages
package CDATA #IMPLIED>
- <!ATTLIST pages
-automapping (true|false) "true">
- <!ATTLIST pages
-autobinding (true|false) "true">
-</screen> The pages element can specify a default package name which is prepended to the classname of any pages defined. The pages element also defines the automapping attribute which is discussed in the <link linkend="configuration.html-application-automapping">Page Automapping</link> topic. <anchor id="configuration.html-application-multi-packages"/><indexterm>
- <primary>application-multi-packages</primary>
- </indexterm>
-</para>
- <sect3 remap="h4">
- <title>2.2.1Â Multiple Pages Packages</title>
- <para> Click can support multiple pages elements to enable the automapping of multiple packages. <screen>
-<click-app>
+ <!ATTLIST pages
+automapping (true|false) "true">
+ <!ATTLIST pages
+autobinding (true|false) "true">
+</programlisting> The pages element can specify a default package name which is prepended
+to the classname of any pages defined. The pages element also defines the automapping
+attribute which is discussed in the <link linkend="application-automapping">Page Automapping</link>
+topic.
+
+</para>
+
+ <sect3 id="application-multiple-packages" remap="h4">
+ <title>2.2.1 Multiple Pages Packages</title>
+ <para> Click can support multiple pages elements to enable the automapping of multiple packages. <programlisting>
+<click-app>
<pages package="com.mycorp.banking.page"/>
<pages package="com.mycorp.common.page"/>
-</click-app>
-</screen> With multiple pages elements, pages are loaded in the order of the page elements, with manual page elements being loaded before automapped pages. Once a page template has been mapped to a Page class it will not be replaced by a subsequent potential match. So pages elements at the top take priority over lower pages elements. <anchor id="configuration.html-application-page"/><indexterm>
- <primary>application-page</primary>
- </indexterm>
+</click-app>
+</programlisting> With multiple pages elements, pages are loaded in the order of
+the page elements, with manual page elements being loaded before automapped pages.
+Once a page template has been mapped to a Page class it will not be replaced by a
+subsequent potential match. So pages elements at the top take priority over lower
+pages elements.
+
</para>
</sect3>
</sect2>
- <sect2 remap="h3">
- <title>2.3Â Page</title>
- <para> The page element defines the Click application pages. <screen>
-<!ELEMENT
+ <sect2 id="application-page" remap="h3">
+ <title>2.3 Page</title>
+ <para> The page element defines the Click application pages. <programlisting>
+<!ELEMENT
page (
header*)>
- <!ATTLIST page
+ <!ATTLIST page
path CDATA #REQUIRED>
- <!ATTLIST page
-classname CDATA #REQUIRED>
-</screen> Each page path must be unique, as the Click application maps HTTP requests to the page paths. The Click application will create a new Page instance for the given request using the configured page classname. All pages must subclass <ulink url="click-api/org/apache/click/Page.html">Page</ulink> and provide a public no arguments constructor, so they can be instantiated. Pages can also define header values which are discussed in the next topic. When the Click application starts up it will check all the page definitions. If there is a critical configuration error the ClickSerlvet will log an <literal>ERROR</literal> message and throw an <ulink url="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/UnavailableException.html">UnavailableException</ulink>. If this occurs the click application will be permanently unavailable until the error is fixed and the web app is restarted. <anchor id="configuration.html-application-automapping"/><indexterm>
- <primary>application-automapping</primary>
- </indexterm>
-</para>
- <sect3 remap="h4">
- <title>2.3.1Â Page Automapping</title>
- <para> Page automapping will automatically configure application pages using a simple set of rules. This enables you to greatly streamline your configuration file as you only need to define pages which don't fit the automapping rules. Automapping will attempt to associate each page template (*.htm) and JSP file in the web application (excluding those under the WEB-INF and click directories) to a Page class. Automapped pages are loaded after the manually defined pages are loaded, and manually defined pages takes preference. When automapping is enabled the Click application will log the page mappings when in debug or trace mode. For example given a page path to class mapping: <screen>
+ <!ATTLIST page
+classname CDATA #REQUIRED>
+</programlisting> Each page path must be unique, as the Click application maps HTTP
+requests to the page paths. The Click application will create a new Page instance
+for the given request using the configured page classname. All pages must subclass
+<ulink url="click-api/org/apache/click/Page.html">Page</ulink> and provide a public
+no arguments constructor, so they can be instantiated. Pages can also define header
+values which are discussed in the next topic. When the Click application starts up it
+will check all the page definitions. If there is a critical configuration error the
+ClickSerlvet will log an <literal>ERROR</literal> message and throw an
+<ulink url="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/UnavailableException.html">UnavailableException</ulink>.
+If this occurs the click application will be permanently unavailable until the error
+is fixed and the web app is restarted.
+
+</para>
+ <sect3 id="application-automapping" remap="h4">
+ <title>2.3.1 Page Automapping</title>
+ <para> Page automapping will automatically configure application pages using a simple set of rules. This enables you to greatly streamline your configuration file as you only need to define pages which don't fit the automapping rules. Automapping will attempt to associate each page template (*.htm) and JSP file in the web application (excluding those under the WEB-INF and click directories) to a Page class. Automapped pages are loaded after the manually defined pages are loaded, and manually defined pages takes preference. When automapping is enabled the Click application will log the page mappings when in debug or trace mode. For example given a page path to class mapping: <programlisting>
-index.htm =>
+index.htm =>
com.mycorp.page.Home
-search.htm =>
+search.htm =>
com.mycorp.page.Search
-contacts/contacts.htm =>
+contacts/contacts.htm =>
com.mycorp.page.contacts.Contacts
-security/login.htm =>
+security/login.htm =>
com.mycorp.page.security.Login
-security/logout.htm =>
+security/logout.htm =>
com.mycorp.page.security.Logout
-security/change-password.htm =>
+security/change-password.htm =>
com.mycorp.page.security.ChangePassword
-</screen> This could be configured manually by setting the automapping attribute to "false" and using the package prefix, for example: <screen>
+</programlisting> This could be configured manually by setting the automapping attribute to "false" and using the package prefix, for example: <programlisting>
<click-app>
<pages package="
-com.mycorp.page"
+com.mycorp.page"
automapping="
false">
<page path="
@@ -238,66 +264,65 @@
security.Login"/>
<page path="
security/logout.htm" classname="
-security.Logout"/>
+security.Logout"/>
<page path="
security/change-password.htm" classname="
-security.ChangePassword"/>
+security.ChangePassword"/>
</pages>
-</click-app>
-</screen> Using automapping you only need to define the Home page which doesn't automatically map to index.html. <screen>
+</click-app>
+</programlisting> Using automapping you only need to define the Home page which doesn't automatically map to index.html. <programlisting>
<click-app>
<pages package="
-com.mycorp.page"
+com.mycorp.page"
automapping="
true">
<page path="
index.htm" classname="
Home"/>
</pages>
-</click-app>
-</screen> Note automapping is true by default, so it could be omitted from the configuration file. The page template name to classname convention is: <screen>
+</click-app>
+</programlisting> Note automapping is true by default, so it could be omitted from the configuration file. The page template name to classname convention is: <programlisting>
change-password.htm => ChangePassword
change_password.htm => ChangePassword
changePassword.htm => ChangePassword
ChangePassword.htm => ChangePassword
-</screen> When automapping pages, if a class cannot be found Click will attempt to add the 'Page' suffix to the classname if not already present and map this. For example: <screen>
+</programlisting> When automapping pages, if a class cannot be found Click will attempt to add the 'Page' suffix to the classname if not already present and map this. For example: <programlisting>
customer.htm => CustomerPage
change-password.htm => ChangePasswordPage
-</screen><anchor id="configuration.html-application-excludes"/><indexterm>
- <primary>application-excludes</primary>
- </indexterm>
+</programlisting>
</para>
</sect3>
- <sect3 remap="h4">
- <title>2.3.2Â Automapping Excludes</title>
- <para> With Page automapping there can be resources where you don't want automapping applied. For example when using a JavaScript library with lots of <literal>.htm</literal> files, you don't want automapping to try and find Page class for each of these files. In these situations you can use the pages <literal>excludes</literal> element. <screen>
-<!ELEMENT
+
+ <sect3 id="application-excludes" remap="h4">
+ <title>2.3.2 Automapping Excludes</title>
+ <para> With Page automapping there can be resources where you don't want automapping applied. For example when using a JavaScript library with lots of <literal>.htm</literal> files, you don't want automapping to try and find Page class for each of these files. In these situations you can use the pages <literal>excludes</literal> element. <programlisting>
+<!ELEMENT
excludes (#PCDATA)>
- <!ATTLIST excludes
+ <!ATTLIST excludes
pattern CDATA #REQUIRED>
-</screen> For example if our application uses the TinyMCE JavaScript library we could configure our pages automapping to exclude all <literal>.htm</literal> files under the <literal>/tiny_mce</literal> directory. <screen>
+</programlisting> For example if our application uses the TinyMCE JavaScript library we could configure our pages automapping to exclude all <literal>.htm</literal> files under the <literal>/tiny_mce</literal> directory. <programlisting>
<click-app>
<pages package="com.mycorp.page">
<
excludes pattern="
/tiny_mce/*"/>
</pages>
-</click-app>
-</screen> The excludes pattern can specify multiple directories or files using a comma separated notation. For example: <screen>
+</click-app>
+</programlisting> The excludes pattern can specify multiple directories or files using a comma separated notation. For example: <programlisting>
<click-app>
<pages package="com.mycorp.page">
<
excludes pattern="
/dhtml/*, /tiny_mce/*, banner.htm, about.htm"/>
</pages>
-</click-app>
-</screen> HTM files excluded from Page automapping are handled by an internal Page class with caching headers enabled. <anchor id="configuration.html-application-autobinding"/><indexterm>
- <primary>application-autobinding</primary>
- </indexterm>
+</click-app>
+</programlisting> HTM files excluded from Page automapping are handled by an internal
+Page class with caching headers enabled.
</para>
</sect3>
- <sect3 remap="h4">
- <title>2.3.3Â Page Autobinding</title>
+
+ <sect3 id="application-autobinding" remap="h4">
+ <title>2.3.3 Page Autobinding</title>
<para> By default all pages have autobinding enabled. With autobinding enabled the ClickServlet will automatically: <itemizedlist>
<listitem>
<para> add any public controls to the page, after the page constructor has been invoked</para>
@@ -312,21 +337,21 @@
<para> add any public page fields to the page model, before rendering</para>
</listitem>
</itemizedlist>
- For example: <screen>
+ For example: <programlisting>
public class EmployeePage extends Page {
public Form employeeForm = new Form();
-
+
public Table myTable = new Table();
-
+
}
-</screen> In the example above the employeeForm and myTable controls were not added to the page. Also note that Form and Table does not have their names defined. When autobinding is enabled, ClickServlet will create a new Page and add the public controls to the page. In the example above the employeeForm and myTable will be added to the page, as if you had invoked, <emphasis>addControl(employeeForm)</emphasis> and <emphasis>addControl(myTable)</emphasis>. The control's names were not defined so ClickServlet will set their names to the value of their field/variable name. In this case the Form name will be set to employeeForm while the Table name will set to myTable. The above example is thus a shorthand way of writing the following: <screen>
+</programlisting> In the example above the employeeForm and myTable controls were not added to the page. Also note that Form and Table does not have their names defined. When autobinding is enabled, ClickServlet will create a new Page and add the public controls to the page. In the example above the employeeForm and myTable will be added to the page, as if you had invoked, <emphasis>addControl(employeeForm)</emphasis> and <emphasis>addControl(myTable)</emphasis>. The control's names were not defined so ClickServlet will set their names to the value of their field/variable name. In this case the Form name will be set to employeeForm while the Table name will set to myTable. The above example is thus a shorthand way of writing the following: <programlisting>
public class EmployeePage extends Page {
private Form employeeForm = new Form();
-
+
private Table myTable = new Table();
-
+
public void onInit() {
employeeForm.setName("employeeForm");
addControl(employeeForm);
@@ -335,37 +360,36 @@
addControl(myTable);
}
}
-</screen> You can turn this behaviour off by setting the autobinding attribute to false, for example: <screen>
-<click-app>
- <pages package="com.mycorp.page"
+</programlisting> You can turn this behaviour off by setting the autobinding attribute to false, for example: <programlisting>
+<click-app>
+ <pages package="com.mycorp.page"
autobinding="
false"/>
-</click-app>
-</screen><anchor id="configuration.html-application-headers"/><indexterm>
- <primary>application-headers</primary>
- </indexterm>
+</click-app>
+</programlisting>
</para>
</sect3>
</sect2>
- <sect2 remap="h3">
- <title>2.4Â Headers</title>
- <para> The optional <literal>headers</literal> element defines a list of <literal>header</literal> elements which are applied to all pages. <screen>
-<!ELEMENT
+
+ <sect2 id="application-headers" remap="h3">
+ <title>2.4 Headers</title>
+ <para> The optional <literal>headers</literal> element defines a list of <literal>header</literal> elements which are applied to all pages. <programlisting>
+<!ELEMENT
headers (
-header*)>
-</screen> The <literal>header</literal> element defines header name and value pairs which are applied to the <ulink url="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/http/HttpServletResponse.html">HttpServletResponse</ulink>. <screen>
-<!ELEMENT
+header*)>
+</programlisting> The <literal>header</literal> element defines header name and value pairs which are applied to the <ulink url="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/http/HttpServletResponse.html">HttpServletResponse</ulink>. <programlisting>
+<!ELEMENT
header (#PCDATA)>
- <!ATTLIST header
+ <!ATTLIST header
name CDATA #REQUIRED>
- <!ATTLIST header
+ <!ATTLIST header
value CDATA #REQUIRED>
- <!ATTLIST header
+ <!ATTLIST header
type (String|Integer|Date) "String">
-</screen> Page headers are set after the Page has been constructed and before <literal>onInit()</literal> is called. Pages can then modify their <ulink url="click-api/org/apache/click/Page.html#headers">headers</ulink> property using the <ulink url="click-api/org/apache/click/Page.html#setHeader(java.lang.String,%20java.lang.Object)">setHeader()</ulink> method. </para>
- <sect3 remap="h4">
- <title>2.4.1Â Browser Caching</title>
- <para> Headers are typically used to switch off browser caching. By default Click will use the following no caching header values if you don't define a <literal>headers</literal> element in your application: <screen>
+</programlisting> Page headers are set after the Page has been constructed and before <literal>onInit()</literal> is called. Pages can then modify their <ulink url="click-api/org/apache/click/Page.html#headers">headers</ulink> property using the <ulink url="click-api/org/apache/click/Page.html#setHeader(java.lang.String,%20java.lang.Object)">setHeader()</ulink> method. </para>
+ <sect3 id="browser-caching" remap="h4">
+ <title>2.4.1 Browser Caching</title>
+ <para> Headers are typically used to switch off browser caching. By default Click will use the following no caching header values if you don't define a <literal>headers</literal> element in your application: <programlisting>
<click-app>
<pages>
..
@@ -375,7 +399,7 @@
Pragma" value="
no-cache"/>
<header name="
-Cache-Control"
+Cache-Control"
value="
no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/>
<header name="
@@ -384,7 +408,7 @@
Date"/>
</headers>
</click-app>
-</screen> Alternatively you can define your headers individually in pages or for all application pages by setting header values. For example to switch off caching in the login page, note the value for a Date type should be a long number value: <screen>
+</programlisting> Alternatively you can define your headers individually in pages or for all application pages by setting header values. For example to switch off caching in the login page, note the value for a Date type should be a long number value: <programlisting>
<page path="
login.htm" classname="
com.mycorp.page.Login">
@@ -395,17 +419,17 @@
Expires" value="
1" type="
Date"/>
-</page>
-</screen> If you wanted to enable caching for a particular page you could set the following page cache control header. This will mark the page as cachable for a period of 1 hour after which it should be reloaded. <screen>
+</page>
+</programlisting> If you wanted to enable caching for a particular page you could set the following page cache control header. This will mark the page as cachable for a period of 1 hour after which it should be reloaded. <programlisting>
<page path="
home.htm" classname="
com.mycorp.page.Home">
<header name="
Cache-Control" value="
max-age=3600, public, must-revalidate"/>
-</page>
-</screen> To apply header values globally define header values in the headers element. For example: <screen>
-<click-app>
+</page>
+</programlisting> To apply header values globally define header values in the headers element. For example: <programlisting>
+<click-app>
<pages>
..
</pages>
@@ -414,7 +438,7 @@
Pragma" value="
no-cache"/>
<header name="
-Cache-Control"
+Cache-Control"
value="
no-store, no-cache, must-revalidate, post-check=0, pre-check=0"/>
<header name="
@@ -422,34 +446,32 @@
1" type="
Date"/>
</headers>
-</click-app>
-</screen><anchor id="configuration.html-application-format"/><indexterm>
- <primary>application-format</primary>
- </indexterm>
+</click-app>
+</programlisting>
</para>
</sect3>
</sect2>
- <sect2 remap="h3">
- <title>2.5Â Format</title>
- <para> The optional <literal>format</literal> element defines the Format object classname which is applied to all pages. <screen>
-<!ELEMENT
+
+ <sect2 id="application-format" remap="h3">
+ <title>2.5 Format</title>
+ <para> The optional <literal>format</literal> element defines the Format object classname which is applied to all pages. <programlisting>
+<!ELEMENT
format (#PCDATA)>
- <ATTLIST format classname CDATA #FIXED "org.apache.click.util.Format">
-</screen> By default all Click pages are configured with a <ulink url="click-api/org/apache/click/util/Format.html">org.apache.click.util.Format</ulink> object. The format object is made available in the Velocity page templates using the name <literal>$format</literal>. To specify a custom format class configure a <literal>format</literal> element in the click-app descriptor. For example: <screen>
-<click-app>
+ <ATTLIST format classname CDATA #FIXED "org.apache.click.util.Format">
+</programlisting> By default all Click pages are configured with a <ulink url="click-api/org/apache/click/util/Format.html">org.apache.click.util.Format</ulink> object. The format object is made available in the Velocity page templates using the name <literal>$format</literal>. To specify a custom format class configure a <literal>format</literal> element in the click-app descriptor. For example: <programlisting>
+<click-app>
..
<
format classname="
com.mycorp.util.CustomFormat"/>
-</click-app>
-</screen><anchor id="configuration.html-application-mode"/><indexterm>
- <primary>application-mode</primary>
- </indexterm>
+</click-app>
+</programlisting>
</para>
</sect2>
- <sect2 remap="h3">
- <title>2.6Â Mode</title>
- <para> The optional <literal>mode</literal> element defines the application logging and caching mode. <screen>
+
+ <sect2 id="application-mode" remap="h3">
+ <title>2.6 Mode</title>
+ <para> The optional <literal>mode</literal> element defines the application logging and caching mode. <programlisting>
<!ELEMENT mode (#PCDATA)>
<ATTLIST mode value (
production|
@@ -457,16 +479,16 @@
development|
debug|
trace) "development">
-</screen> By default Click applications run in <literal>development</literal> mode, which switches off page template caching, and the logging level is set to <literal>INFO</literal>. To change the default application mode configure a mode element in the click-app descriptor. For example to specify <literal>production</literal> mode you would add the following mode element: <screen>
+</programlisting> By default Click applications run in <literal>development</literal> mode, which switches off page template caching, and the logging level is set to <literal>INFO</literal>. To change the default application mode configure a mode element in the click-app descriptor. For example to specify <literal>production</literal> mode you would add the following mode element: <programlisting>
<click-app>
..
<
mode value="
production">
-</click-app>
-</screen> The application mode configuration can be overridden by setting the system property <literal>"click.mode"</literal>. This can be use in the scenario of debugging a problem on a production system, where you change the mode to <literal>trace</literal> by setting the following system property and restarting the application. <screen>
+</click-app>
+</programlisting> The application mode configuration can be overridden by setting the system property <literal>"click.mode"</literal>. This can be use in the scenario of debugging a problem on a production system, where you change the mode to <literal>trace</literal> by setting the following system property and restarting the application. <programlisting>
-Dclick.mode=trace
-</screen> The Click Application modes and their settings for Page auto loading, template caching and logging levels are: <informaltable frame="none">
+</programlisting> The Click Application modes and their settings for Page auto loading, template caching and logging levels are: <informaltable frame="none">
<tgroup cols="5">
<colspec colname="c1" colwidth="20*"/>
<colspec colname="c2" colwidth="20*"/>
@@ -599,20 +621,23 @@
</tbody>
</tgroup>
</informaltable>
-<anchor id="configuration.html-page-auto-loading"/><indexterm>
- <primary>page-auto-loading</primary>
- </indexterm>
-</para>
- <sect3 remap="h4">
- <title>2.6.1Â Page Auto Loading</title>
- <para> When Page Auto Loading is enabled any new page templates and classes will be automatically loaded at runtime. These pages are loaded using the <link linkend="configuration.html-application-automapping">Page Automapping</link> rules. Page auto loading is a very handy feature for rapid development as you do not have to restart you application server to pick up new pages. <anchor id="configuration.html-click-logging"/><indexterm>
- <primary>click-logging</primary>
- </indexterm>
+
+</para>
+
+ <sect3 id="page-auto-loading" remap="h4">
+ <title>2.6.1 Page Auto Loading</title>
+ <para> When Page Auto Loading is enabled any new page templates and classes
+ will be automatically loaded at runtime. These pages are loaded using the
+ <link linkend="application-automapping">Page Automapping</link> rules. Page
+ auto loading is a very handy feature for rapid development as you do not have
+ to restart you application server to pick up new pages.
+
</para>
</sect3>
- <sect3 remap="h4">
- <title>2.6.2Â Click and Velocity Logging</title>
- <para> The Click and Velocity runtimes use <ulink url="click-api/org/apache/click/service/LogService.html">LogService</ulink> for logging messages. The default LogService implementation is <ulink url="click-api/org/apache/click/service/ConsoleLogService.html">ConsoleLogService</ulink> which will send messages to the console [System.out]. For example the following logging output is for a HomePage request when the application mode is <literal>trace</literal>: <screen>
+
+ <sect3 id="click-logging" remap="h4">
+ <title>2.6.2 Click and Velocity Logging</title>
+ <para> The Click and Velocity runtimes use <ulink url="click-api/org/apache/click/service/LogService.html">LogService</ulink> for logging messages. The default LogService implementation is <ulink url="click-api/org/apache/click/service/ConsoleLogService.html">ConsoleLogService</ulink> which will send messages to the console [System.out]. For example the following logging output is for a HomePage request when the application mode is <literal>trace</literal>: <programlisting>
[Click] [debug] GET http://localhost:8080/quickstart/home.htm
[Click] [trace] invoked: HomePage.<<init>>
[Click] [trace] invoked: HomePage.onSecurityCheck() : true
@@ -621,25 +646,32 @@
[Click] [trace] invoked: HomePage.onRender()
[Click] [info ] renderTemplate: /home.htm - 6 ms
[Click] [trace] invoked: HomePage.onDestroy()
-[Click] [info ] handleRequest: /home.htm - 24 ms
-</screen> Any unhandled <literal>Throwable</literal> errors are logged by the ClickServlet. Note that Click Extras also provide log adaptors for <ulink url="extras-api/org/apache/click/extras/service/Log4JLogService.html">Log4J</ulink> and the <ulink url="extras-api/org/apache/click/extras/service/JdkLogService.html">JDK Logging API</ulink>. When an application is not in <literal>production</literal> mode the error page displays detailed debugging information. When the application mode is <literal>production</literal> no debug information is displayed to prevent sensitive information being revealed. This behaviour can be changed by modifying the deployed <literal>click/error.htm</literal> page template. <anchor id="configuration.html-application-controls"/><indexterm>
- <primary>application-controls</primary>
- </indexterm>
+[Click] [info ] handleRequest: /home.htm - 24 ms
+</programlisting> Any unhandled <literal>Throwable</literal> errors are logged by
+the ClickServlet. Note that Click Extras also provide log adaptors for
+<ulink url="extras-api/org/apache/click/extras/service/Log4JLogService.html">Log4J</ulink>
+and the <ulink url="extras-api/org/apache/click/extras/service/JdkLogService.html">JDK Logging API</ulink>.
+When an application is not in <literal>production</literal> mode the error page
+displays detailed debugging information. When the application mode is <literal>production</literal>
+no debug information is displayed to prevent sensitive information being revealed.
+This behaviour can be changed by modifying the deployed <literal>click/error.htm
+</literal> page template.
</para>
</sect3>
</sect2>
- <sect2 remap="h3">
- <title>2.7Â Controls</title>
- <para> The optional <literal>controls</literal> element defines a list of <literal>control</literal> elements which will be deployed on application startup. <screen>
-<!ELEMENT
+
+ <sect2 id="application-controls" remap="h3">
+ <title>2.7 Controls</title>
+ <para> The optional <literal>controls</literal> element defines a list of <literal>control</literal> elements which will be deployed on application startup. <programlisting>
+<!ELEMENT
controls (
-control*)>
-</screen> The <literal>control</literal> registers <ulink url="click-api/org/apache/click/Control.html">Control</ulink> classes which will have their <ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink> method invoked when the click application starts. <screen>
-<!ELEMENT
+control*)>
+</programlisting> The <literal>control</literal> registers <ulink url="click-api/org/apache/click/Control.html">Control</ulink> classes which will have their <ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink> method invoked when the click application starts. <programlisting>
+<!ELEMENT
control (#PCDATA)>
- <!ATTLIST control
+ <!ATTLIST control
classname CDATA #REQUIRED>
-</screen> For example to have a <literal>CustomField</literal> control deploy its resources on application startup, you would add the following elements to your <literal>click.xml</literal> file: <screen>
+</programlisting> For example to have a <literal>CustomField</literal> control deploy its resources on application startup, you would add the following elements to your <literal>click.xml</literal> file: <programlisting>
<click-app>
..
@@ -649,43 +681,50 @@
"com.mycorp.control.CustomField"/>
</controls>
</click-app>
-</screen><anchor id="configuration.html-auto-deployed-files"/><indexterm>
- <primary>auto-deployed-files</primary>
- </indexterm>
+</programlisting>
</para>
</sect2>
</sect1>
- <sect1 remap="h2">
- <title>3. Auto Deployed Files</title>
+
+ <sect1 id="auto-deployed-files" remap="h2">
+ <title>3. Auto Deployed Files</title>
<para> To make pre-configured resources (templates, stylesheets, etc.) available to web applications, Click automatically deploys configured classpath resources to the <literal>/click</literal> directory at startup (if not already present). You can modify these support files and Click will <emphasis role="bold">not</emphasis> overwrite them. These files include: <itemizedlist>
<listitem>
- <para> click/error.htm  -  the Page <ulink url="pages.html#page-error-handling">Error Handling</ulink> template</para>
+ <para> click/error.htm - the Page <ulink url="pages.html#page-error-handling">Error Handling</ulink> template</para>
</listitem>
<listitem>
- <para> click/control.css  -  the Controls cascading stylesheet</para>
+ <para> click/control.css - the Controls cascading stylesheet</para>
</listitem>
<listitem>
- <para> click/control.js  -  the Controls JavaScript library</para>
+ <para> click/control.js - the Controls JavaScript library</para>
</listitem>
<listitem>
- <para> click/not-found.htm  -  the <ulink url="pages.html#page-not-found">Page Not Found</ulink> template</para>
+ <para> click/not-found.htm - the <ulink url="pages.html#page-not-found">Page Not Found</ulink> template</para>
</listitem>
</itemizedlist>
- It is generally easier to work with unpacked WARs and most servlet containers do just that. However some contains such as WebLogic (at least version 10) does not. To enable WebLogic to unpack the WAR go to the <emphasis>Admin Console > server node > Web Applications</emphasis> tab and check the <emphasis>Archived Real Path Enabled</emphasis> parameter. If Click cannot deploy resources because of restricted file system permissions, warning messages will be logged. If your application server does not unpack the WAR/EAR or has restricted permissions, you will need to package up these auto deployed files in your web applications WAR file. To do this you should run you application on a development machine without these restrictions and then package up the deployed files into the WAR/EAR before deployment. <anchor id="configuration.html-deploying-custom-resources"/><indexterm>
- <primary>deploying-custom-resources</primary>
- </indexterm>
+ It is generally easier to work with unpacked WARs and most servlet containers do just that.
+ However some contains such as WebLogic (at least version 10) does not. To enable
+ WebLogic to unpack the WAR go to the <emphasis>Admin Console > server node > Web Applications</emphasis>
+ tab and check the <emphasis>Archived Real Path Enabled</emphasis> parameter.
+ If Click cannot deploy resources because of restricted file system permissions,
+ warning messages will be logged. If your application server does not unpack the WAR/EAR
+ or has restricted permissions, you will need to package up these auto deployed files
+ in your web applications WAR file. To do this you should run you application on a
+ development machine without these restrictions and then package up the deployed files
+ into the WAR/EAR before deployment.
</para>
- <sect2 remap="h3">
- <title>3.1Â Deploying Custom Resources</title>
+
+ <sect2 id="deploying-custom-resources" remap="h3">
+ <title>3.1 Deploying Custom Resources</title>
<para> Click supports two ways of deploying pre-configured resources (templates, stylesheets, JavaScript etc.) from a Jar to a web applications. <orderedlist>
<listitem>
- <para> Through a Control's <ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink> event handler. See the <link linkend="configuration.html-application-controls">Controls</link> section above.</para>
+ <para> Through a Control's <ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink> event handler. See the <link linkend="application-controls">Controls</link> section above.</para>
</listitem>
<listitem>
<para> By packaging the resources (stylesheets, JavaScript, Images etc.) into a special folder called <emphasis>'META-INF/web'</emphasis>.</para>
</listitem>
</orderedlist>
- As option #1 was already discussed above in section <link linkend="configuration.html-application-controls">2.7 Controls</link>, lets look at option #2. When Click starts up, it scans each Jar in the classpath for specially marked entries starting with 'META-INF/web/'. (Please note that even though Click will scan the entire classpath it is strongly recommended to host your Jar files inside your WAR lib folder e.g. WEB-INF/lib. Sharing Jars on the classpath can lead to class loading issues.) Click will then copy all files found under 'META-INF/web/' to the web application folder. For example, given a Jar file with the following entries: <itemizedlist>
+ As option #1 was already discussed above in section <link linkend="application-controls">2.7 Controls</link>, lets look at option #2. When Click starts up, it scans each Jar in the classpath for specially marked entries starting with 'META-INF/web/'. (Please note that even though Click will scan the entire classpath it is strongly recommended to host your Jar files inside your WAR lib folder e.g. WEB-INF/lib. Sharing Jars on the classpath can lead to class loading issues.) Click will then copy all files found under 'META-INF/web/' to the web application folder. For example, given a Jar file with the following entries: <itemizedlist>
<listitem>
<para> META-INF/web/mycorp/edit_customer.js</para>
</listitem>
@@ -699,4 +738,4 @@
Click will copy the files <emphasis>'/mycorp/edit_customer.js'</emphasis> and <emphasis>'/mycorp/edit_customer.css'</emphasis> to the web application folder. Thus if the web application is called 'webapp', the files will be deployed as <emphasis>'webapp/mycorp/edit_customer.js'</emphasis> and <emphasis>'webapp/mycorp/edit_customer.css'</emphasis>. Option #2 is especially useful when you need to deploy a large number of resources from a Jar. Note, only Jars placed under the <emphasis>'WEB-INF/lib'</emphasis> folder will be deployed. </para>
</sect2>
</sect1>
- </chapter>
+</chapter>
Modified: incubator/click/trunk/tools/docbook/src/docbook/click/chapter-controls.xml
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/src/docbook/click/chapter-controls.xml?rev=741172&r1=741171&r2=741172&view=diff
==============================================================================
--- incubator/click/trunk/tools/docbook/src/docbook/click/chapter-controls.xml (original)
+++ incubator/click/trunk/tools/docbook/src/docbook/click/chapter-controls.xml Thu Feb 5 16:39:47 2009
@@ -1,34 +1,36 @@
-<?xml version='1.0' encoding='UTF-8'?>
- <chapter id="chapter-controls" remap="h1">
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter-controls" remap="h1">
<title>Controls</title>
<para> Click provides a rich set of Controls which support client side rendering and server side processing. This section covers the following topics: </para>
<orderedlist>
<listitem>
- <para><link linkend="anchor-control-interface">Control Interface</link> - describes the Control interface</para>
+ <para><link linkend="control-interface">Control Interface</link> - describes the Control interface</para>
</listitem>
<listitem>
- <para><link linkend="anchor-control-callback">Control Callback</link> - control event callback pattern</para>
+ <para><link linkend="control-callback">Control Callback</link> - control event callback pattern</para>
</listitem>
<listitem>
- <para><link linkend="anchor-control-class">Control Classes</link> - control Java classes</para>
+ <para><link linkend="control-class">Control Classes</link> - control Java classes</para>
</listitem>
<listitem>
- <para><link linkend="anchor-message-properties">Message Properties</link> - control message properties</para>
+ <para><link linkend="message-properties">Message Properties</link> - control message properties</para>
</listitem>
<listitem>
- <para><link linkend="anchor-container">Container</link> - a Container is a Control that can contain other Controls.</para>
+ <para><link linkend="container">Container</link> - a Container is a Control that can contain other Controls.</para>
</listitem>
<listitem>
- <para><link linkend="anchor-layout">Layouts</link> - describes layout options and how to create custom layouts.</para>
+ <para><link linkend="layout">Layouts</link> - describes layout options and how to create custom layouts.</para>
</listitem>
</orderedlist>
+
<para>Â </para>
- <para> While this section provides an overview how Controls work please see the <ulink url="click-api/org/apache/click/control/package-summary.html">Javadoc</ulink>, which provides extensive information and examples. <anchor id="anchor-control-interface"/><indexterm>
- <primary>control-interface</primary>
- </indexterm>
-</para>
- <sect1 id="section-control-interface" remap="h2">
- <title>1. Control Interface</title>
+
+ <para> While this section provides an overview how Controls work please see the
+ <ulink url="click-api/org/apache/click/control/package-summary.html">Javadoc</ulink>,
+ which provides extensive information and examples.</para>
+
+ <sect1 id="control-interface" remap="h2">
+ <title>Control Interface</title>
<para> Controls provide the server side components that process user input, and render their display to the user. Controls are equivalent to Visual Basic Controls or Delphi Components. Controls handle the processing of user input in the <ulink url="click-api/org/apache/click/Control.html#onProcess()">onProcess</ulink> method and render their HTML display using the toString() method. The execution sequence for a Control being processed and rendered is illustrated below in Figure 1. <inlinemediaobject>
<imageobject>
<imagedata fileref="images/controls/control-post-sequence-diagram.png" format="PNG"/>
@@ -72,18 +74,13 @@
<para><ulink url="click-api/org/apache/click/Control.html#onDestroy()">onDestroy()</ulink> - on destroy event handler.</para>
</listitem>
<listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#render(org.apache.click.util.HtmlStringBuffer)">render()</ulink> - generate the control's HTML representation.</para>
+ <para><ulink url="click-api/org/apache/click/Control.html#render(org.apache.click.util.HtmlStringBuffer)">render()</ulink> - generate the control's HTML representation.</para>
</listitem>
</itemizedlist>
- <para>
- <anchor id="anchor-control-callback"/>
- </para>
- <indexterm>
- <primary>control-callback</primary>
- </indexterm>
</sect1>
- <sect1 id="section-control-callback" remap="h2">
- <title>2. Control Callback</title>
+
+ <sect1 id="control-callback" remap="h2">
+ <title>Control Callback</title>
<para> Click Controls provide an event callback mechanism similar to a java.awt.ActionListener callback. Click supports two styles of action listeners, the first is using the ActionListener interface which provides compile time safety. The second is to register the action listener via the setListener(Object, String) method where you specify the call back method via its name. This second style uses less lines of code, but has no compile time safety. Examples of these two action listener styles are provided below: <programlisting>
public class ActionDemo extends BorderPage {
@@ -103,7 +100,7 @@
});
// Succinct but typos will cause runtime errors
- button.setListener(this, "onButtonClick");
+ button.setListener(this, "onButtonClick");
}
// Event Handlers ---------------------------------------------------------
@@ -118,13 +115,23 @@
return true;
}
}
-</programlisting> All call back listener methods must return a boolean value. If they return true the further processing of other controls and page methods should continue. Otherwise if they return false, then any further processing should be aborted. By returning false you can effectively exit at this point and redirect or forward to another page. This execution logic is illustrated in the <ulink url="pages.html#activity-diagram">Page Execution Activity Diagram</ulink>. Being able to stop further processing and do something else can be very handy. For example your Pages onRender() method may perform an expensive database operation. By returning false in an event handler you can skip this step and render the template or forward to the next page. <anchor id="anchor-control-class"/><indexterm>
- <primary>control-class</primary>
- </indexterm>
+</programlisting>
+
+All call back listener methods must return a boolean value. If they return true
+the further processing of other controls and page methods should continue.
+Otherwise if they return false, then any further processing should be aborted.
+By returning false you can effectively exit at this point and redirect or forward
+to another page. This execution logic is illustrated in the
+<ulink url="pages.html#activity-diagram">Page Execution Activity Diagram</ulink>.
+Being able to stop further processing and do something else can be very handy.
+For example your Pages onRender() method may perform an expensive database operation.
+By returning false in an event handler you can skip this step and render the template
+or forward to the next page.
+
</para>
</sect1>
- <sect1 id="section-control-classes" remap="h2">
- <title>3. Control Classes</title>
+ <sect1 id="control-class" remap="h2">
+ <title>Control Classes</title>
<para> Core control classes are defined in the package <ulink url="click-api/org/apache/click/control/package-summary.html">org.apache.click.control</ulink>. This package includes controls for the essential HTML elements. Extended control classes are provided in the Click Extras package <ulink url="extras-api/org/apache/click/extras/control/package-summary.html">org.apache.click.extras.control</ulink>. Click Extras classes can contain dependencies to 3rd party frameworks. A subset of these control classes are depicted below in Figure 3. <inlinemediaobject>
<imageobject>
<imagedata fileref="images/controls/control-package-class-diagram.png" format="PNG"/>
@@ -148,15 +155,19 @@
<para><ulink url="click-api/org/apache/click/control/TextField.html">TextField</ulink> - provides an input type text control which can invoke callback listeners.</para>
</listitem>
</itemizedlist>
- The control classes are designed to support subclassing for customized behaviour. All control fields have protected visibility and have public accessor methods. You can also aggregate controls to build more complex controls. For example the <ulink url="extras-api/org/apache/click/extras/control/CreditCardField.html">CreditCardField</ulink> uses a <ulink url="click-api/org/apache/click/control/Select.html">Select</ulink> control to render the different credit card types. <anchor id="anchor-message-properties"/><indexterm>
- <primary>message-properties</primary>
- </indexterm>
+ The control classes are designed to support subclassing for customized behaviour.
+ All control fields have protected visibility and have public accessor methods.
+ You can also aggregate controls to build more complex controls. For example the
+ <ulink url="extras-api/org/apache/click/extras/control/CreditCardField.html">CreditCardField</ulink>
+ uses a <ulink url="click-api/org/apache/click/control/Select.html">Select</ulink>
+ control to render the different credit card types.
</para>
</sect1>
- <sect1 id="section-message-properties" remap="h2">
- <title>4. Message Properties</title>
+
+ <sect1 id="message-properties" remap="h2">
+ <title>Message Properties</title>
<para> Control strings for field validation messages and HTML formatting strings are externalized in the properties file. By using these properties files you can localize a Click application for your particular language and dialect. </para>
- <sect2 id="section-message-resolution" remap="h3">
+ <sect2 id="message-resolution" remap="h3">
<title>4.1Â Message Resolution</title>
<para> Messages are looked up in a particular order enabling taylor specific messages, for your controls, individual pages or across your entire application. The order in which localized messages are resolved is: <variablelist>
<varlistentry>
@@ -194,7 +205,7 @@
</variablelist>
</para>
</sect2>
- <sect2 id="section-control-properties" remap="h3">
+ <sect2 id="control-properties" remap="h3">
<title>4.2Â Control Properties</title>
<para> To customize the <literal>click-control.properties</literal> simply add this file to your classpath and tailor the specific values. Note when customizing the message properties you must include all the properties, not just the ones you want to override. <programlisting>
# Click Control messages
@@ -205,7 +216,7 @@
file-required-error=You must enter a filename for {0}
label-required-prefix=
-label-required-suffix=<span class="required">*</span>
+label-required-suffix=<span class="required">*</span>
label-not-required-prefix=
label-not-required-suffix=&nbsp;
@@ -225,11 +236,11 @@
table-last-label=Last
table-last-title=Go to last page
table-goto-title=Go to page
-table-page-banner=<span class="pagebanner">{0} items found, displaying {1} to {2}.</span>
+table-page-banner=<span class="pagebanner">{0} items found, displaying {1} to {2}.</span>
table-page-banner-nolinks=
- <span class="pagebanner-nolinks">{0} items found, displaying {1} to {2}.</span>
-table-page-links=<span class="pagelinks">[{0}/{1}] {2} [{3}/{4}]</span>
-table-page-links-nobanner=<span class="pagelinks-nobanner">[{0}/{1}] {2} [{3}/{4}]</span>
+ <span class="pagebanner-nolinks">{0} items found, displaying {1} to {2}.</span>
+table-page-links=<span class="pagelinks">[{0}/{1}] {2} [{3}/{4}]</span>
+table-page-links-nobanner=<span class="pagelinks-nobanner">[{0}/{1}] {2} [{3}/{4}]</span>
table-no-rows-found=No records found.
table-inline-first-image=/click/paging-first.gif
@@ -242,13 +253,14 @@
table-inline-last-disabled-image=/click/paging-last-disabled.gif
table-inline-page-links=Page {0} {1} {2} {3} {4}
-# Message displayed when a error occurs when the application is in "production" mode
+# Message displayed when a error occurs when the application is in "production" mode
production-error-message=
- <div id='errorReport' class='errorReport'>The application encountered an unexpected error.
+ <div id='errorReport' class='errorReport'>The application encountered an unexpected error.
</div>
</programlisting></para>
</sect2>
- <sect2 id="section-accessing-messages" remap="h3">
+
+ <sect2 id="accessing-messages" remap="h3">
<title>4.3Â Accessing Messages</title>
<para> Field classes support a hierarchy of resource bundles for displaying validation error messages and display messages. These localized messages can be accessed through the Field methods: <itemizedlist>
<listitem>
@@ -282,14 +294,15 @@
</para>
</listitem>
</itemizedlist>
- These methods use the <literal>Locale</literal> of the request to lookup the string resource bundle, and use <literal>MessageFormat</literal> for any string formatting. <anchor id="anchor-container"/><indexterm>
- <primary>container</primary>
- </indexterm>
+ These methods use the <literal>Locale</literal> of the request to lookup the
+ string resource bundle, and use <literal>MessageFormat</literal> for any string
+ formatting.
</para>
</sect2>
</sect1>
- <sect1 id="section-container" remap="h2">
- <title>5. Container</title>
+
+ <sect1 id="container" remap="h2">
+ <title>Container</title>
<para>
<ulink url="click-api/org/apache/click/control/Container.html">Container</ulink>
</para>
@@ -324,7 +337,8 @@
</listitem>
</itemizedlist>
Lets cover each of them here. </para>
- <sect2 remap="h3">
+
+ <sect2 id="abstractcontainer" remap="h3">
<title>5.1Â AbstractContainer</title>
<para> Enables easy creation of custom Containers, for example an html <emphasis>div</emphasis> or <emphasis>span</emphasis> element: <programlisting>
public class Div extends AbstractContainer {
@@ -334,8 +348,8 @@
}
public String getTag() {
- // Return the control's HTML tag.
- return "div";
+ // Return the control's HTML tag.
+ return "div";
}
}
</programlisting> Lets try out the newly created Container above: (note the MockContext used in this test is described in the <ulink url="mock-api/overview-summary.html">Mock Test Support</ulink> documentation) <programlisting>
@@ -344,23 +358,23 @@
// Create mock context in which to test the container.
MockContext.initContext();
- // Create a div instance called "mydiv"
- String containerName = "mydiv";
+ // Create a div instance called "mydiv"
+ String containerName = "mydiv";
Div mydiv = new Div(containerName);
// Add a control to the container
- mydiv.add(new TextField("myfield"));
+ mydiv.add(new TextField("myfield"));
System.out.println(mydiv);
}
}
</programlisting> Executing the above example results in the following output: <programlisting>
-<div name="mydiv" id="mydiv">
- <input type="text" name="myfield" id="myfield" value="" size="20" />
+<div name="mydiv" id="mydiv">
+ <input type="text" name="myfield" id="myfield" value="" size="20" />
</div>
</programlisting></para>
</sect2>
- <sect2 id="section-abstractcontainerfield" remap="h3">
+ <sect2 id="abstractcontainerfield" remap="h3">
<title>5.2Â AbstractContainerField</title>
<para> AbstractContainerField extends Field and implements the Container interface. This provides a convenient base class in case you run into a situation where you need both a Field and Container. Below is an example of how AbstractContainerField might be used: <programlisting>
public class FieldAndContainer extends AbstractContainerField {
@@ -371,7 +385,7 @@
// Return the html tag to render
public String getTag() {
- return "div";
+ return "div";
}
}
</programlisting> To test the new class we use the following snippet: <programlisting>
@@ -380,30 +394,29 @@
// Create mock context in which to test the container.
MockContext.initContext();
- // Create a FieldContainer instance called "field_container"
- String containerName = "field_container";
+ // Create a FieldContainer instance called "field_container"
+ String containerName = "field_container";
FieldAndContainer fieldAndContainer = new FieldAndContainer(containerName);
// Add a couple of fields to the container
- fieldAndContainer.add(new TextField("myfield"));
- fieldAndContainer.add(new TextArea("myarea"));
+ fieldAndContainer.add(new TextField("myfield"));
+ fieldAndContainer.add(new TextArea("myarea"));
System.out.println(fieldAndContainer);
}
}
</programlisting> Executing the snippet produces the output: <programlisting>
-<div name="field_container" id="field_container">
- <input type="text" name="myfield" id="myfield" value="" size="20"/>
- <textarea name="myarea" id="myarea" rows="3" cols="20"></textarea>
+<div name="field_container" id="field_container">
+ <input type="text" name="myfield" id="myfield" value="" size="20"/>
+ <textarea name="myarea" id="myarea" rows="3" cols="20"></textarea>
</div>
-</programlisting><anchor id="anchor-layout"/><indexterm>
- <primary>layout</primary>
- </indexterm>
+</programlisting>
</para>
</sect2>
</sect1>
- <sect1 id="section-layouts" remap="h2">
- <title>6. Layouts</title>
+
+ <sect1 id="layout" remap="h2">
+ <title>Layouts</title>
<para> Controls such as <ulink url="click-api/org/apache/click/control/Form.html">Form</ulink> takes care of layout and error reporting automatically, and for many use cases auto-layout is good enough. However for custom or complex layouts, Form is not always the best choice. There are two approaches for creating custom layouts. <itemizedlist>
<listitem>
<para> Template approach - use a template engine such as Velocity, Freemarker or JSP to declare the layout as HTML markup.</para>
@@ -412,11 +425,9 @@
<para> Programmatic approach - build custom layout components using Java. This option is very similar to building components using Swing.</para>
</listitem>
</itemizedlist>
-<anchor id="anchor-template-layout"/><indexterm>
- <primary>template-layout</primary>
- </indexterm>
</para>
- <sect2 remap="h3">
+
+ <sect2 id="template-layout" remap="h3">
<title>6.1Â Template layout</title>
<para> Taking the <ulink url="click-api/org/apache/click/control/Form.html#manual-layout">Template</ulink> approach works well and it separates the Page and layout logic. For example: <programlisting>
// EmployeePage.java
@@ -426,16 +437,16 @@
public void onInit() {
// Create form
- Form form = new Form("form");
+ Form form = new Form("form");
// Add a couple of fields to the form
- form.add(new TextField("firstname"));
- form.add(new TextField("lastname"));
- form.add(new IntegerField("age"));
- form.add(new DoubleField("salary"));
+ form.add(new TextField("firstname"));
+ form.add(new TextField("lastname"));
+ form.add(new IntegerField("age"));
+ form.add(new DoubleField("salary"));
// Add a submit button to form
- form.add(new Submit("submit", "Add Employee"));
+ form.add(new Submit("submit", "Add Employee"));
// Add form the page
addControl(form);
@@ -444,37 +455,45 @@
</programlisting> Lets imagine we want to create a layout using Div <div> and HTML List <ol> tags. We could provide the markup for the employee.htm template as shown below, using a template engine such as Velocity: <programlisting>
<!-- employee.htm -->
${form.startTag()}
- <div style="margin: 1em;">
+ <div style="margin: 1em;">
<ol>
<li>
- <label for="firstname">Firstname:</label>
+ <label for="firstname">Firstname:</label>
${form.fields.firstname}
</li>
<li>
- <label for="lastname">Lastname:</label>
+ <label for="lastname">Lastname:</label>
${form.fields.lastname}
</li>
<li>
- <label for="age">Age:</label>
+ <label for="age">Age:</label>
${form.fields.age}
</li>
<li>
- <label for="salary">Salary:</label>
+ <label for="salary">Salary:</label>
${form.fields.salary}
</li>
</ol>
</div>
${form.fields.submit}
${form.endTag()}
-</programlisting> Using a CSS stylesheet, the markup above can be styled and transformed into a fancy looking form. There are pros and cons to using the template approach. One of the advantages of the Template approach, is that the layout is explicit and one can easily tweak it if needed. For example instead of using divs and ordered lists, one can change the template to leverage a table layout. A disadvantage of the Template approach, is added redundancy. In the example above we created the fields in Java, and laid them out using markup in the template. If the requirements should change to add a new field for example, one will have to add the field in the Page as well as the template. It is also possible to "generify" the layout using template engines. <ulink url="click-api/org/apache/click/control/Form.html#velocity-macros">Macro.vm</ulink> is an example of a generic form layout using Velocity.</para>
- <para>
- <anchor id="anchor-programmatic-layout"/>
- </para>
- <indexterm>
- <primary>programmatic-layout</primary>
- </indexterm>
+</programlisting>
+
+Using a CSS stylesheet, the markup above can be styled and
+transformed into a fancy looking form. There are pros and cons to using the
+template approach. One of the advantages of the Template approach, is that the
+layout is explicit and one can easily tweak it if needed. For example instead of
+using divs and ordered lists, one can change the template to leverage a table layout.
+A disadvantage of the Template approach, is added redundancy. In the example above
+we created the fields in Java, and laid them out using markup in the template. If
+the requirements should change to add a new field for example, one will have to add
+the field in the Page as well as the template. It is also possible to "generify"
+the layout using template engines. <ulink url="click-api/org/apache/click/control/Form.html#velocity-macros">Macro.vm</ulink>
+is an example of a generic form layout using Velocity.</para>
+
</sect2>
- <sect2 id="section-programmatic-layout" remap="h3">
+
+ <sect2 id="programmatic-layout" remap="h3">
<title>6.2Â Programmatic layout</title>
<para> To combat the redundancy introduced by the Template approach, you can take a programmatic approach and use normal Java and some Click classes to build custom layouts. Click extras provides two useful classes in this situation namely, <ulink url="click-api/org/apache/click/extras/control/HtmlForm.html">HtmlForm</ulink> and <ulink url="click-api/org/apache/click/extras/control/HtmlFieldSet.html">HtmlFieldSet</ulink>. Unlike Form and FieldSet which renders its controls using a Table layout, HtmlForm and HtmlFieldSet renders its controls in the order they were added and does not add any extra markup. HtmlForm will be shown in the example below. When creating custom layouts, the HTML construct List <ul> is pretty useful. Since Click does not provide this component, lets create it as shown here: <programlisting>
// HtmlList.java
@@ -482,13 +501,13 @@
public class HtmlList extends AbstractContainer {
public String getTag() {
- return "ol";
+ return "ol";
}
// Can only add ListItems: <li> tags
public Control add(Control control) {
if (!(control instanceof ListItem)) {
- throw new IllegalArgumentException("Only list items can be added.");
+ throw new IllegalArgumentException("Only list items can be added.");
}
return super.add(control);
}
@@ -499,7 +518,7 @@
public class ListItem extends AbstractContainer {
public String getTag() {
- return "li";
+ return "li";
}
}
</programlisting> Another component that will be used in the example below is a FieldLabel which renders an HTML label element for a specified Field. <programlisting>
@@ -517,7 +536,7 @@
}
public String getTag() {
- return "label";
+ return "label";
}
// Override render to produce an html label which produces:
@@ -527,24 +546,24 @@
// Open tag: <label
buffer.elementStart(getTag());
- // Set attribute to target field's id
- setAttribute("for", target.getId());
+ // Set attribute to target field's id
+ setAttribute("for", target.getId());
// Render the labels attributes
appendAttributes(buffer);
- // Close tag: <label for="firstname">
+ // Close tag: <label for="firstname">
buffer.closeTag();
- // Add label text: <label for="firstname">Firstname:
+ // Add label text: <label for="firstname">Firstname:
buffer.append(label);
- // Close tag: <label for="firstname">Firstname:</label>
+ // Close tag: <label for="firstname">Firstname:</label>
buffer.elementEnd(getTag());
}
}
-</programlisting> Now the form can be assembled. Continuing with the employee example from the <link linkend="anchor-template-layout">template approach</link>, we again create an EmployeePage, but this time an HtmlForm and HtmlList is used to create a custom layout: <programlisting>
+</programlisting> Now the form can be assembled. Continuing with the employee example from the <link linkend="template-layout">template approach</link>, we again create an EmployeePage, but this time an HtmlForm and HtmlList is used to create a custom layout: <programlisting>
// EmployeePage.java
public class EmployeePage extends Page {
// A form instance variable
@@ -553,20 +572,20 @@
// Build the form when the page is initialized
public void onInit() {
// Create an HtmlForm which is ideal for composing manual layouts
- form = new HtmlForm("form");
+ form = new HtmlForm("form");
// Create a list and add it to the form.
HtmlList list = new HtmlList();
form.add(list);
// Add firstname field and pass in its name, label and the list to add the field to
- addTextField("firstname", "Firstname:", list);
- addTextField("lastname", "Lastname:", list);
- addTextField("age", "Age:", list);
- addTextField("salary", "Salary:", list);
+ addTextField("firstname", "Firstname:", list);
+ addTextField("lastname", "Lastname:", list);
+ addTextField("age", "Age:", list);
+ addTextField("salary", "Salary:", list);
// Add a submit button to form
- form.add(new Submit("submit", "Add Employee"));
+ form.add(new Submit("submit", "Add Employee"));
// Add the form to the page
addControl(form);
@@ -582,14 +601,14 @@
Field field = new TextField(nameStr);
// Create a field label, which associates the label with the field id.
- // label.toString would output: <label for="firstname">Firstname:</name>
+ // label.toString would output: <label for="firstname">Firstname:</name>
FieldLabel label = new FieldLabel(field, labelStr);
// Next add the label and field to the list item.
// item.toString would then produce:
// <li>
- // <label for="firstname">Firstname:</name>
- // <input type="text" name="firstname" id="form_firstname" value="" size="20"/>
+ // <label for="firstname">Firstname:</name>
+ // <input type="text" name="firstname" id="form_firstname" value="" size="20"/>
// </li>
//
item.add(label);
@@ -601,29 +620,29 @@
${form}
</programlisting> which produces the following markup: <programlisting>
<!-- employee.htm -->
-<form method="post" id="form" action="/myapp/employee.htm">
-<input type="hidden" name="form_name" id="form_form_name" value="form"/>
+<form method="post" id="form" action="/myapp/employee.htm">
+<input type="hidden" name="form_name" id="form_form_name" value="form"/>
<ol>
<li>
- <label for="firstname">Firstname:</label>
- <input type="text" name="firstname" id="form_firstname" value="" size="20"/>
+ <label for="firstname">Firstname:</label>
+ <input type="text" name="firstname" id="form_firstname" value="" size="20"/>
</li>
<li>
- <label for="lastname">Lastname:</label>
- <input type="text" name="lastname" id="form_lastname" value="" size="20"/>
+ <label for="lastname">Lastname:</label>
+ <input type="text" name="lastname" id="form_lastname" value="" size="20"/>
</li>
<li>
- <label for="age">Age:</label>
- <input type="text" name="age" id="form_age" value="" size="20"/>
+ <label for="age">Age:</label>
+ <input type="text" name="age" id="form_age" value="" size="20"/>
</li>
<li>
- <label for="salary">Salary:</label>
- <input type="text" name="salary" id="form_salary" value="" size="20"/>
+ <label for="salary">Salary:</label>
+ <input type="text" name="salary" id="form_salary" value="" size="20"/>
</li>
</ol>
- <input type="submit" name="submit" id="form_submit" value="Add Employee"/>
+ <input type="submit" name="submit" id="form_submit" value="Add Employee"/>
</form>
-</programlisting> Again using a CSS stylesheet, the markup above can be styled and transformed into a fancy looking form. There is a <ulink url="http://www.avoka.com/click-examples/form/contact-details.htm">live demo</ulink> showing the programmatic approach. The advantage of the programmatic approach is that there is no redundancy. Each Field is created and added using normal Java. There is no need to specify where the Field must reside in the markup. If new requirements arrive and more fields added, only the Page has to be updated. No need to change the template as the layout is taken care of by the CSS and markup produced by the components. A disadvantage is that it is harder to <emphasis>visualize</emphasis> what output would be rendered by the containers. Whether you use the <link linkend="anchor-template-layout">template</link> or <link linkend="anchor-programmatic-layout">programmatic</link> layout approach, is up to you. Both work well and have advantages and disadva
ntages over the other. </para>
+</programlisting> Again using a CSS stylesheet, the markup above can be styled and transformed into a fancy looking form. There is a <ulink url="http://www.avoka.com/click-examples/form/contact-details.htm">live demo</ulink> showing the programmatic approach. The advantage of the programmatic approach is that there is no redundancy. Each Field is created and added using normal Java. There is no need to specify where the Field must reside in the markup. If new requirements arrive and more fields added, only the Page has to be updated. No need to change the template as the layout is taken care of by the CSS and markup produced by the components. A disadvantage is that it is harder to <emphasis>visualize</emphasis> what output would be rendered by the containers. Whether you use the <link linkend="template-layout">template</link> or <link linkend="programmatic-layout">programmatic</link> layout approach, is up to you. Both work well and have advantages and disadvantages over th
e other. </para>
</sect2>
</sect1>
</chapter>
\ No newline at end of file