<?xml version='1.0' encoding='UTF-8'?>
<section>
<sectioninfo>
<keywordset>
<keyword>HtmlDataDefinitionList</keyword>
<keyword>rich:dataDefinitionList</keyword>
</keywordset>
</sectioninfo>
  
    <table>
      <title>Component identification parameters </title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Name</entry>
            <entry>Value</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>component-type</entry>
            <entry>org.richfaces.DataDefinitionList</entry>
          </row>
          <row>
            <entry>component-class</entry>
            <entry>org.richfaces.component.html.HtmlDataDefinitionList</entry>
          </row>
          <row>
          <entry>component-family</entry>
          <entry>org.richfaces.DataDefinitionList</entry>
          </row>
          <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.DataDefinitionListRenderer</entry>
          </row>          
          <row>
            <entry>tag-class</entry>
            <entry>org.richfaces.taglib.DataDefinitionListTag</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  
  <section>
    <title>Creating the Component with a Page Tag</title>
    <para>To create the simplest variant of <property>dataDefinitionList</property> on a page, use the following syntax:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <rich:dataDefinitionList value="#{bean.capitals}" var="caps">
        <f:facet name="term">Cars</f:facet>
        <h:outputText value="#{car.model}"/>
    </rich:dataDefinitionList>
...
]]></programlisting>
    </section>
  
  <section>
  <title>Creating the Component Dynamically Using Java</title>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
  <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlDataDefinitionList;
...
HtmlDataDefinitionList myList = new HtmlDataDefinitionList();
...
]]></programlisting>
</section>
<section>
<title>Details of Usage</title>
  <para>The <emphasis role="bold">
    <property>&lt;rich:dataDefinitionList&gt;</property>
  </emphasis> component allows to generate an definition list from a model.</para>
  <para>The component has the <emphasis>
    <property>&quot;term&quot;</property>
  </emphasis> facet, which corresponds to the <emphasis>
    <property>&quot;type&quot;</property>
  </emphasis> parameter for the <emphasis role="bold">
    <property>&lt;DT&gt;</property>
  </emphasis> HTML element.</para>
  <para>Here is an example:</para>
  
  <programlisting role="XML"><![CDATA[...
    <h:form>
        <rich:dataDefinitionList var="car" value="#{dataTableScrollerBean.allCars}" rows="5" first="4" title="Cars">
            <f:facet name="term">
                <h:outputText value="#{car.make} #{car.model}"></h:outputText>
            </f:facet>
            <h:outputText value="Price:" styleClass="label"></h:outputText>
            <h:outputText value="#{car.price}" /><br/>
            <h:outputText value="Mileage:" styleClass="label"></h:outputText>
            <h:outputText value="#{car.mileage}" /><br/>
        </rich:dataDefinitionList>
    </h:form>
...
]]></programlisting>
  
  <para>This is a result:</para>
  
  <figure>
    <title><emphasis role="bold">
      <property>&lt;rich:dataDefinitionList&gt;</property>
    </emphasis> component with <emphasis>
      <property>&quot;term&quot;</property>
    </emphasis> facet</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="images/dataDefinitionList2.png"/>
      </imageobject>
    </mediaobject>
  </figure>
  
  <para>In the example the <emphasis>
    <property>&quot;rows&quot;</property>
  </emphasis> attribute limits number of output elements of the list.</para>
  
  <para><emphasis>
    <property>&quot;first&quot;</property>
  </emphasis> attribute defines first element for output. <emphasis>
    <property>&quot;title&quot;</property>
  </emphasis> are used for popup title.</para>
  
  <para>The component was created basing on the <emphasis role="bold">
    <property>&lt;a4j:repeat&gt;</property>
  </emphasis> component and as a result it could be partially updated with Ajax. <emphasis>
    <property>The &quot;ajaxKeys&quot;</property>
  </emphasis> attribute allows to define row keys that are updated after an Ajax request, you need to pass an array with key (lines) of the list that you want to be updated after the Ajax request is executed.</para>
  <para>Here is an example:</para>
  
  <para>
    <emphasis role="bold">Example:</emphasis>
  </para>
  <programlisting role="XML"><![CDATA[...
    <rich:dataDefinitionList value="#{dataTableScrollerBean.allCars}" var="car" ajaxKeys="#{listBean.list}" 
                        binding="#{listBean.dataList}" id="list">
        ...
    </rich:dataDefinitionList>
...
    <a4j:commandButton action="#{listBean.action}" reRender="list" value="Submit"/>
...
]]></programlisting>
  
  <para> In the example <emphasis>
    <property>&quot;reRender&quot;</property>
  </emphasis> attribute contains value of <emphasis>
    <property>&quot;id&quot;</property>
  </emphasis> attribute for <emphasis role="bold">
    <property>&lt;rich:dataDefinitionList&gt;</property>
  </emphasis> component. As a result the component is updated after an Ajax request.</para>
  
