Dashboard

Overview

Since 4.3

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.

Getting Started

In its simplest form, an ace:dashboard component can be defined as follows.

        <h:form id="form">
		<ace:dashboard id="dashboard" maxColumns="3" resizable="true" draggable="true">
			<ace:dashboardPane headerText="One">
				<h:outputText value="Pane one content." />
			</ace:dashboardPane>
			<ace:dashboardPane headerText="Two">
				<h:outputText value="Pane two content." />
			</ace:dashboardPane>
			<ace:dashboardPane headerText="Three">
				<h:outputText value="Pane three content." />
			</ace:dashboardPane>
		</ace:dashboard>
        </h:form>

Attributes

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.

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.

JavaScript APIs

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

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">).

This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

Keyboard and ARIA Support

Not supported at the moment.

Known Issues

An ace:dashboard component inside an ace:tabSet is not displaying properly at the moment.

Observations and Tips

The underlying Javascript library (gridster.js) doesn't support more than 15 rows in the dashboard. Additional panes that cannot fit in that number of rows will not render nor work properly. However, the number of columns per row can be a big number, so plenty of panes can fit in the dashboard.

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.