DataExporter

Overview

Since 3.0

The data exporter is a utility component that exports data from a datatable and serves it as a file in Excel, PDF, XML or CSV format. This component renders an HTML button element. More components and HTML elements can be nested inside this tag to give a different look and feel to the button.

When the button is clicked, a file is generated with the requested data, and a new JSF Resource is created to serve that file. The URL to that Resource is then sent to the client, which automatically loads the file on the same page, without navigating away from it and without disturbing its state.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

The data exporter has three required attributes: target, the id of the table to export; type the file format, and fileName the name of the file (not including its extension). The following is an example of the basic usage.

<ace:dataExporter type="csv" target="myTable" fileName="tableData"/>

<ace:dataTable id="myTable" value="#{bean.items}" var="item">
	<ace:column headerText="Column One">
		<h:outputText value="#{item.propertyA}"/>
	</ace:column>
	<ace:column headerText="Column Two">
		<h:outputText value="#{item.propertyB}"/>
	</ace:column>
</ace:dataTable>

If one wishes to prevent certain data to be exported in the file, one can add the <ace:excludeFromExport /> tag inside the component one wants to avoid exporting. If this tag is placed inside <ace:column>, <ace:row>, or <ace:columnGroup> it will prevent the entire column, row or column group from being exported. The following is an example of <ace:excludeFromExport />.

<ace:dataExporter type="csv" target="myTable" fileName="tableData"/>

<ace:dataTable id="myTable" value="#{bean.items}" var="item">
	<ace:column headerText="Column One">
		<ace:excludeFromExport />
		<h:outputText value="#{item.propertyA}"/>
	</ace:column>
	<ace:column headerText="Column Two">
		<h:outputText value="#{item.propertyB}"/>
		<h:outputText value="#{item.propertyC}">
			<ace:excludeFromExport />
		</h:outputText>
	</ace:column>
</ace:dataTable>

If a table is using stacked columns, it won't affect the results of the exporting action. The data exporter is unaware of stacked columns.

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.

The pageOnly attribute exports only the current page being displayed in the table, when using pagination.

The excludeColumns attribute accepts a comma-separated list of column indexes (zero-relative) to be excluded from the exporting. This is an additional method of excluding columns to the <ace:excludeFromExporting> tag described above. It can be modified dynamically.

The userColumnOrder attribute is used to specify whether the columns should be exported according to the order established by the user in the client or according to the order in which the columns appear in the facelet.

In the case of xls and pdf formats, one can use the preProcessor and postProcessor attributes to specify a method that will be invoked before or after the exporting, so that a developer can modify the document being delivered. The method specified must accept an argument of type com.lowagie.text.Document in the case of the pdf format, and an argument of type org.apache.poi.ss.usermodel.Workbook in the case of the xls format.

The encoding attribute is used to specify the character encoding to use. The default value is UTF-8.

The includeHeaders and includeFooters boolean attributes are used to specify whether the column headers and column footers are included in the exported file, respectively.

If the selectedRowsOnly attribute is set to true, only the selected rows in the table will be included in the exported file. This doesn't work in conjunction with the pageOnly attribute. All selected rows in the entire table in all pages will be included in the exported file.

The style and styleClass attributes are passed thru to the style and class attributes of the root HTML button.

Client Behavior Events

Prior to 4.0 this event was named "activate". The "activate" event name is now deprecated but treated as an alias for "action" for backwards compatibility with existing applications.

JavaScript APIs

ICEfaces 3.x

The client side component object is exposed through the global variable name specified in the widgetVar attribute.

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.

The generated file is loaded on the page via a hidden <iframe>, so the download begins right there on the page, shortly after clicking the button, and without interfering with the state of the page. In IE7 this mechanism isn't supported, instead a new pop-up window is open and the file is loaded there.

Keyboard and ARIA Support

The following ARIA roles are supported: button.

CSS Classes

The following markup represents the basic HTML structure of the component and the CSS classes it uses.

<button class="[user defined classes] ui-button ui-widget ui-state-default ui-corner-all ui-button-text-only" style="[user defined styles]">
	<span class="ui-button-text">
		<span>Label</span>
	</span>
</button>

Known Issues

None.

Other Notes

• The generated file is served as a JSF Resource. This Resource object stays in memory for the duration of the session. The actual bytes of the generated file will be removed from memory when the file is finally downloaded by the user, so that it doesn't take memory space once it has been consumed.

• Note that content under an ace:panelExpansion section won't be exported, whereas child rows rendered via ace:rowExpansion are exported.

In order to support exporting files in PDF format, the iText library version 2.1.7 (itext-2.1.7.jar) must be in the classpath of the application, typically in the WEB-INF/lib folder. For licensing reasons, the iText library is not included in the ICEfaces distribution bundles. Also note that if the itext jar is copied into the icefaces/lib/ace directory, it will be included in the showcase sample application (showcase.war) when it is built using ant.

Up to the 4.2 release, to support exporting files in Excel format, the Apache POI library version 3.7 (poi-3.7.jar) must be in the classpath of the application, typically in the WEB-INF/lib folder. After the 4.2 release, the Apache POI library version 3.9 (poi-3.9.jar) must be in the classpath of the application. If you are using preprocessor and/or postprocessor methods, you might also need the Apache Commons Codec library (commons-codec-1.5.jar). If you want to suport the XLSX format, the following libraries have to be in the classpath of your application: Dom4j (dom4j-1.6.1.jar). POI OOXML (poi-ooxml-3.9.jar). POI OOXML Schemas (poi-ooxml-schemas-3.9.jar). Apache XML Beans (xmlbeans-2.6.0.jar). For your convenience the POI library and all other dependencies are included in the ICEfaces distribution bundles under the icefaces/lib/ace directory.