[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Tue Oct 24 09:09:23 EDT 2006
User: gavin
Date: 06/10/24 09:09:23
Modified: doc/reference/en/modules elenhancements.xml
Log:
revised
Revision Changes Path
1.2 +87 -103 jboss-seam/doc/reference/en/modules/elenhancements.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: elenhancements.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/elenhancements.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- elenhancements.xml 20 Oct 2006 01:46:23 -0000 1.1
+++ elenhancements.xml 24 Oct 2006 13:09:23 -0000 1.2
@@ -1,126 +1,110 @@
<chapter id="elenhancements">
-
- <title>Action Params</title>
-
-
+ <title>Expression language enhancements</title>
<para>
-
- The current Unified Expression Language (EL) assumes that any parameters to a MethodExpression will be provided by Java code.
- Seam provides an enhancement to the EL that allows parameters to be passed to a MethodExpression from within the expression itself.
- In a Seam application, this is useful when an action is specified as an attribute to a <![CDATA[<h:commandLink>, <h:commandButton>, <s:link>]]>, or in <literal>pages.xml.</literal>
-
+ The standard Unified Expression Language (EL) assumes that any parameters to a method expression will be
+ provided by Java code. This means that a method with parameters cannot be used as a JSF method binding.
+ Seam provides an enhancement to the EL that allows parameters to be included in a method expression
+ itself. This applies to <emphasis>any</emphasis> Seam method expression, including any JSF method binding,
+ for example:
</para>
- <programlisting><![CDATA[<s:commandButton action="#{hotelBooking.bookHotel(hotel, user)}" class="button" value="Book Hotel" />]]></programlisting>
+ <programlisting><![CDATA[<s:commandButton action="#{hotelBooking.bookHotel(hotel)}" value="Book Hotel"/>]]></programlisting>
<section>
-
- <title>Setup</title>
+ <title>Configuration</title>
<para>
- To enable the action params feature in Facelets, you will need to add Seam's SeamFaceletViewHandler in your faces-config.xml.
- For JSP applications using JSF 1.1, this is automatically enabled.
+ To use this feature in Facelets, you will need to declare a special view handler,
+ <literal>SeamFaceletViewHandler</literal> in <literal>faces-config.xml</literal>.
</para>
- <programlisting><![CDATA[
-<faces-config>
+ <programlisting><![CDATA[<faces-config>
<application>
<view-handler>org.jboss.seam.ui.facelet.SeamFaceletViewHandler</view-handler>
</application>
</faces-config>]]></programlisting>
</section>
-
-
<section>
-
<title>Usage</title>
<para>
- The Action Params feature allows you to specify parameters when using the EL to call an action. So I can have something like this:
- </para>
-
- <programlisting><![CDATA[
-<h:commandButton action="#{hotelBooking.bookHotel(hotel, user)}" class="button" value="Book Hotel" />]]></programlisting>
-
- <para>
- The parameters <literal>hotel</literal> and <literal>user</literal> will be evaluated as ValueExpressions and passed into the bookHotel method of your managed bean.
- This gives you an alternative to @In which forces injection to happen on every action method called.
+ Parameters are surrounded by parentheses, and separated by commas:
</para>
- <para>You can also pass in literal Strings using single or double quotes:</para>
-
- <programlisting><![CDATA[
- <h:commandLink action=â€#{foo.bar( ‘Here is my message’ )}†value=â€Click Here†/>
- <h:commandLink action=’#{foo.bar( “Here is my message†)}’ value=’Click Here’ />]]></programlisting>
-
-
+ <programlisting><![CDATA[<h:commandButton action="#{hotelBooking.bookHotel(hotel, user)}" value="Book Hotel"/>]]></programlisting>
<para>
- You might want to use this notation for all of your action methods, even when you don’t have params to pass.
- This improves readability by making it clear that the expression is a MethodExpression and not a ValueExpression:
+ The parameters <literal>hotel</literal> and <literal>user</literal> will be evaluated as
+ value expressions and passed to the <literal>bookHotel()</literal> method of the component.
+ This gives you an alternative to the use of <literal>@In</literal>.
</para>
- <programlisting><![CDATA[
- <s:link value="Cancel" action="#{ hotelBooking.cancel() }" buttonClass="button" linkStyle="button"/>]]></programlisting>
<para>
- This is also very handy for passing in JSF implicit objects such as <literal>facesContext</literal> and <literal>view</literal>.
+ You may pass literal strings using single or double quotes:
</para>
- <programlisting><![CDATA[
- <page view-id="/mypage.jsp" action="#{foo.myMethod(facesContext, view)}" />]]></programlisting>
+ <programlisting><![CDATA[<h:commandLink action=â€#{printer.println( ‘Hello world!’ )}†value=â€Helloâ€/>]]></programlisting>
+ <programlisting><![CDATA[<h:commandLink action=’#{printer.println( “Hello again†)}’ value=’Hello’/>]]></programlisting>
<para>
- If you desire, you can still use the [ ] operator as defined in the EL spec.
- If you do, you should put both the method and the params inside the [ ]:
+ You might even want to use this notation for all your action methods, even when you don’t
+ have parameters to pass. This improves readability by making it clear that the expression is
+ a method expression and not a value expression:
</para>
- <programlisting><![CDATA[
- <h:commandLink action=â€#{ foo[ bar( facesContext ) ] }†value=â€Click Here†/>]]></programlisting>
+ <programlisting><![CDATA[<s:link value="Cancel" action="#{hotelBooking.cancel()}"/>]]></programlisting>
</section>
<section>
-
<title>Limitations</title>
<para>
- The action params feature has a couple of limitations to be aware of.
+ Please be aware of the following limitations:
</para>
<section>
<title>Incompatibility with JSP 2.1</title>
<para>
- Action params can not currently be used with JSF 1.2 and JSP 2.1. If you want to use JSF 1.2 with the action params feature, you will need to use Facelets.
- Action params will always work with JSF 1.1.
+ This extension is not currently compatible with JSP 2.1. So if you want to use this extension
+ with JSF 1.2, you will need to use Facelets. The extension works correctly with JSP 2.0.
</para>
</section>
<section>
- <title>Limitations when calling a MethodExpression from Java code</title>
+ <title>Calling a <literal>MethodExpression</literal> from Java code</title>
<para>
- Normally, when a MethodExpression or MethodBinding is created, the parameter types are passed in by the JSF framework.
- In the case of an action, JSF assumes that there are no params to pass. With action params in an expression, you can’t know the param types until the parameters are evaluated.
- Evaluation of the params doesn’t happen until the MethodExpression is invoked. This has two minor consequences:
+ Normally, when a <literal>MethodExpression</literal> or <literal>MethodBinding</literal> is created,
+ the parameter types are passed in by JSF. In the case of a method binding, JSF assumes that there
+ are no parameters to pass. With this extension, we can’t know the parameter types until after the
+ expression has been evaluated. This has two minor consequences:
+ </para>
+
<itemizedlist>
<listitem>
<para>
- If you call invoke on the MethodExpression by hand, any params you pass may be ignored. Params defined in the expression will take precedence.
+ When you invoke a <literal>MethodExpression</literal> in Java code, parameters you pass may
+ be ignored. Parameters defined in the expression will take precedence.
</para>
</listitem>
<listitem>
<para>
- Since Facelets uses MethodExpression instead of MethodBinding, you would normally be able to call
- <literal>myMethodExpression.getMethodInfo().getParamTypes()</literal> at any time.
- For an expression containing action params, you will only be able to do this after the method has been invoked at least once.
+ Ordinarily, it is safe to call <literal>methodExpression.getMethodInfo().getParamTypes()</literal>
+ at any time. For an expression with parameters, you must first invoke the
+ <literal>MethodExpression</literal> before calling <literal>getParamTypes()</literal>.
</para>
</listitem>
</itemizedlist>
- Both of these cases are exceedingly rare and only apply when you want to invoke the MethodExpression by hand in Java code.
+
+ <para>
+ Both of these cases are exceedingly rare and only apply when you want to invoke the
+ <literal>MethodExpression</literal> by hand in Java code.
</para>
- </section>
+
</section>
+ </section>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list