changes.
| | h2. 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. |
| | |
| | {tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=dataExporterBean] of this component, complete with source code.{tip} |
| | |
| | |
| | h2. 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. |
| | |
| | {panel} |
| | {code:xml|borderStyle=dashed}<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> |
| | {code} |
| | {panel}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 />}}. |
| | |
| | {panel} |
| | {code:xml|borderStyle=dashed}<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> |
| | {code} |
| | {panel}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. |
| | |
| | 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://www.icefaces.org/docs/v4_latest/ace/tld/ace/dataExporter.html].{tip}The supported attributes are the following: |
| | |
| | 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. |
| | |
| | h2. Client Behavior Events |
| | |
| | | action | Fired when the button is clicked or pressed by any other means. | |
| | |
| | {tip}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.{tip} |
| | |
| | h2. JavaScript APIs |
| | |
| |  | 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. |
| | | h4. ICEfaces 3.x |
| | |
 | | The client side component object is exposed through the global variable name specified in the *widgetVar* attribute. |
| | |
| | h4. 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. |
| | |
| | {code}var widget = ice.ace.instance('frm:componentId);{code} |
| | |
| | {tip}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">_).{tip} |
| | |
| | {info}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. |
| | {info} |
| | |
| | {info}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.{info} |
| | |
| | h2. Keyboard and ARIA Support |
| | |
| | The following ARIA roles are supported: button. |
| | |
| | h2. CSS Classes |
| | |
| | The following markup represents the basic HTML structure of the component and the CSS classes it uses. |
| | |
| | {code:xml} |
| | <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> |
| | {code} |
| | |
| | h2. Known Issues |
| | |
| | None. |
| | |
| | h2. 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. |
| | |
| | {tip}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.{tip} |
| | {tip}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. For your convenience the POI library is included in the ICEfaces distribution bundles under the icefaces/lib/ace directory. |
| | | |
| | {tip}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. |
| | {tip} |
DataExporter