[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Tue Jan 16 21:52:11 EST 2007
User: gavin
Date: 07/01/16 21:52:11
Modified: doc/reference/en/modules controls.xml events.xml
Added: doc/reference/en/modules text.xml
Log:
doc text and navigation
Revision Changes Path
1.12 +8 -0 jboss-seam/doc/reference/en/modules/controls.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: controls.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/controls.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- controls.xml 13 Dec 2006 02:52:15 -0000 1.11
+++ controls.xml 17 Jan 2007 02:52:11 -0000 1.12
@@ -28,6 +28,14 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><literal><s:formattedText></literal></term>
+ <listitem>
+ <para>
+ Output <emphasis>Seam Text</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><literal><s:convertDateTime></literal></term>
<listitem>
<para>
1.8 +186 -1 jboss-seam/doc/reference/en/modules/events.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: events.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/events.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- events.xml 14 Dec 2006 07:14:10 -0000 1.7
+++ events.xml 17 Jan 2007 02:52:11 -0000 1.8
@@ -227,6 +227,191 @@
</sect3>
<sect3>
+ <title>Navigation</title>
+
+ <para>
+ You can use standard JSF navigation rules defined in <literal>faces-config.xml</literal>
+ in a Seam application. However, JSF navigation rules have a number of annoying
+ limitations:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ It is not possible to specify request parameters to be used when redirecting.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It is not possible to begin or end conversations from a rule.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rules work by evaluating the return value of the action method; it is not
+ possible to evaluate an arbitrary EL expression.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ A further problem is that "orchestration" logic gets scattered between <literal>pages.xml</literal>
+ and <literal>faces-config.xml</literal>. It's better to unify this logic into <literal>pages.xml</literal>.
+ </para>
+
+ <para>
+ This JSF navigation rule:
+ </para>
+
+ <programlisting><![CDATA[<navigation-rule>
+ <from-view-id>/editDocument.xhtml</from-view-id>
+
+ <navigation-case>
+ <from-action>#{documentEditor.update}</from-action>
+ <from-outcome>success</from-outcome>
+ <to-view-id>/viewDocument.xhtml</to-view-id>
+ <redirect/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ Can be rewritten as follows:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}">
+ <rule if-outcome="success">
+ <redirect view-id="/viewDocument.xhtml"/>
+ <rule/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ But it would be even nicer if we didn't have to pollute our <literal>DocumentEditor</literal>
+ component with string-valued return values (the JSF outcomes). So Seam lets us write:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}"
+ evaluate="#{documentEditor.errors.size}">
+ <rule if-outcome="0">
+ <redirect view-id="/viewDocument.xhtml"/>
+ <rule/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ Or even:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}">
+ <rule if="#{documentEditor.errors.empty}">
+ <redirect view-id="/viewDocument.xhtml"/>
+ <rule/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ The first form evaluates a value binding to determine the outcome value
+ to be used by the subsequent rules.
+ The second approach ignores the outcome and evaluates a value binding
+ for each possible rule.
+ </para>
+
+ <para>
+ Of course, when an update succeeds, we probably want to end the current
+ conversation. We can do that like this:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}">
+ <rule if="#{documentEditor.errors.empty}">
+ <end-conversation/>
+ <redirect view-id="/viewDocument.xhtml"/>
+ <rule/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ But ending the conversation loses any state associated with the conversation,
+ including the document we are currently interested in! One solution would be
+ to use an immediate render instead of a redirect:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}">
+ <rule if="#{documentEditor.errors.empty}">
+ <end-conversation/>
+ <render view-id="/viewDocument.xhtml"/>
+ <rule/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ But the correct solution is to pass the document id as a request parameter:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}">
+ <rule if="#{documentEditor.errors.empty}">
+ <end-conversation/>
+ <redirect view-id="/viewDocument.xhtml">
+ <param name="documentId" value="#{documentEditor.documentId}"/>
+ </redirect>
+ <rule/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ Null outcomes are a special case in JSF. The null outcome is interpreted to
+ mean "redisplay the page". The following navigation rule matches any non-null
+ outcome, but <emphasis>not</emphasis> the null outcome:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}">
+ <rule>
+ <render view-id="/viewDocument.xhtml"/>
+ <rule/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+ <para>
+ If you want to perform navigation when a null outcome occurs, use the
+ following form instead:
+ </para>
+
+ <programlisting><![CDATA[<page view-id="/editDocument.xhtml">
+
+ <navigation from-action="#{documentEditor.update}">
+ <render view-id="/viewDocument.xhtml"/>
+ </navigation-case>
+
+</navigation-rule>]]></programlisting>
+
+
+
+ </sect3>
+
+
+
+ <sect3>
<title>Fine-grained files for definition of page actions and parameters</title>
<para>
If you have a lot of different page actions and page parameters,
1.1 date: 2007/01/17 02:52:11; author: gavin; state: Exp;jboss-seam/doc/reference/en/modules/text.xml
Index: text.xml
===================================================================
<chapter id="text">
<title>Seam Text</title>
<para>
Collaboration-oriented websites require a human-friendly markup language for easy entry
of formatted text in forum posts, wiki pages, blogs, comments, etc. Seam provides the
<literal><s:formattedText/></literal> control for display of formatted text that
conforms to the <emphasis>Seam Text</emphasis> language. Seam Text is implemented using
an ANTLR-based parser. You don't need to know anything about ANTLR to use it, however.
</para>
<section>
<title>Basic fomatting</title>
<para>
Here is a simple example:
</para>
<programlisting><![CDATA[It's easy to make *bold text*, /italic text/, |monospace|,
-deleted text-, super^scripts^ or _underlines_.]]></programlisting>
<para>
If we display this using <literal><s:formattedText/></literal>, we will get
the following HTML produced:
</para>
<programlisting><![CDATA[<p>
It's easy to make <b>bold text</b>, <i>italic text</i>, <tt>monospace</tt>
<del>deleted text</del>, super<sup>scripts</sup> or <u>underlines</u>.
</p>]]></programlisting>
<para>
We can use a blank line to indicate a new paragraph, and <literal>+</literal> to
indicate a heading:
</para>
<programlisting><![CDATA[+This is a big heading
You /must/ have some text following a heading!
++This is a smaller heading
This is the first paragraph. We can split it across multiple
lines, but we must end it with a blank line.
This is the second paragraph.]]></programlisting>
<para>
This is the HTML that results:
</para>
<programlisting><![CDATA[<h1>This is a big heading</h1>
<p>
You <i>must</i> have some text following a heading!
</p>
<h2>This is a smaller heading</h2>
<p>
This is the first paragraph. We can split it across multiple
lines, but we must end it with a blank line.
</p>
<p>
This is the second paragraph.
</p>]]></programlisting>
<para>
Ordered lists are created using the <literal>#</literal> character. Unordered lists
use the <literal>=</literal> character:
</para>
<programlisting><![CDATA[An ordered list:
#first item
#second item
#and even the /third/ item
An unordered list:
=an item
=another item]]></programlisting>
<programlisting><![CDATA[<p>
An ordered list:
</p>
<ol>
<li>first item</li>
<li>second item</li>
<li>and even the <i>third</i> item</li>
</ol>
<p>
An unordered list:
</p>
<ul>
<li>an item</li>
<li>another item</li>
</ul>]]></programlisting>
<para>
Quoted sections should be surrounded in double quotes:
</para>
<programlisting><![CDATA[The other guy said:
"Nyeah nyeah-nee
/nyeah/ nyeah!"
But what do you think he means by "nyeah-nee"?]]></programlisting>
<programlisting><![CDATA[<p>
The other guy said:
</p>
<quote>Nyeah nyeah-nee
<i>nyeah</i> nyeah!</quote>
<p>
But what do you think he means by <quote>nyeah-nee</quote>?
</p>]]></programlisting>
</section>
<section>
<title>Entering code and text with special characters</title>
<para>
Special characters such as <literal>*</literal>, <literal>|</literal>
and <literal>#</literal>, along with HTML characters such as
<literal><</literal>, <literal>></literal> and <literal>&</literal>
may be escaped using <literal>\</literal>:
</para>
<programlisting><![CDATA[You can write down equations like 2\*3\=6 and HTML tags
like \<body\> using the escape character: \\.]]></programlisting>
<programlisting><![CDATA[<p>
You can write down equations like 2*3=6 and HTML tags
like <body> using the escape character: \.
</p>]]></programlisting>
<para>
And we can quote code blocks using backticks:
</para>
<programlisting><![CDATA[My code doesn't work:
`for (int i=0; i<100; i--)
{
doSomething();
}`
Any ideas?]]></programlisting>
<programlisting><![CDATA[<p>
My code doesn't work:
</p>
<pre>for (int i=0; i<100; i--)
{
doSomething();
}</pre>
<p>
Any ideas?
</p>]]></programlisting>
</section>
<section>
<title>Entering HTML</title>
<para>
Text may even include a certain limited subset of HTML (don't worry, the subset is chosen
to be safe from cross-site scripting attacks). This is useful for creating links:
</para>
<programlisting><![CDATA[You might want to link to <a href="http://jboss.com/products/seam">something
cool</a>, or even include an image: <img src="/logo.jpg"/>]]></programlisting>
<para>
And for creating tables:
</para>
<programlisting><![CDATA[<table>
<tr><td>First name:</td><td>Gavin</td></tr>
<tr><td>Last name:</td><td>King</td></tr>
</table>]]></programlisting>
<para>
But you can do much more if you want!
</para>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list