Author: SeanRogers
Date: 2009-12-18 02:05:05 -0500 (Fri, 18 Dec 2009)
New Revision: 16165
Added:
root/docs/trunk/Component_Reference/en-US/extras/exam-Component_Reference-Resources-a4jloadBundle-0.xml_sample
Modified:
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_features.xml
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml
Log:
Worked on Resources chapter
Modified: root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml
===================================================================
---
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml 2009-12-17
18:52:56 UTC (rev 16164)
+++
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Actions.xml 2009-12-18
07:05:05 UTC (rev 16165)
@@ -10,7 +10,19 @@
This chapter details the basic components that respond to a user action and submit an
Ajax request.
</para>
<section id="sect-Component_Reference-Actions-a4jactionParam">
- <title>a4j:actionParam</title>
+ <title><a4j:actionParam></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.ActionParameter</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.HTMLActionParameter</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
The <sgmltag><a4j:actionParam></sgmltag> behavior combines
the functionality of the JavaServer Faces (<acronym>JSF</acronym>) components
<sgmltag><f:param></sgmltag> and
<sgmltag><f:actionListener></sgmltag>.
</para>
@@ -78,11 +90,28 @@
<section id="sect-Component_Reference-Actions-a4jajaxListener">
<title>a4j:ajaxListener</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ listener-class: <classname>org.ajax4jsf.event.AjaxListener</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ event-class: <classname>org.ajax4jsf.event.AjaxEvent</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ tag-class:
<classname>org.ajax4jsf.taglib.html.jsp.AjaxListenerTag</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
The <sgmltag><a4j:ajaxListener></sgmltag> component adds an
action listener to a parent component. It works similar to the JavaServer Faces
<sgmltag><f:actionListener></sgmltag> or
<sgmltag><f:valueChangeListener></sgmltag> components, except
that the invocation of <sgmltag><a4j:ajaxListener></sgmltag> is
not canceled if validation of the <emphasis>Update Model</emphasis> phase
fails. The <sgmltag><a4j:ajaxListener></sgmltag> component is
guaranteed to be invoked with each Ajax response.
</para>
<para>
- Baasic usage requires only the <varname>type</varname> attribute, which
defines the fully-qualified Java class name for the listener. This Java class should
implement the <classname>org.ajax4jsf.event.AjaxListener</classname>
interface, which is a base listener for all listeners and is capable of receiving Ajax
events. The object from which the event originated could be accessed using the
<methodname>java.util.EventObject.getSource()</methodname> method.
+ Basic usage requires only the <varname>type</varname> attribute, which
defines the fully-qualified Java class name for the listener. This Java class should
implement the <classname>org.ajax4jsf.event.AjaxListener</classname>
interface, which is a base listener for all listeners and is capable of receiving Ajax
events. The object from which the event originated could be accessed using the
<methodname>java.util.EventObject.getSource()</methodname> method.
</para>
<para>
The <sgmltag><a4j:ajaxListener></sgmltag> component is not
invoked for non-Ajax requests, or when the RichFaces works in the <emphasis>Ajax
request generates non-Ajax response</emphasis> mode, so the
<sgmltag><a4j:ajaxListener></sgmltag> invocation is a good
indicator that an Ajax response is going to be processed.
@@ -184,12 +213,37 @@
</listitem>
</itemizedlist>
<para>
- Incomplete
+ The <sgmltag><a4j:htmlCommandLink></sgmltag> component
functions similarly to the standard
<sgmltag><h:commandLink></sgmltag> component, but addresses some
of the potential issues that can occur.
</para>
+ <para>
+ When using the standard component, hidden fields were not rendered to child elements
if they were deemed unnecessary, so command links relating to content on the initial page
could become broken if they were later updated through Ajax. The
<sgmltag><a4j:htmlCommandLink></sgmltag> component addresses
this by always rendering all hidden fields.
+ </para>
</section>
<section id="sect-Component_Reference-Actions-a4jjsFunction">
<title><a4j:jsFunction></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.Function</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family:
<classname>org.ajax4jsf.components.ajaxFunction</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.HtmlajaxFunction</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ renderer-type:
<classname>org.ajax4jsf.components.ajaxFunctionRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
The <sgmltag><a4j:jsFunction></sgmltag> component allows
Ajax requests to be performed directly from JavaScript code, and server-side data to be
invoked and returned in JavaScript Object Notation (<acronym>JSON</acronym>)
format to use in client-side JavaScript calls.
</para>
@@ -213,19 +267,75 @@
<section id="sect-Component_Reference-Actions-a4jpoll">
<title><a4j:poll></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.Poll</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family:
<classname>org.ajax4jsf.components.AjaxPoll</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.AjaxPoll</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ renderer-type:
<classname>org.ajax4jsf.components.AjaxPollRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
The <sgmltag><a4j:poll></sgmltag> component allows
periodical sending of Ajax requests to the server. It is used for repeatedly updating a
page at specific time intervals.
</para>
<para>
- The <varname>interval</varname> attribute specifies the time in
milliseconds to between requests. The default for this value is 1000 ms (1 second).
+ The <varname>interval</varname> attribute specifies the time in
milliseconds between requests. The default for this value is 1000 ms (1 second).
</para>
+ <para>
+ The <varname>timeout</varname> attribute defines the response waiting time
in milliseconds. If a response isn't received within the timeout period, the
connection is aborted and the next request is sent. By default, the timeout is not set.
+ </para>
+ <para>
+ The <sgmltag><a4j:poll></sgmltag> component can be enabled
and disabled using the <varname>enabled</varname> attribute. Using Expression
Language (<acronym>EL</acronym>), the <varname>enabled</varname>
attribute can point to a bean property to apply a particular attribute value.
+ </para>
</section>
<section id="sect-Component_Reference-Actions-a4jpush">
<title><a4j:push></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.Push</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family:
<classname>org.ajax4jsf.components.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ renderer-type:
<classname>org.ajax4jsf.components.AjaxPushRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- Incomplete
+ The <sgmltag><a4j:push></sgmltag> component periodically
performs an Ajax request to the server, simulating "push" functionality. While
it is not strictly pushing updates, the request is made to minimal code only, not to the
<acronym>JSF</acronym> tree, checking for the presence of new messages in the
queue. The request registers <classname>EventListener</classname>, which
receives messages about events, but does not poll registered beans. If a message exists, a
complete request is performed. This is different from the
<sgmltag><a4j:poll></sgmltag> component, which performs a full
request at every interval.
</para>
+ <para>
+ The <varname>interval</varname> attribute specifies the time in
milliseconds between checking for messages. The default for this value is 1000 ms (1
second). It is possible to set the interval value to <literal>0</literal>, in
which case it is constantly checking for new messages.
+ </para>
+ <para>
+ The <varname>timeout</varname> attribute defines the response waiting time
in milliseconds. If a response isn't received within the timeout period, the
connection is aborted and the next request is sent. By default, the timeout is not set. In
combination with the <varname>interval</varname> attribute, checks for the
queue state can short polls or long connections.
+ </para>
</section>
</chapter>
Modified:
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_features.xml
===================================================================
---
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_features.xml 2009-12-17
18:52:56 UTC (rev 16164)
+++
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Common_features.xml 2009-12-18
07:05:05 UTC (rev 16165)
@@ -19,7 +19,7 @@
<section
id="sect-Component_Reference-Common_features-Calling_available_JavaScript_methods">
<title>Calling available JavaScript methods</title>
<para>
- Incomplete
+ Client-side JavaScript methods can be called using component events. These JavaScript
methods are defined using the relevant event attribute for the component tag.
</para>
</section>
Modified:
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml
===================================================================
---
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml 2009-12-17
18:52:56 UTC (rev 16164)
+++
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Containers.xml 2009-12-18
07:05:05 UTC (rev 16165)
@@ -7,7 +7,7 @@
<chapter id="chap-Component_Reference-Containers">
<title>Containers</title>
<para>
- Incomplete
+ This chapter details those components in the <classname>a4j</classname> tag
library which define an area used as a container or wrapper for other components.
</para>
<section id="sect-Component_Reference-Containers-a4jform">
<title><a4j:form></title>
Modified:
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml
===================================================================
---
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml 2009-12-17
18:52:56 UTC (rev 16164)
+++
root/docs/trunk/Component_Reference/en-US/chap-Component_Reference-Resources.xml 2009-12-18
07:05:05 UTC (rev 16165)
@@ -7,38 +7,196 @@
<chapter id="chap-Component_Reference-Resources">
<title>Resources</title>
<para>
- Incomplete
+ This chapter covers those components used to handle and manage resources and beans.
</para>
<section id="sect-Component_Reference-Resources-a4jloadBundle">
- <title>a4j:loadBundle</title>
+ <title><a4j:loadBundle></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.Bundle</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family: <classname>org.ajax4jsf.Bundle</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.AjaxLoadBundle</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- Incomplete
+ The <sgmltag><a4j:loadBundle></sgmltag> component is used to
load resource bundles to aid in localization of an application. The bundles are localized
to the locale of the current view, and properties are stored as a map in the current
request attributes.
</para>
+ <para>
+ The <sgmltag><a4j:loadBundle></sgmltag> component allows
bundles to be accessed by Ajax requests working in their own address scopes. This solves
the problem of using the <acronym>JSF</acronym>
<sgmltag><h:loadBundle></sgmltag> component with Ajax, where
bundle information loaded with the page was unavailable for later Ajax requests.
+ </para>
+ <para>
+ Resource bundles are registered in the Faces configuration file,
<filename>faces-config.xml</filename>.
+ </para>
+ <example id="exam-Component_Reference-Resources-a4jloadBundle">
+ <title><sgmltag><a4j:loadBundle></sgmltag>
example</title>
+ <para>
+ This example shows a simple application capable of switching between different
localized languages.
+ </para>
+ <procedure>
+ <step>
+ <title>Create resource bundles</title>
+ <para>
+ String resource bundles are contained in files with a <filename
class="extension">.properties</filename> extension. The files consist
of a list of entries, each with a unique name and a corresponding value. A seperate file
is required for each language. Append the filename with the locale identifier
(<literal>en</literal> for English, for example).
+ </para>
+ </step>
+ <step>
+ <title>Register bundles in Faces configuration file</title>
+ <para>
+ The resource bundles need to be registered in the Faces configuration file,
<filename>faces-config.xml</filename>. The filename is defined with the
<sgmltag><message-bundle></sgmltag> tag, without the locale code
and without the extension. The supported locale codes are listed with
<sgmltag><supported-locale></sgmltag> tags.
+ </para>
+<programlisting language="XML" role="XML">
+<xi:include parse="text"
href="extras/exam-Component_Reference-Resources-a4jloadBundle-0.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+ </step>
+ <step>
+ <title>Create method to set locale</title>
+ <para>
+ The <acronym>JSF</acronym>
<methodname>javax.faces.component.UIViewRoot.setLocale()</methodname> method
can be used to update the locale through a Java class:
+ </para>
+<programlisting language="java" role="JAVA">
+<xi:include parse="text"
href="extras/exam-Component_Reference-Resources-a4jloadBundle-1.js"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+ </step>
+ <step>
+ <title>Add <sgmltag><a4j:loadBundle></sgmltag> to
the <acronym>JSP</acronym> page</title>
+ <para>
+ The <sgmltag><a4j:loadBundle></sgmltag> component is
added to the application, and links to change the locale will update the displayed text.
+ </para>
+<programlisting language="XML" role="XML">
+<xi:include parse="text"
href="extras/exam-Component_Reference-Resources-a4jloadBundle-2.xml_sample"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+ </step>
+ </procedure>
+ <para>
+ Clicking on the different links will render the localized string as appropriate.
+ </para>
+ </example>
</section>
<section id="sect-Component_Reference-Resources-a4jloadScript">
- <title>a4j:loadScript</title>
+ <title><a4j:loadScript></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.LoadScript</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family: <classname>org.ajax4jsf.LoadScript</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.HtmlLoadScript</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ renderer-type: <classname>org.ajax4jsf.LoadScriptRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
- Incomplete
+ The <sgmltag><a4j:loadScript></sgmltag> component allows
scripts to be loaded from external sources such as <filename>jar</filename>
files.
</para>
+ <para>
+ The required <varname>src</varname> attribute defines the path to the
script. A leading slash (<literal>/</literal>) represents the root of the web
context. The <code>resource:///</code> prefix can be used to access a file in
the RichFaces resource framework.
+ </para>
</section>
<section id="sect-Component_Reference-Resources-a4jloadStyle">
- <title>a4j:loadStyle</title>
+ <title><a4j:loadStyle></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.Push</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family:
<classname>org.ajax4jsf.components.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ renderer-type:
<classname>org.ajax4jsf.components.AjaxPushRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
Incomplete
</para>
</section>
<section id="sect-Component_Reference-Resources-a4jkeepAlive">
- <title>a4j:keepAlive</title>
+ <title><a4j:keepAlive></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.Push</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family:
<classname>org.ajax4jsf.components.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ renderer-type:
<classname>org.ajax4jsf.components.AjaxPushRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
Incomplete
</para>
</section>
<section id="sect-Component_Reference-Resources-a4jmediaOutput">
- <title>a4j:mediaOutput</title>
+ <title><a4j:mediaOutput></title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ component-type: <classname>org.ajax4jsf.Push</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-family:
<classname>org.ajax4jsf.components.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component-class:
<classname>org.ajax4jsf.component.html.AjaxPush</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ renderer-type:
<classname>org.ajax4jsf.components.AjaxPushRenderer</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
Incomplete
</para>
Added:
root/docs/trunk/Component_Reference/en-US/extras/exam-Component_Reference-Resources-a4jloadBundle-0.xml_sample
===================================================================
---
root/docs/trunk/Component_Reference/en-US/extras/exam-Component_Reference-Resources-a4jloadBundle-0.xml_sample
(rev 0)
+++
root/docs/trunk/Component_Reference/en-US/extras/exam-Component_Reference-Resources-a4jloadBundle-0.xml_sample 2009-12-18
07:05:05 UTC (rev 16165)
@@ -0,0 +1,9 @@
+<application>
+ <locale-config>
+ <default-locale>en</default-locale>
+ <supported-locale>en</supported-locale>
+ <supported-locale>de</supported-locale>
+ <supported-locale>it</supported-locale>
+ </locale-config>
+ <message-bundle>demo.message</message-bundle>
+</application>