</section>
  
 <section>
   
   <title>Look-and-Feel Customization</title>
   
   <para>For skinnability implementation, the components use a <emphasis>
     <property>style class redefinition method.</property>
   </emphasis> Default style classes are mapped on <emphasis>
     <property>skin parameters.</property>
   </emphasis></para>
   
   <para>There are two ways to redefine the appearance of all <emphasis role="bold">
     <property>&lt;rich:dataDefinitionList&gt;</property>
   </emphasis> components at once:</para>
   
   <itemizedlist>
     <listitem>
       <para>Redefine the corresponding skin parameters</para>
     </listitem>
     
     <listitem>
       <para>Add to your style sheets <emphasis>
         <property>style classes</property>
       </emphasis> used by a <emphasis role="bold">
         <property>&lt;rich:dataDefinitionList&gt;</property>
       </emphasis> component</para>
     </listitem>
   </itemizedlist>
 
 </section>
  
		 <section>
		   <title>Definition of Custom Style Classes</title>
		   
		   <para>On the screenshot there are classes names that define styles for component elements.</para>
		   
		   <figure>
		     <title>Style classes</title>
		     <mediaobject> 
		       <imageobject>
		         <imagedata fileref="images/dataDefinitionList_cn.png"/>
		       </imageobject>
		     </mediaobject>
		   </figure>
		   
		   <table id="tab_dDL">
		     <title>Classes names that define a list appearance</title>
		     <tgroup cols="2">
		       <thead>
		         <row>
		           <entry>Class name</entry>
		           <entry>Description</entry>
		         </row>
		       </thead>
		       <tbody>
		         <row>
		           <entry>rich-deflist</entry>
		           <entry>Defines styles for an html &lt;dl&gt; element</entry>
		         </row>
		         <row>
		           <entry>rich-definition</entry>
		           <entry>Defines styles for an html &lt;dd&gt; element</entry>
		         </row>
		         <row>
		           <entry>rich-definition-term</entry>
		           <entry>Defines styles for an html &lt;dt&gt; element</entry>
		         </row>
		       </tbody>
		     </tgroup>
		   </table>
		 
		   <para>In order to redefine styles for all <emphasis role="bold">
		     <property>&lt;rich:dataDefinitionList&gt;</property>
		   </emphasis> components on a page using CSS, it&apos;s enough to create classes with the
		     same names (possible classes could be found in the tables <link linkend="tab_dDL"> above</link>) and define necessary properties in them. </para>
		   
		   <para>
		     <emphasis role="bold">Example:</emphasis>
		   </para>
		   <programlisting role="CSS"><![CDATA[...
.rich-definition-term{
	font-weight:bold;
}
...]]></programlisting>  
		   
		   <para>This is a result:</para>
		   
		   <figure>
		     <title>Redefinition styles with predefined classes</title>
		     <mediaobject>
		       <imageobject>
		         <imagedata fileref="images/dataDefinitionList_pc.png"/>
		       </imageobject>
		     </mediaobject>
		   </figure>
		   
		   <para>In the example a term font weight was changed.</para>
		   
		   <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
		     ><property>&lt;rich:dataDefinitionList&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
		       ><property>&lt;rich:dataDefinitionList&gt;</property></emphasis> <emphasis><property>styleClass</property></emphasis> attributes. An example is placed below:</para>
		   
		   <para>
		     <emphasis role="bold">Example:</emphasis>
		   </para>
		   <programlisting role="CSS"><![CDATA[...
.myClass{
	font-style: italic;
}
...]]></programlisting>  
		   <para>
		     <emphasis role="bold">Example:</emphasis>
		   </para>
		   <programlisting role="XML"><![CDATA[<rich:dataDefinitionList ... rowClasses="myClass"/>
]]></programlisting>    
		   
		   <para>This is a result:</para>
		   
		   <figure>
		     <title>Redefinition styles with own classes and <emphasis><property>styleClass</property></emphasis> attributes</title>
		     <mediaobject>
		       <imageobject>
		         <imagedata fileref="images/dataDefinitionList_oc.png"/>
		       </imageobject>
		     </mediaobject>
		   </figure>  
		   
		   <para>As it could be seen on the picture above, the font style for rows was changed.</para>
           </section>
  <section>
    <title>Relevant Resources Links</title>
    <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataLists.jsf?c=dataDefinitionList"
      >On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold"
        ><property>&lt;rich:dataDefinitionList&gt;</property></emphasis> usage and sources for the given example. </para>
  </section>             
</section>
