Author: atsebro
Date: 2008-08-15 11:49:39 -0400 (Fri, 15 Aug 2008)
New Revision: 10120
Modified:
trunk/docs/userguide/en/src/main/docbook/included/columns.xml
Log:
RF-4102: Columns: use restriction.
Adding the note to the end of the "Details of usage" section
Modified: trunk/docs/userguide/en/src/main/docbook/included/columns.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/columns.xml 2008-08-15 15:44:28 UTC
(rev 10119)
+++ trunk/docs/userguide/en/src/main/docbook/included/columns.xml 2008-08-15 15:49:39 UTC
(rev 10120)
@@ -1,27 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<section>
- <sectioninfo>
- <keywordset>
- <keyword>rich:columns</keyword>
- <keyword>columns</keyword>
- </keywordset>
- </sectioninfo>
- <table>
- <title>Component identification parameters</title>
+ <sectioninfo>
+ <keywordset>
+ <keyword>rich:columns</keyword>
+ <keyword>columns</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.Column</entry>
- </row>
- <!--row>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+
<entry>component-type</entry>
+
<entry>org.richfaces.Column</entry>
+ </row>
+ <!--row>
<entry>component-class</entry>
<entry></entry>
</row>
@@ -33,84 +33,62 @@
<entry>renderer-type</entry>
<entry></entry>
</row-->
- <row>
- <entry>tag-class</entry>
- <entry>
- org.richfaces.taglib.ColumnsTagHandler
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <section>
- <title>Creating the Component with a Page Tag</title>
- <para>
- To create the simplest variant on a page use the following
- syntax:
- </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
+ <row>
+ <entry>tag-class</entry>
+ <entry>
org.richfaces.taglib.ColumnsTagHandler
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <section>
+ <title>Creating the Component with a Page Tag</title>
+ <para> To create the simplest variant on a page use the
following syntax: </para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
<rich:columns value="#{capitalsBean.labels}" var="col"
index="index">
<h:outputText value="#{cap[index]}" />
</rich:columns>
</rich:dataTable>
...]]></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.HtmlColumns;
+ </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.HtmlColumns;
...
HtmlColumns myColumns = new HtmlColumns();
...]]></programlisting>
- </section>
- <section>
- <title>Details of Usage</title>
- <para>
- The
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- component gets a list from data model and outputs
- corresponding set of columns inside
- <emphasis role="bold">
- <property><rich:dataTable></property>
- </emphasis>
- on a page. It is possible to use
- <emphasis>
- <property>"header"</property>
- </emphasis>
- and
- <emphasis>
- <property>"footer"</property>
- </emphasis>
- facets with
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- component.
- </para>
- <para>
- The
- <emphasis>
- <property>"value"</property>
- </emphasis>
- and
- <emphasis>
- <property>"var"</property>
- </emphasis>
- attributes are used to access the values of collection.
- </para>
- <para>The simple example is placed below.</para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
+ </section>
+ <section>
+ <title>Details of Usage</title>
+ <para> The <emphasis role="bold">
+
<property><rich:columns></property>
+ </emphasis> component gets a list from data model and
outputs
+ corresponding set of columns inside <emphasis
role="bold">
+
<property><rich:dataTable></property>
+ </emphasis> on a page. It is possible to use
<emphasis>
+
<property>"header"</property>
+ </emphasis> and <emphasis>
+
<property>"footer"</property>
+ </emphasis> facets with <emphasis
role="bold">
+
<property><rich:columns></property>
+ </emphasis> component. </para>
+ <para> The <emphasis>
+
<property>"value"</property>
+ </emphasis> and <emphasis>
+
<property>"var"</property>
+ </emphasis> attributes are used to access the values
of collection. </para>
+ <para>The simple example is placed below.</para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
<rich:columns value="#{capitalsBean.labels}" var="col"
index="index">
<f:facet name="header">
@@ -123,46 +101,27 @@
</rich:columns>
</rich:dataTable>
...]]></programlisting>
- <para>
- The
- <emphasis>
- <property>"columns"</property>
- </emphasis>
- attribute defines the count of columns.
- </para>
- <para>
- The
- <emphasis>
- <property>"rows"</property>
- </emphasis>
- attribute defines the number of rows to be displayed. If the
- value of this attribute is zero, all remaining rows in the
- table are displayed on a page.
- </para>
- <para>
- The
- <emphasis>
- <property>"begin"</property>
- </emphasis>
- attribute contains the first iteration item. Note, that
- iteration begins from zero.
- </para>
- <para>
- The
- <emphasis>
- <property>"end"</property>
- </emphasis>
- attribute contains the last iteration item.
- </para>
- <para>
- With the help of the attributes described below you can
- customize the output, i.e. define which columns and how many
- rows appear on a page.
- </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
+ <para> The <emphasis>
+
<property>"columns"</property>
+ </emphasis> attribute defines the count of columns.
</para>
+ <para> The <emphasis>
+
<property>"rows"</property>
+ </emphasis> attribute defines the number of rows to
be displayed. If
+ the value of this attribute is zero, all remaining rows in
the table
+ are displayed on a page. </para>
+ <para> The <emphasis>
+
<property>"begin"</property>
+ </emphasis> attribute contains the first iteration
item. Note, that
+ iteration begins from zero. </para>
+ <para> The <emphasis>
+
<property>"end"</property>
+ </emphasis> attribute contains the last iteration
item. </para>
+ <para> With the help of the attributes described below you can
customize the
+ output, i.e. define which columns and how many rows appear
on a page. </para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{capitalsBean.capitals}" var="cap">
<rich:columns value="#{capitalsBean.labels}" var="col"
index="index" rows="0" columns="3" begin="1"
end="2">
<f:facet name="header">
@@ -172,45 +131,31 @@
</rich:columns>
</rich:dataTable>
...]]></programlisting>
- <para>
- In the example below, columns from first to second and all
- rows are shown in the
- <emphasis role="bold">
- <property><rich:dataTable></property>
- </emphasis>
- .
- </para>
- <para>The result is:</para>
- <figure>
- <title>
- Generated
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- with columns from first to second and all rows
- </title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/columns2.png" />
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- The
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- component does not prevent to use
- <emphasis role="bold">
- <property><rich:column></property>
- </emphasis>
- . In the following example one column renders in any way and
- another columns could be picked from the model.
- </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
+ <para> In the example below, columns from first to second and
all rows are shown
+ in the <emphasis role="bold">
+
<property><rich:dataTable></property>
+ </emphasis> . </para>
+ <para>The result is:</para>
+ <figure>
+ <title> Generated <emphasis
role="bold">
+
<property><rich:columns></property>
+ </emphasis> with columns from first to
second and all rows </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/columns2.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para> The <emphasis role="bold">
+
<property><rich:columns></property>
+ </emphasis> component does not prevent to use
<emphasis role="bold">
+
<property><rich:column></property>
+ </emphasis> . In the following example one column
renders in any way
+ and another columns could be picked from the model.
</para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{rowBean.rows}" var="row">
<rich:column>
<h:outputText value ="#{row.columnValue}"/>
@@ -227,23 +172,17 @@
</rich:dataTable>
...]]></programlisting>
- <para>
- In order to group columns with text information into one
- row, use the
- <emphasis>
- <property>"colspan"</property>
- </emphasis>
- attribute, which is similar to an HTML one. In the following
- example the third column contains 3 columns. In addition,
- it's necessary to specify that the next column begins
- from the first row with the help of the
- <code>breakBefore = "true"</code>
- .
- </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
+ <para> In order to group columns with text information into one
row, use the <emphasis>
+
<property>"colspan"</property>
+ </emphasis> attribute, which is similar to an HTML
one. In the
+ following example the third column contains 3 columns. In
addition,
+ it's necessary to specify that the next column
begins from
+ the first row with the help of the <code>breakBefore
=
+ "true"</code> .
</para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{columns.data1}" var="data">
<rich:column>
<h:outputText value="#{column.Item1}" />
@@ -261,7 +200,7 @@
...
]]></programlisting>
- <!--para>As a result the following structure is rendered:</para>
+ <!--para>As a result the following structure is
rendered:</para>
<figure>
<title><rich:column> modified with colspan and breakbefore
attributes</title>
<mediaobject>
@@ -271,21 +210,15 @@
</mediaobject>
</figure-->
- <para>
- The same way is used for
- <property>columns</property>
- grouping with the
- <emphasis>
- <property>"rowspan"</property>
- </emphasis>
- attribute that is similar to an HTML. The only thing to add
- in the example is an instruction to move onto the next row
- for each next after the second column.
- </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
+ <para> The same way is used for
<property>columns</property> grouping with the <emphasis>
+
<property>"rowspan"</property>
+ </emphasis> attribute that is similar to an HTML. The
only thing to
+ add in the example is an instruction to move onto the next
row for
+ each next after the second column. </para>
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
<rich:dataTable value="#{columns.data1}" var="data">
<rich:columns columns="2" rowspan="3">
<h:outputText value="#{data.str0}" />
@@ -303,7 +236,7 @@
...
]]></programlisting>
- <!--para>As a result:</para>
+ <!--para>As a result:</para>
<figure>
<title><rich:column> generated with rowspan
attribute</title>
<mediaobject>
@@ -312,198 +245,178 @@
</imageobject>
</mediaobject>
</figure-->
- <para>
- Information about sorting and filtering you can find
- <link linkend="sortAndFilter">here</link>
- .
- </para>
+ <note>
+ <title>Note:</title>
+ <para>
+ The <emphasis
role="bold"><property><rich:columns></property></emphasis>
tag is initialized during components tree building process.
+ This process precedes page rendering at
"Render Response" JSF phase.
+ To be rendered properly the component needs all
it variables to be initialized while the components tree is being building.
+ A
<emphasis>javax.servlet.jsp.JspTagException</emphasis> occurs if <emphasis
role="bold"><property><rich:columns></property></emphasis>
uses variables passed from other components, if these variables are initialized during
rendering.
+ Thus, when <emphasis
role="bold"><property><rich:columns></property></emphasis>
is asking for such variables they do not already exist.
+ Use
<property><c:forEach></property> JSP standard tag as workaround.
+ Compare two examples below.
+ </para>
+ <para>
+ This code calls the exception:
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<rich:dataTable value="#{bean.data}" var="var">
+ <rich:columns value="#{var.columns}">
+ ...
+ </rich:columns>
+</rich:dataTable>
+...
+]]></programlisting>
+ <para>
+ This code works properly:
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<c:forEach items="#{bean.data}" var="var">
+ <rich:columns value="#{var.columns}">
+ ...
+ </rich:columns>
+</c:forEach>
+...
+]]></programlisting>
+ </note>
+
+
+ <para> Information about sorting and filtering you can find
<link
+
linkend="sortAndFilter">here</link> . </para>
- </section>
+ </section>
- <section>
- <title>Look-and-Feel Customization</title>
+ <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><rich:columns></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><rich:columns></property>
- </emphasis>
- component
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Skin Parameters Redefinition</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><rich:columns></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><rich:columns></property>
+ </emphasis> component
</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Skin Parameters Redefinition</title>
- <para>
- Skin parameters redefinition for
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- are the same as for the
- <emphasis role="bold">
- <property><rich:dataTable></property>
- </emphasis>
- <link linkend="SPR">component</link>
- .
- </para>
- </section>
- <section>
- <title>Definition of Custom Style Classes</title>
+ <para> Skin parameters redefinition for <emphasis
role="bold">
+
<property><rich:columns></property>
+ </emphasis> are the same as for the <emphasis
role="bold">
+
<property><rich:dataTable></property>
+ </emphasis>
+ <link linkend="SPR">component</link>
. </para>
+ </section>
+ <section>
+ <title>Definition of Custom Style Classes</title>
- <para>
- Custom style classes for
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- are the same as for the
- <emphasis role="bold">
- <property><rich:dataTable></property>
- </emphasis>
- <link linkend="DofCCS">component</link>
- .
- </para>
+ <para> Custom style classes for <emphasis
role="bold">
+
<property><rich:columns></property>
+ </emphasis> are the same as for the <emphasis
role="bold">
+
<property><rich:dataTable></property>
+ </emphasis>
+ <link
linkend="DofCCS">component</link> . </para>
- <para>
- In order to redefine styles for all
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- components on a page using CSS, it's enough to create
- classes with the same names (possible classes could be found
- in the tables
- <link linkend="SPR">above</link>
- ) and define necessary properties in them.
- </para>
+ <para> In order to redefine styles for all <emphasis
role="bold">
+
<property><rich:columns></property>
+ </emphasis> components on a page using CSS,
it's enough to
+ create classes with the same names (possible classes could
be found in
+ the tables <link
linkend="SPR">above</link> ) and define necessary
+ properties in them. </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="CSS"><![CDATA[...
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="CSS"><![CDATA[...
.rich-table-subheadercell{
color: #a0a0a0;
}
...]]></programlisting>
- <para>This is a result:</para>
+ <para>This is a result:</para>
- <figure>
- <title>Redefinition styles with predefined classes</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/columns_pc.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <figure>
+ <title>Redefinition styles with predefined
classes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/columns_pc.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>
- In the example column header cells color was changed.
- </para>
+ <para> In the example column header cells color was changed.
</para>
- <para>
- Also it's possible to change styles of particular
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- component. In this case you should create own style classes
- and use them in corresponding
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- <emphasis>
- <property>styleClass</property>
- </emphasis>
- attributes. An example is placed below:
- </para>
+ <para> Also it's possible to change styles of
particular <emphasis
+ role="bold">
+
<property><rich:columns></property>
+ </emphasis> component. In this case you should create
own style
+ classes and use them in corresponding <emphasis
role="bold">
+
<property><rich:columns></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[...
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="CSS"><![CDATA[...
.myClass {
font-style: oblique;
}
...]]></programlisting>
- <para>
- The
- <emphasis>
- <property>"styleClass"</property>
- </emphasis>
- attribute for
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- is defined as it's shown in the example below:
- </para>
+ <para> The <emphasis>
+
<property>"styleClass"</property>
+ </emphasis> attribute for <emphasis
role="bold">
+
<property><rich:columns></property>
+ </emphasis> is defined as it's shown in the
example below: </para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[<rich:columns
styleClass="myClass">
+ <para>
+ <emphasis
role="bold">Example:</emphasis>
+ </para>
+ <programlisting
role="XML"><![CDATA[<rich:columns styleClass="myClass">
]]></programlisting>
- <para>This is a result:</para>
+ <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/columns_oc.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <figure>
+ <title> Redefinition styles with own classes and
<emphasis>
+
<property>styleClass</property>
+ </emphasis> attributes </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/columns_oc.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>
- As it could be seen on the picture above, the font style for
- columns was changed.
- </para>
- </section>
+ <para> As it could be seen on the picture above, the font style
for columns was
+ changed. </para>
+ </section>
- <section>
- <title>Relevant Resources Links</title>
- <para>
- <ulink
-
url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataTable.j...
- Here
- </ulink>
- you can found some additional information for
- <emphasis role="bold">
- <property><rich:columns></property>
- </emphasis>
- component usage.
- </para>
- </section>
-</section>
\ No newline at end of file
+ <section>
+ <title>Relevant Resources Links</title>
+ <para>
+ <ulink
+
url="http://livedemo.exadel.com/richfaces-demo/richfaces/dataTable.j...
+ > Here </ulink> you can found some
additional information
+ for <emphasis role="bold">
+
<property><rich:columns></property>
+ </emphasis> component usage. </para>
+ </section>
+</section>