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

Author: pete.muir(a)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"