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 2010/10/02 09:14:41 UTC
svn commit: r1003748 - in /click/trunk/click/documentation:
docs/roadmap-changes.html xdocs/src/docbook/click/chapter-best-practices.xml
xdocs/src/docbook/click/chapter-configuration.xml
xdocs/src/docbook/click/chapter-pages.xml
Author: sabob
Date: Sat Oct 2 07:14:40 2010
New Revision: 1003748
URL: http://svn.apache.org/viewvc?rev=1003748&view=rev
Log:
added support for absolute classnames in click.xml. CLK-704
Modified:
click/trunk/click/documentation/docs/roadmap-changes.html
click/trunk/click/documentation/xdocs/src/docbook/click/chapter-best-practices.xml
click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml
click/trunk/click/documentation/xdocs/src/docbook/click/chapter-pages.xml
Modified: click/trunk/click/documentation/docs/roadmap-changes.html
URL: http://svn.apache.org/viewvc/click/trunk/click/documentation/docs/roadmap-changes.html?rev=1003748&r1=1003747&r2=1003748&view=diff
==============================================================================
--- click/trunk/click/documentation/docs/roadmap-changes.html (original)
+++ click/trunk/click/documentation/docs/roadmap-changes.html Sat Oct 2 07:14:40 2010
@@ -198,6 +198,12 @@ service.
[<a target="_blank" href="https://issues.apache.org/jira/browse/CLK-705">CLK-705</a>].
</li>
<li class="change">
+ Added support for absolute page classnames when configuring pages
+ in <tt>click.xml</tt>. Absolute classnames aids with IDE hot-linking
+ and is less confusing to use.
+ [<a target="_blank" href="https://issues.apache.org/jira/browse/CLK-704">CLK-704</a>].
+ </li>
+ <li class="change">
Added a renderId property to ResourceElement to exclude the ID attribute from rendering
[<a target="_blank" href="https://issues.apache.org/jira/browse/CLK-695">CLK-695</a>].
</li>
Modified: click/trunk/click/documentation/xdocs/src/docbook/click/chapter-best-practices.xml
URL: http://svn.apache.org/viewvc/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-best-practices.xml?rev=1003748&r1=1003747&r2=1003748&view=diff
==============================================================================
--- click/trunk/click/documentation/xdocs/src/docbook/click/chapter-best-practices.xml (original)
+++ click/trunk/click/documentation/xdocs/src/docbook/click/chapter-best-practices.xml Sat Oct 2 07:14:40 2010
@@ -754,8 +754,8 @@
For example:
</para>
- <programlisting language="xml"><pages package="com.mycorp.page" automapping="annotation"/>
- <page path="click/error.htm" classname="ErrorPage"/>
+ <programlisting language="xml"><pages package="com.mycorp.page" autobinding="annotation"/>
+ <page path="click/error.htm" classname="com.mycorp.page.ErrorPage"/>
</pages></programlisting>
<para>Generally applications handle transactional errors using service layer code
Modified: click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml
URL: http://svn.apache.org/viewvc/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml?rev=1003748&r1=1003747&r2=1003748&view=diff
==============================================================================
--- click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml (original)
+++ click/trunk/click/documentation/xdocs/src/docbook/click/chapter-configuration.xml Sat Oct 2 07:14:40 2010
@@ -220,9 +220,12 @@
<programlisting language="xml"><click-app charset="UTF-8" locale="de">
- <!-- Specify the Java package where Page classes can be found -->
+ <!-- To aid Click's automapping, specify the Java package where Page classes can be found -->
<pages package="com.mycorp.banking.page">
- <page path="index.htm" classname="Home"/>
+ <!-- We have to manually define the mapping between the Home page class and index.htm template
+ because this page doesn't follow the automatic mapping convention of naming the page class and
+ template the same-->
+ <page path="index.htm" classname="com.mycorp.banking.page.Home"/>
</pages>
<!-- Specify a second Java package where Page classes can be found -->
@@ -295,12 +298,12 @@
<!ATTLIST pages <varname>automapping</varname> (true|false) "true">
<!ATTLIST pages <varname>autobinding</varname> (default|annotation|none) "default"></literallayout>
- <para>The pages element can specify a default <varname>package</varname> name
- which is prepended to the classname of any pages defined.
+ <para>The pages element can specify a base <varname>package</varname>
+ that Click should use for mapping page templates to page classes.
</para>
<para>The pages element also defines the <varname>automapping</varname> and
- <varname>automapping</varname> attributes which is discussed in the
+ <varname>autobinding</varname> attributes which is discussed in the
<link linkend="application-automapping">Page Automapping</link> and
<link linkend="application-autobinding">Page Autobinding</link> sections
respectively.
@@ -374,11 +377,11 @@
</para>
<para>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.
+ and JSP file in the web application (excluding those under WEB-INF) 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 page mappings will be logged if Click is
+ running in debug or trace mode.
</para>
<para>For example, given the following page path to class mapping:
@@ -392,34 +395,63 @@ security/logout.htm => <tok
security/change-password.htm => <token>com.mycorp.page.security.ChangePassword</token></literallayout>
<para>The above mapping could be configured manually by setting the
- <symbol>automapping</symbol> attribute to "false" and using the package
- prefix, for example:
+ <symbol>automapping</symbol> attribute to <literal>false</literal>,
+ for example:
</para>
<programlisting language="xml"><click-app>
- <pages package="<token>com.mycorp.page</token>" <symbol>automapping</symbol>="false">
- <page path="index.htm" classname="<token>Home</token>"/>
- <page path="search.htm" classname="<token>Search</token>"/>
- <page path="contacts/contacts.htm" classname="<token>contacts.Contacts</token>"/>
- <page path="security/login.htm" classname="<token>security.Login</token>"/>
- <page path="security/logout.htm" classname="<token>security.Logout</token>"/>
- <page path="security/change-password.htm" classname="<token>security.ChangePassword</token>"/>
+ <pages automapping="false">
+ <page path="index.htm" classname="<token>com.mycorp.page.Home</token>"/>
+ <page path="search.htm" classname="<token>com.mycorp.page.Search</token>"/>
+ <page path="contacts/contacts.htm" classname="<token>com.mycorp.page.contacts.Contacts</token>"/>
+ <page path="security/login.htm" classname="<token>com.mycorp.page.security.Login</token>"/>
+ <page path="security/logout.htm" classname="<token>com.mycorp.page.security.Logout</token>"/>
+ <page path="security/change-password.htm" classname="<token>com.mycorp.page.security.ChangePassword</token>"/>
</pages>
</click-app></programlisting>
- <para>By using <symbol>automapping</symbol> the page paths will automatically
- map to page classes: (except for Home page which doesn't automatically map
- to index.html)
+ <para>For an application with many pages, it is cumbersome to manually map
+ each page template to its associated class. This is where
+ <symbol>automapping</symbol> comes in.
+ </para>
+
+ <para>By setting <symbol>automapping</symbol> to <literal>true</literal>,
+ Click will automatically map page templates to page classes. To map a
+ template to a page class, Click converts the template path to the Page
+ classname. In the example above, Click will convert the template
+ <token>search.htm</token> to the class <token>Search</token> by
+ capitilizing the template name and removing the <literal>.htm</literal>
+ extension. Of course this is not enough to map the template to the class.
+ what is missing is the class package, <token>com.mycorp.page</token>.
+ To help Click map the page, you can set the base <literal>package</literal>
+ attribute as shown in the next example.
+ </para>
+
+ <para>Below is the full configuration to automatically map the templates
+ to pages (except for index.htm which doesn't automatically map to Home
+ page and has to be mapped manually):
</para>
<programlisting language="xml"><click-app>
<pages package="<token>com.mycorp.page</token>" <symbol>automapping</symbol>="true">
- <page path="index.htm" classname="Home"/>
+ <page path="index.htm" classname="com.mycorp.page.Home"/>
</pages>
</click-app></programlisting>
- <para>Note <symbol>automapping</symbol> is true by default, so it could be
- omitted from the configuration file.
+ <para>Note: <symbol>automapping</symbol> is <literal>true</literal> by
+ default, so it could be omitted.
+ </para>
+
+ <para>If a page template is placed in a <literal>sub folder</literal>
+ of the root web folder, it's associated page class must be placed in an
+ equivalently named <literal>sub package</literal> of the base package in
+ order for the page to be mapped automatically. In the mapping above the
+ page template <token>security/change-password.htm</token> is located in
+ the <token>security</token> folder under the web root. In order for Click
+ to correctly map the page template to it's class, the class must be
+ located in the <token>security</token> package of the
+ base package <token>com.mycorp.page</token>. The absolute page classname
+ is thus: <token>com.mycorp.page.security.ChangePassword</token>.
</para>
<para>The page template name to classname convention is:
@@ -430,9 +462,9 @@ change_password.htm => <token>Chang
changePassword.htm => <token>ChangePassword</token>
ChangePassword.htm => <token>ChangePassword</token></literallayout>
- <para>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:
+ <para>During automapping, if a page class cannot be found, Click will
+ add the 'Page' suffix to the classname (if not already present) and
+ attempt to map the page template to this modified classname. For example:
</para>
<literallayout>customer.htm => <token>CustomerPage</token>
@@ -721,25 +753,28 @@ change-password.htm => <token>Chang
</click-app></programlisting>
<para>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:
+ for all application pages by setting header values. For example, to
+ switch off caching in the <literal>Login</literal> page, set the
+ following page cache control headers:
</para>
<programlisting language="xml"><pages package="com.mycorp.page">
- <page path="login.htm" classname="Login">
+ <page path="login.htm" classname="com.mycorp.page.Login">
<header name="Pragma" value="no-cache"/>
<header name="Expires" value="1" type="Date"/>
</page>
</pages></programlisting>
+ <para>Note: the value for a Date type should be a long number value.
+ </para>
+
<para>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.
</para>
<programlisting language="xml"><pages package="com.mycorp.page">
- <page path="home.htm" classname="Home">
+ <page path="home.htm" classname="com.mycorp.page.Home">
<header name="Cache-Control" value="max-age=3600, public, must-revalidate"/>
</page>
</pages></programlisting>
Modified: click/trunk/click/documentation/xdocs/src/docbook/click/chapter-pages.xml
URL: http://svn.apache.org/viewvc/click/trunk/click/documentation/xdocs/src/docbook/click/chapter-pages.xml?rev=1003748&r1=1003747&r2=1003748&view=diff
==============================================================================
--- click/trunk/click/documentation/xdocs/src/docbook/click/chapter-pages.xml (original)
+++ click/trunk/click/documentation/xdocs/src/docbook/click/chapter-pages.xml Sat Oct 2 07:14:40 2010
@@ -867,7 +867,9 @@ public void onPost() {
method, returning the path of the border template to render. For example:
</para>
- <programlisting language="java">public class BorderedPage extends Page {
+ <programlisting language="java">package com.mycorp.page;
+
+public class BorderedPage extends Page {
/**
* @see Page#getTemplate()
@@ -906,9 +908,11 @@ public void onPost() {
<para>An example bordered Home page is provided below:
</para>
- <literallayout><page path="<varname>home.htm</varname>" classname="<token>Home</token>"/></literallayout>
+ <literallayout><page path="<varname>home.htm</varname>" classname="<token>com.mycorp.page.Home</token>"/></literallayout>
+
+ <programlisting language="java">package com.mycorp.page;
- <programlisting language="java">public class Home extends BorderedPage {
+public class Home extends BorderedPage {
public String title = "Home";