View Source

h2. Overview
_Since 3.0_

The _ace:tableConfigPanel_ component enables the user to adjust the state of several column attributes through a convenient, ready-made interface. The component renders the controls on a hidden panel launched by a button, whose location is defined by the 'type' attribute.

{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=tableConfigPanelBean] of this component, complete with source code.{tip}

h2. Getting Started
{code:xml}
<ace:tableConfigPanel id="tableConfig"
for="carTable"
columnNameConfigurable="true"
columnVisibilityConfigurable="true"
columnOrderingConfigurable="true"
columnSortingConfigurable="true"
type="last-col"/>

<ace:dataTable id="carTable"
value="#{dataTableSort.carsData}"
var="car"
rows="10">
<ace:column headerText="ID">
#{car.id}
</ace:column>
<ace:column headerText="Name" sortBy="#{car.name}">
#{car.name}
</ace:column>
<ace:column headerText="Chassis" sortBy="#{car.chassis}">
#{car.chassis}
</ace:column>
<ace:column headerText="Weight" sortBy="#{car.weight}">
#{car.weight}lbs.
</ace:column>
<ace:column headerText="MPG" sortBy="#{car.mpg}">
#{car.mpg}
</ace:column>
</ace:dataTable>
{code}


h2. Attributes

{tip:title=TagLib Documentation}This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available [here|http://res.icesoft.org/docs/v4_latest/ace/tld/ace/tableConfigPanel.html].{tip}

{panel}
The *columnOrderingConfigurable* attribute enables the editing of column order on the TableConfigPanel. Default is false.
{panel}

{panel}
The *columnVisibilityConfigurable* attribute enables the editing of column visibility on the TableConfigPanel. Default is false.
{panel}

{panel}
The *columnNameConfigurable* attribute enables the editing of column name on the TableConfigPanel. Default is false.
{panel}

{panel}
The *columnSortingConfigurable* attribute enables the editing of table sorting on the TableConfigPanel. Default is false.
{panel}

{panel}
The *hideDisabledRows* attribute enables the hiding of Columns with the 'configurable' attribute set to false, from the TableConfigPanel. Normally the disabled columns are just rendered with a disabled state. Default is false.
{panel}

{panel}
The *type* attribute controls the placement of the button used to open the TableConfigPanel.
Options are *first-col* (left-most column, of the top-most row of a multi-row header), *last-col* (right-most column, of the bottom-most row of a multi-row header), *in-col-left* (to the left of the label of the specified column id), and *in-col-right* (to the right of the label of the specified column id).
{panel}

{panel}
The *inColumnId* the id of the column where the launcher button is placed when using the types *in-col-left* and *in-col-right*.
{panel}

{tip}It's also possible to specify in {{ace:column}} the attributes *columnOrderingConfigurable*, *columnVisibilityConfigurable*, *columnNameConfigurable*, and *columnSortingConfigurable*, which apply specifically o that column, when more control is desired over each column's configurability.
{tip}

h2. Client Behavior Events

| open | Fired when the table config panel is opened by click its launch button. |
| submit | Fired when the table config panel submits, either by clicking the launch button again or clicking the checkmark button on the panel. (default event) |
| cancel | Fired when the table config panel closes by clicking the 'x' button table config panel. |

h2. Javascript API

The show() function is available to display the panel using a separate button or link. It works by first retrieving the table config object via ice.ace.instance(clientId) and the calling .show() on it, as in the following example.

{code:xml}
<h:commandButton value="Show panel" onclick="ice.ace.instance('carForm:carTable:tableConfig').show();return false;" />
{code}

h2. Keyboard Support

Sorting on the TableConfigPanel is keyboard configurable.
|| Keypress || Result ||
| Enter/Space Key | Begin new sort in selected direction. |
| Meta Key + Enter/Space Key | Add column to current sort in selected direction. |

h2. Positioning

This component offers positioning options for both the launcher button and the panel itself. The position of the launcher button can be specified with the *type* and *onColumnId* attributes. The position of the panel itself can be specified with the *offsetLeft* and *offsetTop* attributes.

When the type is *first-col*, the launcher is rendered in the left-most column of the top-most row of a multi-row header; when it's *last-col*, the launcher is rendered in right-most column of the bottom-most row of a multi-row header; when the type is *in-col-left* or *in-call-right*, the launcher is rendered to the left or right, respectively, of the label of the column specified by *inColumnId*.

Once the launcher is clicked, the panel will be opened at the center of the viewport, unless the *offsetLeft* and/or *offsetTop* attributes are specified, which indicate values in pixels from its container, which is usually the document itself.

When *modal* is set to true, a gray overlay that covers the whole page is displayed behind the panel, and interaction with anything behind it is disabled.

Example:
{code:xml}
<ace:dataTable id="carTable"
value="#{tableConfigPanelBean.carsData}"
var="car">
<ace:tableConfigPanel id="tableConfig"
modal="true" offsetLeft="200" offsetTop="100"
type="in-col-left" inColumnId="secondCol">
</ace:tableConfigPanel>
<ace:column id="firstCol" headerText="ID">
#{car.id}
</ace:column>
<ace:column id="secondCol" headerText="Name">
#{car.name}
</ace:column>
<ace:column id="thirdCol" headerText="Chassis">
#{car.chassis}
</ace:column>
</ace:dataTable>
{code}