[seam-commits] Seam SVN: r8053 - trunk/doc/reference/en/modules.

[seam-commits at lists.jboss.org]

Author: pete.muir at jboss.org
Date: 2008-04-28 12:45:49 -0400 (Mon, 28 Apr 2008)
New Revision: 8053

Modified:
   trunk/doc/reference/en/modules/controls.xml
Log:
Document entity converter changes

Modified: trunk/doc/reference/en/modules/controls.xml
===================================================================
--- trunk/doc/reference/en/modules/controls.xml	2008-04-28 16:00:54 UTC (rev 8052)
+++ trunk/doc/reference/en/modules/controls.xml	2008-04-28 16:45:49 UTC (rev 8053)
@@ -242,15 +242,15 @@
           <entry valign="top">
             <para><emphasis>Description</emphasis></para>
             <para>
-               Assigns an entity converter to the current component.  This is primarily
+               Assigns an entity converter to the current component.  This is 
                useful for radio button and dropdown controls.
             </para>
 
             <para>
-              The converter works with any managed entity which has an <literal>@Id</literal> annotation -
-              either simple or composite.  The converter should be able to find the items declared in the
-              JSF controls (the currently selected, and the items available for selection), otherwise
-              you will receive a validation error.
+              The converter works with any managed entity - either simple or 
+              composite.  The converter should be able to find the items 
+              declared in the JSF controls on form submission, otherwise you 
+              will receive a validation error.
             </para>
 
             <para><emphasis>Attributes</emphasis></para>
@@ -262,47 +262,66 @@
             <para><emphasis>Configuration</emphasis></para>
 
             <para>
-              You must use <emphasis>Seam managed transactions</emphasis> (see <xref linkend="persistence.seam-managed-transactions" />) with <literal>&lt;s:convertEntity /&gt;</literal>.
+              You must use <emphasis>Seam managed transactions</emphasis> 
+              (see <xref linkend="persistence.seam-managed-transactions" />) 
+              with <literal>&lt;s:convertEntity /&gt;</literal>.
             </para>
 
             <para>
-              If your <emphasis>Managed Persistence Context</emphasis> isn't called
-              <literal>entityManager</literal>, then you need to set it in components.xml:
+              If your <emphasis>Managed Persistence Context</emphasis> isn't 
+              called <literal>entityManager</literal>, then you need to set it 
+              in components.xml:
             </para>
-            <programlisting><![CDATA[<component name="org.jboss.seam.ui.EntityConverter">
-  <property name="entityManager">#{em}</property>
-</component>]]></programlisting>
+            <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+            xmlns:ui="http://jboss.com/products/seam/ui">
+            
+   <ui:entity-loader entity-manager="#{em}" />]]></programlisting>
 
             <para>
               If you are using a <emphasis>Managed Hibernate Session</emphasis> 
               then you need to set it in components.xml:
             </para>
-            <programlisting><![CDATA[<component name="org.jboss.seam.ui.EntityConverter">
-  <property name="session">#{hibernateSession}</property>
-</component>]]></programlisting>
+            <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+            xmlns:ui="http://jboss.com/products/seam/ui">
+            
+   <ui:hibernate-entity-loader />]]></programlisting>
+            
+            <para>
+              If your <emphasis>Managed Hibernate Session</emphasis> isn't 
+              called <literal>session</literal>, then you need to set it 
+              in components.xml:
+            </para>
+            
+            <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+            xmlns:ui="http://jboss.com/products/seam/ui">
+            
+   <ui:hibernate-entity-loader session="#{hibernateSession}" />]]></programlisting>
 
             <para>
               If you want to use more than one entity manager with the entity 
               converter, you can create a copy of the entity converter for each
-              entity manager in components.xml:
+              entity manager in <literal>components.xml</literal> - note how 
+              the entity converter delegates to the entity loader to perform
+              persistence operations:
             </para>
             
-            <programlisting><![CDATA[<component name="myEntityConverter" class="org.jboss.seam.ui.converter.EntityConverter">
-  <property name="entityManager">#{em}</property>
-</component>]]></programlisting>
+            <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+            xmlns:ui="http://jboss.com/products/seam/ui">
+            
+   <ui:entity-converter name="standardEntityConverter" entity-loader="#{standardEntityLoader}" />
+            
+   <ui:entity-loader name="standardEntityLoader" entity-manager="#{standardEntityManager}" />
+   
+   <ui:entity-converter name="restrictedEntityConverter" entity-loader="#{restrictedEntityLoader}" />
+            
+   <ui:entity-loader name="restrictedEntityLoader" entity-manager="#{restrictedEntityManager}" />]]></programlisting>
 
             <programlisting><![CDATA[<h:selectOneMenu value="#{person.continent}">
   <s:selectItems value="#{continents.resultList}" var="continent" 
                  label="#{continent.name}" />
-    <f:converter converterId="myEntityConverter" />
+    <f:converter converterId="standardEntityConverter" />
 </h:selectOneMenu>]]></programlisting>
 
-            <para>
-              If a page uses more than one entity manager for rendering, the
-              above standard reference to the converter is obligatory. Otherwise
-              the converter's entity loader might show unexpected behavior.
-            </para>
-
             <para><emphasis>Usage</emphasis></para>
             <programlisting><![CDATA[<h:selectOneMenu value="#{person.continent}" required="true">
   <s:selectItems value="#{continents.resultList}" var="continent"