The ace:dashboard component is a component that contains ace:dashboardPane's that can contain arbitrary content and are resizable, draggable and closable. The panes are arranged in a grid with fixed base dimensions (in pixels), and they can span multiple rows and/or columns in the grid, as specified or as modified by the user.
|See the ICEfaces Showcase Live Demo of this component, complete with source code.|
In its simplest form, an ace:dashboard component can be defined as follows.
<ace:dashboard id="dashboard" maxColumns="3" resizable="true" draggable="true">
<h:outputText value="Pane one content." />
<h:outputText value="Pane two content." />
<h:outputText value="Pane three content." />
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.
Here are some general configuration options of the dashboard. A lot of the configuration is done on the ace:dashboardPane components.
maxColumns The maximum number of columns to allow in the dashboard. Valid values range from 1 to 100. Any other value will be treated as 100.
paneWidth The base/minimum width of the panes in pixels, which determines the column width as well. This value can be multiplied by the pane's 'sizeX' property.
paneHeight The base/minimum height of the panes in pixels, which determines the row height as well. This value can be multiplied by the pane's 'sizeY' property.
resizable Specifies whether the panes are resizable or not.
draggable Specifies whether the panes are draggable or not.
Client Behavior Events
The ajax events are defined on the ace:dashboardPane component.
var widget = ice.ace.instance('frm:componentId);
|The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).|
Keyboard and ARIA Support
Not supported at the moment.
An ace:dashboard component inside an ace:tabSet is not displaying properly at the moment.
Observations and Tips
The size and position attributes of all the panes in the dashboard (row, column, sizeX, and sizeY) are automatically updated on the server at each request (as long as the ace:dashboard component is executed). This is so to maintain consistency of the size and position states between the client and the server. Often times resizing or dragging a dashboard pane will move other panes, indirectly, and this new state has to be communicated to the server at some point, in order to properly render the component and the panes in subsequent requests. So, the values of these attributes mentioned at the beginning will automatically change in the server across requests.
If you intend to make programmatic changes to the dashboard on certain user interactions, make sure to execute the entire dashboard in the request that will perform a programmatic change, so that the client communicates all the current state information to the server.