You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by sa...@apache.org on 2009/02/17 17:53:14 UTC
svn commit: r745145 [3/6] - in /incubator/click/trunk/tools/docbook/src:
docbook/click/ images/ images/best-practices/ images/configuration/
images/controls/ images/introduction/ images/pages/ resources/
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=745145&r1=745144&r2=745145&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 Tue Feb 17 16:53:13 2009
@@ -1,88 +1,203 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
<chapter id="chapter-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>
+ <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="control-interface">Control Interface</link> - describes
+ the Control interface
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="control-callback">Control Callback</link> - control
+ event callback pattern
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="control-class">Control Classes</link> - control Java
+ classes
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="control-message-properties">Control Message Properties</link>
+ - control message properties
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="container">Container</link> - a Container is a Control
+ that can contain other Controls.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="layout">Layouts</link> - describes layout options and
+ how to create custom layouts.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <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.
+ </para>
+
+ <para>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
+ in the figure below.
+ </para>
+
+ <figure id="control-post-sequence-diagram">
+ <title>Post Sequence Diagram - created with Enterprise Architect
+ courtesy <ulink url="http://www.sparxsystems.com.au">Sparx Systems</ulink>
+ </title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/controls/control-post-sequence-diagram.png" format="PNG" scale="85"/>
+ </imageobject>
+ </inlinemediaobject>
+ </figure>
+
+ <para>In Click all control classes must implement the
+ <ulink url="click-api/org/apache/click/Control.html">Control</ulink> interface.
+ The Control interface is depicted in the figure below.
+ </para>
+
+ <figure id="control-class-diagram">
+ <title>Control Interface Diagram - created with Enterprise Architect
+ courtesy <ulink url="http://www.sparxsystems.com.au">Sparx Systems</ulink>
+ </title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/controls/control-class-diagram.png" format="PNG" scale="85"/>
+ </imageobject>
+ </inlinemediaobject>
+ </figure>
+
+ <para>Methods on the Control interface include:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#getHtmlImports()">getHtmlImports()</ulink>
+ - defines the controls HTML header imports.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#getMessages()">getMessages()</ulink>
+ - defines the controls localized messages map.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#getName()">getName()</ulink> /
+ <ulink url="click-api/org/apache/click/Control.html#setName(java.lang.String)">setName()</ulink>
+ Â - Â defines the controls name in the Page model or Form fields.
+ </para>
+ </listitem>
<listitem>
- <para><link linkend="control-interface">Control Interface</link> - describes the Control interface</para>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#getParent()">getParent()</ulink> /
+ <ulink url="click-api/org/apache/click/Control.html#setParent(java.lang.Object)">setParent()</ulink>
+ Â - Â defines the controls parent.
+ </para>
</listitem>
<listitem>
- <para><link linkend="control-callback">Control Callback</link> - control event callback pattern</para>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink>
+ - deploy resources on startup.
+ </para>
</listitem>
<listitem>
- <para><link linkend="control-class">Control Classes</link> - control Java classes</para>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#onInit()">onInit()</ulink>
+ - on initialize event handler.
+ </para>
</listitem>
<listitem>
- <para><link linkend="message-properties">Message Properties</link> - control message properties</para>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#onProcess()">onProcess()</ulink>
+ - process request event handler.
+ </para>
</listitem>
<listitem>
- <para><link linkend="container">Container</link> - a Container is a Control that can contain other Controls.</para>
+ <para>
+ <ulink url="click-api/org/apache/click/Control.html#onDestroy()">onDestroy()</ulink>
+ - on destroy event handler.
+ </para>
</listitem>
<listitem>
- <para><link linkend="layout">Layouts</link> - describes layout options and how to create custom layouts.</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>
- </orderedlist>
+ </itemizedlist>
- <para>Â </para>
+ </sect1>
- <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-callback" remap="h2">
+ <title>Control Callback</title>
- <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"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para><emphasis role="bold">Figure 1. Â Post Sequence Diagram</emphasis> - created with Enterprise Architect courtesy <ulink url="http://www.sparxsystems.com.au">Sparx Systems</ulink></para>
- <para> In Click all control classes must implement the <ulink url="click-api/org/apache/click/Control.html">Control</ulink> interface. The Control interface is depicted below in Figure 2. </para>
- <para>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/controls/control-class-diagram.png" format="PNG"/>
- </imageobject>
- </inlinemediaobject>
- </para>
- <para><emphasis role="bold">Figure 2. Â Control Interface Diagram</emphasis> - created with Enterprise Architect courtesy <ulink url="http://www.sparxsystems.com.au">Sparx Systems</ulink></para>
- <para> Methods on the Control interface include: </para>
- <itemizedlist>
- <listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#getHtmlImports()">getHtmlImports()</ulink> - defines the controls HTML header imports.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#getMessages()">getMessages()</ulink> - defines the controls localized messages map.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#getName()">getName()</ulink> / <ulink url="click-api/org/apache/click/Control.html#setName(java.lang.String)">setName()</ulink> Â - Â defines the controls name in the Page model or Form fields.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#getParent()">getParent()</ulink> / <ulink url="click-api/org/apache/click/Control.html#setParent(java.lang.Object)">setParent()</ulink> Â - Â defines the controls parent.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#onDeploy(javax.servlet.ServletContext)">onDeploy()</ulink> - deploy resources on startup.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#onInit()">onInit()</ulink> - on initialize event handler.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/Control.html#onProcess()">onProcess()</ulink> - process request event handler.</para>
- </listitem>
- <listitem>
- <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>
- </listitem>
- </itemizedlist>
- </sect1>
+ <para>Click Controls provide an event callback mechanism similar to a
+ <classname>java.awt.ActionListener</classname> callback.
+ </para>
+
+ <para>Click supports two styles of action listeners. The first is using the
+ <ulink url="click-api/org/apache/click/ActionListener.html">ActionListener</ulink>
+ interface and
+ <ulink url="click-api/org/apache/click/control/AbstractControl.html#setActionListener(org.apache.click.ActionListener)">setActionListener(ActionListener)</ulink>
+ method which provides compile time safety.
+ </para>
+
+ <para>The second is to register the action listener via the
+ <ulink url="click-api/org/apache/click/Control.html#setListener(java.lang.Object, java.lang.String)">setListener(Object, String)</ulink>
+ 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.
+ </para>
- <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 {
+ <para>Examples of these two action listener styles are provided below:
+ </para>
+
+ <programlisting>public class ActionDemo extends BorderPage {
// Uses listener style 1
public ActionLink link = new ActionLink();
@@ -103,7 +218,7 @@
button.setListener(this, "onButtonClick");
}
- // Event Handlers ---------------------------------------------------------
+ // Event Handlers ---------------------------------------------------------
public boolean onLinkClick(Control source) {
..
@@ -114,101 +229,200 @@
..
return true;
}
-}
-</programlisting>
+}</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="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"/>
- </imageobject>
- </inlinemediaobject>
- <emphasis role="bold">Figure 3. Â Package Class Diagram</emphasis> - created with Enterprise Architect courtesy <ulink url="http://www.sparxsystems.com.au">Sparx Systems</ulink></para>
- <para> The key control classes include: <itemizedlist>
- <listitem>
- <para><ulink url="click-api/org/apache/click/control/ActionLink.html">ActionLink</ulink> - provides an anchor link which can invoke callback listeners.</para>
- </listitem>
+ <para>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 <link linkend="activity-diagram">Page Execution Activity Diagram</link>.
+ </para>
+
+ <para>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="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.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>A subset of these control classes are depicted in the figure below.
+ </para>
+
+ <figure id="control-package-class-diagram">
+ <title>Package Class Diagram - created with Enterprise Architect
+ courtesy <ulink url="http://www.sparxsystems.com.au">Sparx Systems</ulink>
+ </title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/controls/control-package-class-diagram.png" format="PNG" scale="75"/>
+ </imageobject>
+ </inlinemediaobject>
+ </figure>
+
+ <para>The key control classes include:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/ActionLink.html">ActionLink</ulink>
+ - provides an anchor link which can invoke callback listeners.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/Field.html">Field</ulink>
+ - provides the abstract form field control.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/Form.html">Form</ulink>
+ - provides a form control for processing, validation and rendering.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/Submit.html">Submit</ulink>
+ - provides an input type submit control which can invoke callback listeners.
+ </para>
+ </listitem>
+ <listitem>
+ <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>
+
+ <para>The control classes are designed to support subclassing for customized
+ behaviour. All control fields have protected visibility and have public
+ accessor methods.
+ </para>
+
+ <para>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="control-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="message-resolution" remap="h3">
+ <title>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:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">Page scope messages</emphasis></term>
<listitem>
- <para><ulink url="click-api/org/apache/click/control/Field.html">Field</ulink> - provides the abstract form field control.</para>
+ <para>Message lookups are first resolved to the Page classes message
+ bundle if it exists. For example a <classname>Login</classname> page
+ may define the message properties:
+ </para>
+
+ <literallayout>/com/mycorp/page/Login.properties</literallayout>
+
+ <para>If you want to tailor messages for a particular page this is
+ where to place them.
+ </para>
+
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">Global page scope messages</emphasis></term>
<listitem>
- <para><ulink url="click-api/org/apache/click/control/Form.html">Form</ulink> - provides a form control for processing, validation and rendering.</para>
+ <para>Next message lookups are resolved to the global pages message
+ bundle if it exists.
+ </para>
+
+ <literallayout>/click-page.properties</literallayout>
+
+ <para>If you want messages to be used across your entire application
+ this is where to place them.
+ </para>
+
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <para> </para>
+ <term><emphasis role="bold">Control scope messages</emphasis></term>
<listitem>
- <para><ulink url="click-api/org/apache/click/control/Submit.html">Submit</ulink> - provides an input type submit control which can invoke callback listeners.</para>
+ <para>Next message lookups are resolved to the Control classes
+ message bundle if it exists. For example a
+ <classname>CustomTextField</classname> control may define the
+ message properties:
+ </para>
+
+ <literallayout>/com/mycorp/control/CustomTextField.properties</literallayout>
+
+ <para>A custom control's messages can be placed here
+ (or the global control scope covered next) and overridden by one of the
+ above options.
+ </para>
+
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">Global control scope messages</emphasis></term>
<listitem>
- <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>
+ <para>Finally message lookups are resolved to the global application
+ control message bundle if the message has not already been found.
+ The global control properties file is:
+ </para>
+
+ <literallayout>/click-control.properties</literallayout>
+
+ <para>Control messages can be placed here and overridden by one of
+ the above options.
+ </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.
-</para>
- </sect1>
-
- <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="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>
- <term>4.1.1Â Page scope messages</term>
- <listitem>
- <para>Message lookups are first resolved to the Page classes message bundle if it exists. For example a <literal>Login</literal> page may define the message properties: <programlisting>
- /com/mycorp/page/Login.properties
-</programlisting> If you want to tailor messages for a particular page this is where to place them.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>4.1.2Â Global page scope messages</term>
- <listitem>
- <para>Next message lookups are resolved to the global pages message bundle if it exists. <programlisting>
- /click-page.properties
-</programlisting> If you want messages to be used across your entire application this is where to place them.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>4.1.3Â Control scope messages</term>
- <listitem>
- <para>Next message lookups are resolved to the Control classes message bundle if it exists. For example a <literal>CustomTextField</literal> control may define the message properties: <programlisting>
- /com/mycorp/control/CustomTextField.properties
-</programlisting></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>4.1.4Â Global control scope messages</term>
- <listitem>
- <para>Finally message lookups are resolved to the global application control message bundle if the message has not already been found. The global control properties file is: <programlisting>
- /click-control.properties
-</programlisting></para>
- </listitem>
- </varlistentry>
- </variablelist>
-</para>
- </sect2>
- <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
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="control-properties" remap="h3">
+ <title>Control Properties</title>
+
+ <para>To customize the <filename>click-control.properties</filename> simply
+ add this file to your classpath and tailor the specific values.
+ </para>
+
+ <para>Note when customizing the message properties you must include all
+ the properties, not just the ones you want to override.
+ </para>
+
+ <literallayout># Click Control messages
field-maxlength-error={0} must be no longer than {1} characers
field-minlength-error={0} must be at least {1} characters
field-required-error=You must enter a value for {0}
@@ -257,92 +471,132 @@
production-error-message=
<div id='errorReport' class='errorReport'>The application encountered an unexpected error.
</div>
-</programlisting></para>
- </sect2>
+ </literallayout>
- <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>
- <para>
- <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessage(java.lang.String)">getMessage(String)</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessage(java.lang.String,%20java.lang.Object)">getMessage(String, Object)</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessage(java.lang.String,%20java.lang.Object[])">getMessage(String, Object[])</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessages()">getMessages()</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="click-api/org/apache/click/control/Field.html#setErrorMessage(java.lang.String)">setErrorMessage(String)</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="click-api/org/apache/click/control/Field.html#setErrorMessage(java.lang.String,%20java.lang.Object)">setErrorMessage(String, Object)</ulink>
- </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.
-</para>
- </sect2>
- </sect1>
+ </sect2>
- <sect1 id="container" remap="h2">
- <title>Container</title>
- <para>
- <ulink url="click-api/org/apache/click/control/Container.html">Container</ulink>
+ <sect2 id="accessing-messages" remap="h3">
+ <title>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:
</para>
- <para> is a Control that can contain other Controls, thus forming a hierarchy of components. Container enables components to add, remove and retrieve other controls. Listed below are example Containers: <itemizedlist>
- <listitem>
- <para><ulink url="click-api/org/apache/click/control/Form.html">Form</ulink> - an HTML form which provides default layout of fields and error feedback.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/control/Panel.html">Panel</ulink> - similar to <ulink url="click-api/org/apache/click/Page.html">Page</ulink>, this Container provides its own template and model.</para>
- </listitem>
- <listitem>
- <para><ulink url="click-api/org/apache/click/control/FieldSet.html">FieldSet</ulink> - draws a legend (border) around its child Controls.</para>
- </listitem>
- </itemizedlist>
-</para>
- <para> These Containers are depicted below in Figure 4. <inlinemediaobject>
- <imageobject>
- <imagedata fileref="./../images/container-package-class-diagram.png" format="PNG"/>
- </imageobject>
- </inlinemediaobject>
- <emphasis role="bold">Figure 4. Â Containers Class Diagram</emphasis></para>
- <para> The following classes provides convenient extension points for creating custom Containers: <itemizedlist>
- <listitem>
- <para>
- <ulink url="click-api/org/apache/click/control/AbstractContainer.html">AbstractContainer</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="click-api/org/apache/click/extras/control/AbstractContainerField.html">AbstractContainerField</ulink>
- </para>
- </listitem>
- </itemizedlist>
- Lets cover each of them here. </para>
- <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 {
-
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessage(java.lang.String)">getMessage(String)</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessage(java.lang.String,%20java.lang.Object)">getMessage(String, Object)</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessage(java.lang.String,%20java.lang.Object[])">getMessage(String, Object[])</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/AbstractControl.html#getMessages()">getMessages()</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/Field.html#setErrorMessage(java.lang.String)">setErrorMessage(String)</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/Field.html#setErrorMessage(java.lang.String,%20java.lang.Object)">setErrorMessage(String, Object)</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These methods use the <literal>Locale</literal> of the request to
+ lookup the string resource bundle, and use <classname>MessageFormat</classname>
+ for any string formatting.
+ </para>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="container" remap="h2">
+ <title>Container</title>
+
+ <para><ulink url="click-api/org/apache/click/control/Container.html">Container</ulink>
+ is a Control that can contain other Controls, thus forming a hierarchy
+ of components. Container enables components to add, remove and retrieve other
+ controls. Listed below are example Containers:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/Form.html">Form</ulink>
+ - an HTML form which provides default layout of fields and error feedback.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/Panel.html">Panel</ulink>
+ - similar to
+ <ulink url="click-api/org/apache/click/Page.html">Page</ulink>, this
+ Container provides its own template and model.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/FieldSet.html">FieldSet</ulink>
+ - draws a legend (border) around its child Controls.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These Containers are depicted in the figure below.
+ </para>
+
+ <figure id="container-package-class-diagram">
+ <title>Container Class Diagram</title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/controls/container-package-class-diagram.png" format="PNG" scale="70"/>
+ </imageobject>
+ </inlinemediaobject>
+ </figure>
+
+ <para>The following classes provides convenient extension points for creating
+ custom Containers:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/control/AbstractContainer.html">AbstractContainer</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="click-api/org/apache/click/extras/control/AbstractContainerField.html">AbstractContainerField</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Lets cover each of them here.
+ </para>
+
+ <sect2 id="abstractcontainer" remap="h3">
+ <title>AbstractContainer</title>
+
+ <para>Enables easy creation of custom Containers, for example an html
+ <emphasis>div</emphasis> or <emphasis>span</emphasis> element:
+ </para>
+
+ <programlisting>public class Div extends AbstractContainer {
+
public Div(String name) {
super(name);
}
@@ -351,9 +605,15 @@
// 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>
-public class Test {
+}</programlisting>
+
+ <para>Lets try out the newly created <classname>Container</classname>
+ above: (note the <classname>MockContext</classname> used in this test is
+ described in the <ulink url="mock-api/overview-summary.html">Mock Test Support</ulink>
+ documentation)
+ </para>
+
+ <programlisting>public class Test {
public static void main (String args[]) {
// Create mock context in which to test the container.
MockContext.initContext();
@@ -361,23 +621,35 @@
// 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"));
System.out.println(mydiv);
}
-}
-</programlisting> Executing the above example results in the following output: <programlisting>
-<div name="mydiv" id="mydiv">
+}</programlisting>
+
+ <para>Executing the above example results in the following output:
+ </para>
+
+ <programlisting><div name="mydiv" id="mydiv">
<input type="text" name="myfield" id="myfield" value="" size="20" />
-</div>
-</programlisting></para>
- </sect2>
- <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 {
+</div></programlisting>
+
+ </sect2>
+
+ <sect2 id="abstractcontainerfield" remap="h3">
+ <title>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.
+ </para>
+
+ <para>Below is an example of how AbstractContainerField might be used:
+ </para>
+
+ <programlisting>public class FieldAndContainer extends AbstractContainerField {
public FieldAndContainer(String name) {
super(name);
@@ -387,9 +659,12 @@
public String getTag() {
return "div";
}
-}
-</programlisting> To test the new class we use the following snippet: <programlisting>
-public class Test {
+}</programlisting>
+
+ <para>To test the new class we use the following snippet:
+ </para>
+
+ <programlisting>public class Test {
public static void main (String args[]) {
// Create mock context in which to test the container.
MockContext.initContext();
@@ -397,48 +672,75 @@
// 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"));
System.out.println(fieldAndContainer);
}
-}
-</programlisting> Executing the snippet produces the output: <programlisting>
-<div name="field_container" id="field_container">
+}</programlisting>
+
+ <para>Executing the snippet produces the output:
+ </para>
+
+ <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>
-</programlisting>
-</para>
- </sect2>
- </sect1>
-
- <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>
- </listitem>
- <listitem>
- <para> Programmatic approach - build custom layout components using Java. This option is very similar to building components using Swing.</para>
- </listitem>
- </itemizedlist>
-</para>
+</div></programlisting>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="layout" remap="h2">
+ <title>Layouts</title>
- <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
+ <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 the auto-layout approach is good enough. It is certainly very productive.
+ </para>
+
+ <para>However for custom or complex layouts, auto-layout is not always the best
+ choice. There are two approaches for creating custom layouts.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Template approach - use a template engine such as Velocity,
+ Freemarker or JSP to declare the layout as HTML markup.
+ </para>
+ </listitem>
+ <listitem>
+ <para> Programmatic approach - build custom layout components using Java.
+ This option is very similar to building components using Swing.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2 id="template-layout" remap="h3">
+ <title>Template layout</title>
+
+ <para>The <ulink url="click-api/org/apache/click/control/Form.html#manual-layout">Template</ulink>
+ approach separates the Page and layout logic. The Page is used to implement
+ the presentation logic such as creating controls, registering listeners
+ and copying data to domain objects, while the template is used to layout
+ the Page controls.
+ </para>
+
+ <para>Lets walk through an example using the template approach. Below
+ we create an EmployeePage which contains a Form and a bunch of fields
+ and submit button.
+ </para>
+
+ <programlisting>// EmployeePage.java
public EmployeePage extends Page {
private Form form;
-
+
public void onInit() {
// Create form
Form form = new Form("form");
-
+
// Add a couple of fields to the form
form.add(new TextField("firstname"));
form.add(new TextField("lastname"));
@@ -451,9 +753,17 @@
// Add form the page
addControl(form);
}
-}
-</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 -->
+}</programlisting>
+
+ <para>Lets imagine we want to create a layout using the HTML tags,
+ <div> and <ol>.
+ </para>
+
+ <para>We would then provide the markup for the <varname>employee.htm</varname>
+ template as shown below, using a template engine such as Velocity:
+ </para>
+
+ <programlisting><!-- employee.htm -->
${form.startTag()}
<div style="margin: 1em;">
<ol>
@@ -476,28 +786,65 @@
</ol>
</div>
${form.fields.submit}
-${form.endTag()}
-</programlisting>
+${form.endTag()}</programlisting>
+
+ <para>Using CSS the markup above can further be styled and transformed
+ into a nice looking form.
+ </para>
+
+ <para>There are pros and cons to using the template approach.
+ </para>
+
+ <para>One of the advantages 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.
+ </para>
+
+ <para>A disadvantage 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.
+ </para>
+
+ <para>However it is possible to "generify" the layout using template
+ engines such as Velocity, Freemarker and JSP.
+ <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="programmatic-layout" remap="h3">
+ <title>Programmatic layout</title>
-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="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
-// Create a list <ol> html element, that accepts <li> elements as children
+ <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.
+ </para>
+
+ <para>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>.
+ </para>
+
+ <para>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 used in the
+ examples below.
+ </para>
+
+ <para>To make it easy to compare the two layout approaches we will recreate
+ the example from the template layout section, but using the programmatic
+ approach.
+ </para>
+
+ <para>When creating custom layouts, the HTML construct List <ul> is
+ pretty useful. Since Click does not provide this component, we will create
+ it as shown below. First we create the HTML list element <ol>, to
+ which list item elements <li> can be added:
+ </para>
+
+ <programlisting>// HtmlList.java
public class HtmlList extends AbstractContainer {
public String getTag() {
@@ -511,19 +858,24 @@
}
return super.add(control);
}
-}
-</programlisting><programlisting>
-// ListItem.java
-// Create a listItem <li> element
+}</programlisting>
+
+ <para>Next we create the HTML list item element <li>:
+ </para>
+
+ <programlisting>// ListItem.java
public class ListItem extends AbstractContainer {
public String getTag() {
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>
-// FieldLabel.java
-// Create an html <label> element for a specified Field
+}</programlisting>
+
+ <para>Another component that will be used in the example is a FieldLabel
+ which renders an HTML label element for a target Field.
+ </para>
+
+ <programlisting>// FieldLabel.java
public class FieldLabel extends AbstractControl {
private Field target;
@@ -539,9 +891,7 @@
return "label";
}
- // Override render to produce an html label which produces:
- //
-Firstname:
+ // Override render to produce an html label for the specified field.
public void render(HtmlStringBuffer buffer) {
// Open tag: <label
buffer.elementStart(getTag());
@@ -562,9 +912,16 @@
buffer.elementEnd(getTag());
}
-}
-</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
+}</programlisting>
+
+ <para>Now the form can be assembled. Continuing with the employee example
+ from the <link linkend="template-layout">template approach</link>, we again
+ create an <classname>EmployeePage</classname>, but this time an
+ <classname>HtmlForm</classname> and <classname>HtmlList</classname> is used
+ to create the custom layout:
+ </para>
+
+ <programlisting>// EmployeePage.java
public class EmployeePage extends Page {
// A form instance variable
private HtmlForm form;
@@ -573,24 +930,24 @@
public void onInit() {
// Create an HtmlForm which is ideal for composing manual layouts
form = new HtmlForm("form");
-
- // Create a list and add it to the 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);
-
+
// Add a submit button to form
form.add(new Submit("submit", "Add Employee"));
// Add the form to the page
addControl(form);
}
-
+
// Provide a helper method to add fields to the form
private void addTextField(String nameStr, String labelStr, List list) {
// Create a new ListItem <li> and add it to the List
@@ -599,7 +956,7 @@
// Create a textfield with the specified name
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>
FieldLabel label = new FieldLabel(field, labelStr);
@@ -614,13 +971,20 @@
item.add(label);
item.add(field);
}
-}
-</programlisting> Now the employee.htm template would only need to specify the name of the top level component, in this case <emphasis>form</emphasis>. <programlisting>
-<!--employee.htm-->
-${form}
-</programlisting> which produces the following markup: <programlisting>
-<!-- employee.htm -->
-<form method="post" id="form" action="/myapp/employee.htm">
+}</programlisting>
+
+ <para>And lastly the <filename>employee.htm</filename> template would only
+ need to specify the name of the top level component, in this case
+ <varname>form</varname>.
+ </para>
+
+ <programlisting><!--employee.htm-->
+${<varname>form</varname>}</programlisting>
+
+ <para>which produces the following markup:
+ </para>
+
+ <programlisting><form method="post" id="form" action="/myapp/employee.htm">
<input type="hidden" name="form_name" id="form_form_name" value="form"/>
<ol>
<li>
@@ -641,8 +1005,42 @@
</li>
</ol>
<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="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
+</form></programlisting>
+
+ <para>Again using a CSS stylesheet, the markup above can be styled and
+ transformed into a fancy looking form.
+ </para>
+
+ <para>There is a <ulink url="http://www.avoka.com/click-examples/form/contact-details.htm">live demo</ulink>
+ showing the programmatic approach.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>If new requirements arrive and more fields added, only the Page needs
+ to change. There is no need to change the template as the layout is taken
+ care of by CSS and the markup produced by the components.
+ </para>
+
+ <para>Disadvantages are that more upfront work is needed to write the
+ components and it is more difficult to
+ <emphasis>visualize</emphasis> what output would be rendered by the
+ components.
+ </para>
+
+ <para>However once your custom layout components are in place, it can be
+ reused across your project and boost productivity.
+ </para>
+
+ <para>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 the
+ other.
+ </para>
+
+ </sect2>
+ </sect1>
+</chapter>