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.|
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.One can use the label attribute to change the label of the rendered button, otherwise the default value is Export. Also, one can nest other components or HTML markup inside the data exporter tag to modify the look and feel of the button. In this case, the label will be rendered before all other components and markup, but only if it was explicitly specified (i.e. the default label value won't be rendered if there are nested items).
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 />.The code above will prevent the entire first column from being exported, and for the second column, only property B will be exported.
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.
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.
|action||Fired when the button is clicked or pressed by any other means.|
|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.|
The client side component object is exposed through the global variable name specified in the widgetVar attribute.
|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">).|
|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.|
The following ARIA roles are supported: button.
The following markup represents the basic HTML structure of the component and the CSS classes it uses.
- 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
For your convenience the POI library and all other dependencies are included in the ICEfaces distribution bundles under the icefaces/lib/ace directory.