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 [4/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-introduction.xml
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/src/docbook/click/chapter-introduction.xml?rev=745145&r1=745144&r2=745145&view=diff
==============================================================================
--- incubator/click/trunk/tools/docbook/src/docbook/click/chapter-introduction.xml (original)
+++ incubator/click/trunk/tools/docbook/src/docbook/click/chapter-introduction.xml Tue Feb 17 16:53:13 2009
@@ -1,145 +1,212 @@
<?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-introduction">
- <title>Introduction to Click</title>
+ <title>Introduction to Click</title>
- <section id="preface">
- <title>Preface</title>
+ <sect1 id="preface">
+ <title>Preface</title>
- <para>Click is a simple JEE web application framework for commercial
- Java developers.</para>
+ <para>Click is a simple JEE web application framework for commercial
+ Java developers.
+ </para>
+
+ <para>Click is an open source project, licensed under the
+ <ulink url="../../resources/LICENSE.txt"><citetitle>Apache license</citetitle>
+ </ulink>.
+ </para>
+
+ <para>Click uses an event based programming model for processing Servlet
+ requests and <ulink url="velocity/velocity.html">Velocity</ulink> for
+ rendering the response. (Note other template engines such as
+ <ulink url="http://java.sun.com/products/jsp/">JSP</ulink> and
+ <ulink url="http://freemarker.sourceforge.net/">Freemarker</ulink> are also
+ supported)
+ </para>
+
+ <para>This framework uses a single servlet, called
+ <ulink url="../../click-api/org/apache/click/ClickServlet.html">ClickServlet</ulink>,
+ to act as a request dispatcher. When a request arrives ClickServlet creates
+ a <ulink url="../../click-api/org/apache/click/Page.html">Page</ulink>
+ object to process the request and then uses the page's Velocity template to
+ render the results.
+ </para>
+
+ <para>Pages provide a simple thread safe programming environment, with a new
+ page instance created for each servlet request.
+ </para>
+
+ <para>Possibly the best way to see how Click works is to dive right in and
+ look at some examples.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link linkend="hello-world">Hello World</link> - the Hello World
+ classic
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="control-listener">Control Listener</link> - an
+ ActionLink control listener example
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="simple-table">Simple Table</link> - a simple Table
+ control example
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="advanced-table">Advanced Table</link> - a more advanced
+ Table example
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="simple-form">Simple Form</link> - a simple Form example
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="advanced-form">Advanced Form</link> - a more advanced
+ Form example
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <para>These examples are available online at
+ <ulink url="http://www.avoka.com/click-examples/">http://www.avoka.com/click-examples/</ulink>
+ under the menu "Intro Examples".
+ </para>
+
+ <sect1 id="hello-world">
+ <title>Hello World Example</title>
- <para>Click is an open source project, licensed under the <ulink
- url="../../LICENSE.txt"><citetitle>Apache
- license.</citetitle></ulink>.</para>
-
- <para>Click uses an event based programming model for processing Servlet
- requests and <ulink url="velocity/velocity.html">Velocity</ulink> for
- rendering the response. (Note other template engines such as <ulink
- url="http://java.sun.com/products/jsp/">JSP</ulink> and <ulink
- url="http://freemarker.sourceforge.net/">Freemarker</ulink> are also
- supported)</para>
-
- <para>This framework uses a single servlet, called <ulink
- url="../../click-api/org/apache/click/ClickServlet.html">ClickServlet</ulink>, to
- act as a request dispatcher. When a request arrives ClickServlet creates
- a <ulink url="../../click-api/org/apache/click/Page.html">Page</ulink>
- object to process the request and then uses the page's Velocity template
- to render the results.</para>
-
- <para>Pages provide a simple thread safe programming environment, with a
- new page instance created for each servlet request.</para>
-
- <para>Possibly the best way to see how Click works is to dive right in
- and look at some examples.</para>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="hello-world">Hello World</link> - the Hello World classic</para>
- </listitem>
- <listitem>
- <para><link linkend="control-listener">Control Listener</link> - a ActionLink control listener example</para>
- </listitem>
- <listitem>
- <para><link linkend="simple-table">Simple Table</link> - a simple Table control example</para>
- </listitem>
- <listitem>
- <para><link linkend="advanced-table">Advanced Table</link> - a more advanced Table example</para>
- </listitem>
- <listitem>
- <para><link linkend="simple-form">Simple Form</link> - a simple Form example</para>
- </listitem>
- <listitem>
- <para><link linkend="advanced-form">Advanced Form</link> - a more advanced Form example</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <para>
- These examples are available online at <ulink url="http://www.avoka.com/click-examples/">http://www.avoka.com/click-examples/</ulink>
- under the menu "Intro Examples".</para>
-
- <section id="hello-world">
- <title>Hello World Example</title>
+ <para>A Hello World example in Click would look something like this.
+ </para>
- <para>A Hello World example in Click would look something like
- this.</para>
+ <para>First we create a <classname>HelloWorld</classname> page class:
+ </para>
- <para>First we create a <classname>HelloWorld</classname> page
- class:</para>
-
- <programlisting>package examples.page;
+ <programlisting>package <symbol>examples.page</symbol>;
import java.util.Date;
-import net.sf.click.Page;
+import org.apache.click.Page;
public HelloWorld extends Page {
- public Date time = new Date(); <co id="co-hello-world-date" linkends="ca-hello-world-date"/>
+ private Date time = new Date(); <co id="co-hello-world-date" linkends="ca-hello-world-date"/>
+
+ public HelloWorld() {
+ addModel("time", time); <co id="co-hello-world-addmodel" linkends="ca-hello-world-addmodel"/>
+ }
-} </programlisting>
+}</programlisting>
- <calloutlist>
- <callout arearefs="co-hello-world-date" id="ca-hello-world-date">
- <para>Declaring the Date as public, informs Click to automatically bind
- the date to the Page model.</para>
- </callout>
- </calloutlist>
-
- <para>Next we have a page template
- <filename>hello-world.htm:</filename></para>
- <programlisting><html>
+ <calloutlist>
+ <callout arearefs="co-hello-world-date" id="ca-hello-world-date">
+ <para>Assign a new Date instance to the <literal>time</literal> variable.
+ </para>
+ </callout>
+ <callout arearefs="co-hello-world-addmodel" id="ca-hello-world-addmodel">
+ <para>Add the <literal>time</literal> variable to the Page model under
+ the name <varname>"time"</varname>. Click ensures all objects added
+ to the Page model is automatically available in the Page template.
+ </para>
+ </callout>
+ </calloutlist>
+
+ <para>Next we have a page template <varname>hello-world.htm</varname>,
+ where we can access the Page's <literal>time</literal> variable using the
+ reference <varname>$time</varname>:
+ </para>
+
+ <programlisting><html>
<body>
-
+
<h2>Hello World</h2>
-
+
Hello world from Click at <varname>$time</varname>
-
+
</body>
-</html> </programlisting>
+</html></programlisting>
- <para>Click is smart enough to figure out that the <classname>HelloWorld</classname>
- page class maps to the template <filename>hello-world.htm</filename>. We
- only have to inform Click of the <package>package</package> of the
- HelloWorld class, in this case <package>examples.page</package>.</para>
-
- <para>We do that through the <link linkend="application-configuration">click.xml</link>
- configuration file which tells Click to map <filename>hello-world.htm</filename>
- requests to our <classname>examples.page.HelloWorld</classname> page class.</para>
-
- <programlisting><click-app>
- <pages package="examples.page"/>
-</click-app> </programlisting>
-
- <para>At runtime the ClickSerlvet maps a GET
- <filename>hello-world.htm</filename> request to our page class
- <classname>example.page.HelloWorld</classname> and creates a new
- instance. The HelloWorld page creates a new public
- <emphasis>Date</emphasis> object, which is automatically added to the
- pages model using the fields name <varname>time</varname>.</para>
-
- <para>The page model is then merged with the template which substitutes
- the <varname>$time</varname> parameter with the
- <emphasis>Date</emphasis> object. Velocity then renders the merged
- template which looks something like</para>
-
- <literallayout> <emphasis role="bold">Hello World</emphasis>
-
- Hello world from Click at Tue May 08 19:37:05 EST 2007</literallayout>
- </section>
-
- <section id="control-listener-example">
- <title>Control Listener Example</title>
-
- <para>Click includes a library of <link
- linkend="chapter-controls">Controls</link> which provide user interface
- functionality.</para>
-
- <para>One of the commonly used controls is the <ulink
- url="../../click-api/org/apache/click/control/ActionLink.html">ActionLink</ulink>,
- which you can use to have a HTML link call a method on a Page object.
- For example:</para>
+ <para>Click is smart enough to figure out that the <classname>HelloWorld</classname>
+ page class maps to the template <varname>hello-world.htm</varname>. We only
+ have to inform Click of the <package>package</package> of the HelloWorld
+ class, in this case <symbol>examples.page</symbol>. We do that through the
+ <link linkend="application-configuration">click.xml</link> configuration
+ file which allows Click to map <varname>hello-world.htm</varname> requests
+ to the <classname>examples.page.HelloWorld</classname> page class.
+ </para>
+
+ <programlisting><click-app>
+ <pages package="<symbol>examples.page</symbol>"/>
+</click-app></programlisting>
+
+ <para>At runtime the following sequence of events occur. The ClickSerlvet
+ maps a GET <varname>hello-world.htm</varname> request to our page class
+ <classname>example.page.HelloWorld</classname> and creates a new instance.
+ The HelloWorld page creates a new private <emphasis>Date</emphasis> object,
+ which is added to the page's model under the name <varname>time</varname>.
+ </para>
+
+ <para>The page model is then merged with the template which substitutes
+ the <varname>$time</varname> reference with the <emphasis>Date</emphasis>
+ object. Velocity then renders the merged template which looks something like:
+ </para>
+
+ <screenshot>
+ <graphic fileref="images/introduction/hello-world-screenshot.png" scale="85">Hello</graphic>
+ </screenshot>
+
+ <!--
+ <figure id="hello-world-screenshot">
+ <title>Hello World Screenshot</title>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/introduction/hello-world-screenshot.png" format="PNG" scale="85"/>
+ </imageobject>
+ </inlinemediaobject>
+ </figure>-->
+
+ </sect1>
+
+ <sect1 id="control-listener">
+ <title>Control Listener Example</title>
- <programlisting>public class ControlListenerPage extends Page {
+ <para>Click includes a library of <link linkend="chapter-controls">Controls</link>
+ which provide user interface functionality.
+ </para>
+
+ <para>One of the commonly used controls is the
+ <ulink url="../../click-api/org/apache/click/control/ActionLink.html">ActionLink</ulink>,
+ which you can use to have an HTML link call a method on a Page object.
+ For example:
+ </para>
+
+ <programlisting>public class ControlListenerPage extends Page {
public ActionLink myLink = new ActionLink();
@@ -167,23 +234,25 @@
}
}</programlisting>
- <para>In the Page class we create an ActionLink called
- <varname>myLink</varname> and define the control's listener to be the
- page method <methodname>onMyLinkClick()</methodname>. When a user clicks
- on <varname>myLink</varname> control it will invoke the listener method
- <methodname>onMyLinkClick()</methodname>.</para>
-
- <para>In Click a control listener method can have any name but it must
- return a boolean value. The boolean return value specifies whether
- processing of page events should continue. This control listener pattern
- provides a short hand way for wiring up action listener methods without
- having to define anonymous inner classes.</para>
-
- <para>Back to our example, in the page template we define a HTML link
- and have the <varname>myLink</varname> control render the link's href
- attribute:</para>
+ <para>In the Page class we create an ActionLink called
+ <varname>myLink</varname> and define the control's listener to be the page
+ method <methodname>onMyLinkClick()</methodname>. When a user clicks on
+ <varname>myLink</varname> control it will invoke the listener method
+ <methodname>onMyLinkClick()</methodname>.
+ </para>
+
+ <para>In Click a control listener method can have any name but it must
+ return a boolean value. The boolean return value specifies whether
+ processing of page events should continue. This control listener pattern
+ provides a short hand way for wiring up action listener methods without
+ having to define anonymous inner classes.
+ </para>
+
+ <para>Back to our example, in the page template we define a HTML link and
+ have the <varname>myLink</varname> control render the link's href attribute:
+ </para>
- <programlisting><html>
+ <programlisting><html>
<head>
<link type="text/css" rel="stylesheet" href="style.css"></link>
</head>
@@ -191,38 +260,41 @@
Click myLink control <a href="<varname>$myLink.href</varname>">here</a>.
- <symbol>#if</symbol> (<varname>$msg</varname>)
+ <command>#if</command> (<varname>$msg</varname>)
<div id="msgDiv"> <varname>$msg</varname> </div>
- <symbol>#end</symbol>
+ <command>#end</command>
</body>
</html></programlisting>
- <para>At runtime this page would be rendered as:</para>
+ <para>At runtime this page would be rendered as:</para>
- <literallayout>Click myLink control <varname>here</varname>.</literallayout>
+ <literallayout>Click myLink control <varname>here</varname>.</literallayout>
- <para>When a user clicks on the link the
- <methodname>onMyLinkClick()</methodname> method is invoked. This method
- then creates <varname>msg</varname> model value, which is rendered in
- the page as:</para>
+ <para>When a user clicks on the link the <methodname>onMyLinkClick()</methodname>
+ method is invoked. This method then creates <varname>msg</varname> model
+ value, which is rendered in the page as:
+ </para>
- <literallayout>Click myLink control <varname>here</varname>.
+ <literallayout>Click myLink control <varname>here</varname>.
<computeroutput>ControlListenerPage#12767107 object method onMyLinkClick() invoked.</computeroutput></literallayout>
- </section>
- <section id="simple-table-example">
- <title>Simple Table Example</title>
+ </sect1>
+
+ <sect1 id="simple-table">
+ <title>Simple Table Example</title>
- <para>One of the most useful Click controls is the <ulink
- url="../../click-api/org/apache/click/control/Table.html">Table</ulink>
- control.</para>
+ <para>One of the most useful Click controls is the
+ <ulink url="../../click-api/org/apache/click/control/Table.html">Table</ulink>
+ control.
+ </para>
- <para>An example usage of the Table control in a customers Page is
- provided below:</para>
+ <para>An example usage of the Table control in a customers Page is provided
+ below:
+ </para>
- <programlisting>public class SimpleTablePage extends Page {
+ <programlisting>public class SimpleTablePage extends Page {
public Table table = new Table();
@@ -248,22 +320,25 @@
}
}</programlisting>
- <para>In this Page code example a Table control is declared, we set the
- table's HTML class, and then define a number of table <ulink
- url="../../click-api/org/apache/click/control/Column.html">Column</ulink> objects.
- In the column definitions we specify the name of the column in the
- constructor, which is used for the table column header and also to
- specify the row object property to render.</para>
-
- <para>The last thing we need to do is populate the table with data. To
- do this we override the Page onRender() method and set the table row
- list before it is rendered.</para>
-
- <para>In our Page template we simply reference the
- <varname>$table</varname> object which is rendered when its toString()
- method is called.</para>
+ <para>In this Page code example a Table control is declared, we set the
+ table's HTML class, and then define a number of table
+ <ulink url="../../click-api/org/apache/click/control/Column.html">Column</ulink>
+ objects. In the column definitions we specify the name of the column in the
+ constructor, which is used for the table column header and also to specify
+ the row object property to render.
+ </para>
+
+ <para>The last thing we need to do is populate the table with data. To do
+ this we override the Page onRender() method and set the table row list
+ before it is rendered.
+ </para>
+
+ <para>In our Page template we simply reference the <varname>$table</varname>
+ object which is rendered when its <methodname>toString()</methodname> method
+ is called.
+ </para>
- <programlisting><html>
+ <programlisting><html>
<head>
<varname>$cssImports</varname>
</head>
@@ -272,54 +347,61 @@
<varname>$table</varname>
<varname>$jsImports</varname>
+
</body>
</html></programlisting>
- <para>Note above we also specify the <varname>$cssImports</varname>
- reference so the table can include any CSS imports or styles in the
- header, and the <varname>$jsImports</varname> reference any JavaScript
- imports or scripts at the bottom.</para>
-
- <para>At runtime the Table would be rendered in the page as:</para>
-
- <para><mediaobject>
- <imageobject>
- <imagedata fileref="images/introduction/simple-table.png" />
- </imageobject>
- </mediaobject></para>
- </section>
-
- <section id="advanced-table-example">
- <title>Advanced Table Example</title>
-
- <para>The Table control also provides support for:</para>
-
- <itemizedlist>
- <listitem>
- <para>automatic rendering</para>
- </listitem>
-
- <listitem>
- <para>column formatting and custom rendering</para>
- </listitem>
-
- <listitem>
- <para>automatic pagination</para>
- </listitem>
-
- <listitem>
- <para>link control support</para>
- </listitem>
- </itemizedlist>
+ <para>Note above we also specify the <varname>$cssImports</varname>
+ reference so the table can include any CSS imports or styles in the header,
+ and the <varname>$jsImports</varname> reference any JavaScript imports or
+ scripts at the bottom. At runtime Click automatically makes the variables
+ <varname>$cssImports</varname> and <varname>$jsImports</varname> available
+ to the template.
+ </para>
+
+ <para>At runtime the Table would be rendered in the page as:</para>
+
+ <figure id="simple-table-image">
+ <title>Simple Table</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/introduction/simple-table.png" scale="85"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </sect1>
+
+ <sect1 id="advanced-table">
+ <title>Advanced Table Example</title>
+
+ <para>The Table control also provides support for:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>automatic rendering</para>
+ </listitem>
+
+ <listitem>
+ <para>column formatting and custom rendering</para>
+ </listitem>
+
+ <listitem>
+ <para>automatic pagination</para>
+ </listitem>
- <para>A more advanced Table example is provided below:</para>
+ <listitem>
+ <para>link control support</para>
+ </listitem>
+ </itemizedlist>
- <programlisting>public class CustomerPage extends Page {
+ <para>A more advanced Table example is provided below:</para>
+
+ <programlisting>public class CustomerPage extends Page {
public Table table = new Table();
public PageLink editLink = new PageLink("Edit", EditCustomer.class);
- public ActionLink deleteLink = new ActionLink("Delete", this,
- "onDeleteClick");
+ public ActionLink deleteLink = new ActionLink("Delete", this, "onDeleteClick");
// ------------------------------------- Constructor
@@ -377,69 +459,73 @@
}
}</programlisting>
- <para>In this Page code example a Table control is declared and a number
- of <ulink
- url="../../click-api/org/apache/click/control/Column.html">Column</ulink> objects
- are added. A deleteLink <ulink
- url="../../click-api/org/apache/click/control/ActionLink.html">ActionLink</ulink>
- control is used as a decorator for the "Action" column. This control
- will invoke the Page <methodname>onDeleteClick()</methodname> method
- when it is clicked. Finally we have the Page
- <methodname>onRender()</methodname> method which is used to populate the
- Table control with rows before it is rendered.</para>
-
- <para>In our Page template we simply reference the
- <varname>$table</varname> object which is rendered when its
- <methodname>toString()</methodname> method is called.</para>
+ <para>In this Page code example a Table control is declared and a number of
+ <ulink url="../../click-api/org/apache/click/control/Column.html">Column</ulink>
+ objects are added. A deleteLink
+ <ulink url="../../click-api/org/apache/click/control/ActionLink.html">ActionLink</ulink>
+ control is used as a decorator for the "Action" column. This control will
+ invoke the Page <methodname>onDeleteClick()</methodname> method when it is
+ clicked. Finally we have the Page <methodname>onRender()</methodname> method
+ which is used to populate the Table control with rows before it is rendered.
+ </para>
+
+ <para>In our Page template we simply reference the <varname>$table</varname>
+ object which is rendered when its <methodname>toString()</methodname> method
+ is called.
+ </para>
- <programlisting><html>
+ <programlisting><html>
<head>
-<varname> $cssImports</varname>
+ <varname>$cssImports</varname>
</head>
<body>
-<varname> $table</varname>
+ <varname>$table</varname>
+
+ <varname>$jsImports</varname>
-<varname> $jsImports</varname>
</body>
</html></programlisting>
- <para>At runtime the Table would be rendered in the page as:</para>
+ <para>At runtime the Table would be rendered in the page as:</para>
- <para><mediaobject>
- <imageobject>
- <imagedata fileref="images/introduction/advanced-table.png" />
- </imageobject>
- </mediaobject></para>
-
- <para>In this example if a user click on the Delete link the
- <methodname>onDeleteClick()</methodname> method will be called on the
- Page deleting the customer record.</para>
- </section>
-
- <section id="simple-form-example">
-
- <title>Simple Form Example</title>
-
- <para>The <ulink
- url="../../click-api/org/apache/click/control/Form.html">Form</ulink> and <ulink
- url="../../click-api/org/apache/click/control/Field.html">Field</ulink> controls
- are also some of the most commonly used controls in the Click
- Framework.</para>
-
- <para>The SimpleForm page below provides a demonstration of using these
- controls.</para>
-
- <para>In our example code we have the page's constructor adding a <ulink
- url="../../click-api/org/apache/click/control/TextField.html">TextField</ulink>
- field and a <ulink
- url="../../click-api/org/apache/click/control/Submit.html">Submit</ulink> button
- to the form. A page method is also set as a control listener on the
- form. Also note in this example the page's public
- <varname>form</varname> field is automatically added to its list of
- controls.</para>
+ <figure id="advanced-table-image">
+ <title>Advanced Table</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/introduction/advanced-table.png" scale="85"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
- <programlisting>public class SimpleForm extends Page {
+ <para>In this example if a user click on the Delete link, the
+ <methodname>onDeleteClick()</methodname> method will be called on the Page
+ deleting the customer record.
+ </para>
+
+ </sect1>
+
+ <sect1 id="simple-form">
+ <title>Simple Form Example</title>
+
+ <para>The <ulink url="../../click-api/org/apache/click/control/Form.html">Form</ulink>
+ and <ulink url="../../click-api/org/apache/click/control/Field.html">Field</ulink>
+ controls are also some of the most commonly used controls in the Click Framework.
+ </para>
+
+ <para>The SimpleForm page below provides a demonstration of using these
+ controls.
+ </para>
+
+ <para>In our example code we have the page's constructor adding a
+ <ulink url="../../click-api/org/apache/click/control/TextField.html">TextField</ulink>
+ field and a <ulink url="../../click-api/org/apache/click/control/Submit.html">Submit</ulink>
+ button to the form. A page method is also set as a control listener on the
+ form. Also note in this example the page's public <varname>form</varname>
+ field is automatically added to its list of controls.
+ </para>
+
+ <programlisting>public class SimpleForm extends Page {
public Form form = new Form();
public String msg;
@@ -466,89 +552,104 @@
}
}</programlisting>
- <para>Next we have the SimpleForm template
- <filename>simple-form.htm</filename>. The Click application
- automatically associates the <filename>simple-form.htm</filename>
- template with the <classname>SimpleForm</classname> class.</para>
+ <para>Next we have the SimpleForm template <varname>simple-form.htm</varname>.
+ The Click application automatically associates the
+ <varname>simple-form.htm</varname> template with the
+ <classname>SimpleForm</classname> class.
+ </para>
- <programlisting><html>
+ <programlisting><html>
<head>
-<varname> $cssImports</varname>
+ <varname>$cssImports</varname>
</head>
<body>
-<varname> $form</varname>
+ <varname>$form</varname>
-<symbol> #if</symbol> (<varname>$msg</varname>)
+ <command>#if</command> (<varname>$msg</varname>)
<div id="msgDiv"> <varname>$msg</varname> </div>
-<symbol> #end</symbol>
+ <command>#end</command>
<varname>$jsImports</varname>
+
</body>
</html></programlisting>
- <para>When the SimpleForm page is first requested the
- <varname>$form</varname> object will automatically render itself
- as:</para>
+ <para>When the SimpleForm page is first requested the <varname>$form</varname>
+ object will automatically render itself as:
+ </para>
+ <figure id="simple-form-image">
+ <title>Simple Form</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/introduction/simple-form.png" />
+ <imagedata fileref="images/introduction/simple-form.png" scale="85"/>
</imageobject>
</mediaobject>
+ </figure>
- <para>Say the user does not enter their name and presses the OK button
- to submit the form. The <classname>ClickServlet</classname> creates a
- new SimpleForm page and processes the form control.</para>
-
- <para>The form control processes its fields and determines that it is
- invalid. The form then invokes the listener method
- <methodname>onSubmit()</methodname>. As the form is not valid this
- method simply returns true and the form renders the field validation
- errors.</para>
+ <para>Say the user does not enter their name and presses the OK button to
+ submit the form. The <classname>ClickServlet</classname> creates a new
+ SimpleForm page and processes the form control.
+ </para>
+
+ <para>The form control processes its fields and determines that it is
+ invalid. The form then invokes the listener method
+ <methodname>onSubmit()</methodname>. As the form is not valid this method
+ simply returns true and the form renders the field validation errors.
+ </para>
+ <figure id="simple-form-error-image">
+ <title>Form after an invalid request</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/introduction/simple-form-error.png" />
+ <imagedata fileref="images/introduction/simple-form-error.png" scale="85"/>
</imageobject>
</mediaobject>
+ </figure>
- <para>Note the form will automatically maintain the entered state during
- the post and validate cycle.</para>
-
- <para>Now if the user enters their name and clicks the OK button, the
- form will be valid and the <methodname>onSubmit()</methodname> add a
- <varname>msg</varname> to the Pages model. This will be rendered
- as:</para>
+ <para>Note the form will automatically maintain the entered state during the
+ post and validate cycle.
+ </para>
+
+ <para>Now if the user enters their name and clicks the OK button, the form
+ will be valid and the <methodname>onSubmit()</methodname> add a
+ <varname>msg</varname> to the Pages model. This will be rendered as:
+ </para>
+ <figure id="simple-form-success-image">
+ <title>Form after a valid request</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/introduction/simple-form-success.png" />
+ <imagedata fileref="images/introduction/simple-form-success.png" scale="85"/>
</imageobject>
</mediaobject>
- </section>
+ </figure>
+
+ </sect1>
- <section id="advanced-form-example">
- <title>Advanced Form Example</title>
+ <sect1 id="advanced-form">
+ <title>Advanced Form Example</title>
- <para>The <classname>AdvancedForm</classname> page below provides a more
- advanced demonstration of using Form, Field and FielsSet
- controls.</para>
-
- <para>First we have an <classname>AdvancedForm</classname> class which
- setups up a <ulink
- url="../../click-api/org/apache/click/control/Form.html">Form</ulink> in its
- constructor. The form's investment <ulink
- url="../../click-api/org/apache/click/control/Select.html">Select</ulink> list is
- populated in the page's <methodname>onInit()</methodname> method. At
- this point any page dependencies such as the CustomerService should be
- available.</para>
-
- <para>Note in this example the page's public <varname>form</varname>
- field is automatically added to its list of controls. The
- <varname>msg</varname> field is added to the page's model.</para>
+ <para>The <classname>AdvancedForm</classname> page below provides a more
+ advanced demonstration of using Form, Field and FielsSet controls.
+ </para>
+
+ <para>First we have an <classname>AdvancedForm</classname> class which
+ setups up a <ulink url="../../click-api/org/apache/click/control/Form.html">Form</ulink>
+ in its constructor. The form's investment
+ <ulink url="../../click-api/org/apache/click/control/Select.html">Select</ulink>
+ list is populated in the page's <methodname>onInit()</methodname> method. At
+ this point any page dependencies such as the CustomerService should be
+ available.
+ </para>
+
+ <para>Note in this example the page's public <varname>form</varname> field
+ is automatically added to its list of controls. The <varname>msg</varname>
+ field is added to the page's model.
+ </para>
- <programlisting>public class AdvancedForm extends Page {
+ <programlisting>public class AdvancedForm extends Page {
public Form form = new Form();
public String msg;
@@ -618,69 +719,78 @@
}
}</programlisting>
- <para>Next we have the AdvancedForm template
- <filename>advanced-form.htm</filename>. The Click application
- automatically associates the <filename>advanced-form.htm</filename>
- template with the <classname>AdvancedForm</classname> class.</para>
+ <para>Next we have the AdvancedForm template
+ <filename>advanced-form.htm</filename>. The Click application automatically
+ associates the <filename>advanced-form.htm</filename> template with the
+ <classname>AdvancedForm</classname> class.
+ </para>
- <programlisting><html>
+ <programlisting><html>
<head>
-<varname> $cssImports</varname>
+ <varname>$cssImports</varname>
</head>
<body>
-<symbol> #if</symbol> (<varname>$msg</varname>)
+ <command>#if</command> (<varname>$msg</varname>)
<div id="msgDiv"> <varname>$msg</varname> </div>
-<symbol> #end</symbol>
+ <command>#end</command>
-<varname> $form</varname>
+ <varname>$form</varname>
<varname>$jsImports</varname>
+
</body>
</html></programlisting>
- <para>When the AdvancedForm page is first requested the
- <varname>$form</varname> object will automatically render itself
- as:</para>
+ <para>When the AdvancedForm page is first requested the
+ <varname>$form</varname> object will automatically render itself as:
+ </para>
+ <figure id="advanced-form-image">
+ <title>Advanced Form</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/introduction/advanced-form.png" />
+ <imagedata fileref="images/introduction/advanced-form.png" scale="85"/>
</imageobject>
</mediaobject>
+ </figure>
+
+ <para>In this example when the OK button is clicked the
+ <methodname>onOkClicked()</methodname> method is invoked. If the form is
+ valid a new customer object is created and the forms field values are copied
+ to the new object using the Form
+ <ulink url="click-api/org/apache/click/control/Form.html#copyTo(java.lang.Object)">copyTo()</ulink>
+ method. The customer object is then saved, the form's field values are
+ cleared and an info message is presented to the user.
+ </para>
+
+ <para>If the user clicks on the Cancel button the request is redirected to
+ the applications HomePage.
+ </para>
+
+ <sect2 id="form-layout">
+ <title>Form Layout</title>
+
+ <para>In the example above the Form control automatically renders the form
+ and the fields HTML markup. This is a great feature for quickly building
+ screens, and the form control provides a number of layout options. See the
+ Click Examples for an interactive
+ <ulink url="http://www.avoka.com/click-examples/form/form-properties.htm">Form Properties demo</ulink>.
+ </para>
+
+ <para>For fine grained page design you can specifically layout form and
+ fields in your page template. See the
+ <link linkend="template-layout">Template Layout</link> section and
+ <ulink url="../../click-api/org/apache/click/control/Form.html#form-layout">Form</ulink>
+ Javadoc for more details.
+ </para>
+
+ <para>An alternative to page template design is using a programmatic
+ approach. See <link linkend="programmatic-layout">Programmatic Layout</link>
+ for more details.
+ </para>
+
+ </sect2>
- <para>In this example when the OK button is clicked the
- <methodname>onOkClicked()</methodname> method is invoked. If the form is
- valid a new customer object is created and the forms field values are
- copied to the new object using the Form
- <methodname>copyTo()</methodname> method. The customer object is then
- saved, the form's field values are cleared and an info message is
- presented to the user.</para>
-
- <para>If the user clicks on the Cancel button the request is redirected
- to the applications HomePage.</para>
-
- <section id="form-layout">
- <title>Form Layout</title>
-
- <para>In the example above the Form control automatically renders the
- form and the fields HTML markup. This is a great feature for quickly
- building screens, and the form control provides a number of layout
- options. See the Click Examples for an interactive <ulink
- url="http://www.avoka.com/click-examples/form/form-properties.htm">Form
- Properties demo</ulink>.</para>
-
- <para>For fine grained page design you can specifically layout form
- and fields in your page template. See the <link
- linkend="template-layout">Template Layout</link> section and
- <ulink
- url="../../click-api/org/apache/click/control/Form.html#form-layout">Form</ulink>
- Javadoc for more details.</para>
-
- <para>An alternative approach to page template design is using a
- programmatic approach. See the <link
- linkend="programmatic-layout">Programmatic Layout</link>
- section for more details.</para>
- </section>
- </section>
+ </sect1>
</chapter>
\ No newline at end of file