Gridx in XPages – 27: Exporting to Excel

No application would be complete without the ability to export all of the data to Excel. In reality, this request still comes up a lot, so it’s a very handy feature that Gridx provides the ability to export the grid data. In this post, I’ll show what the exporter module provides, the easy way to send the data in CSV format, and how to tie the process together.

Gridx Series

Gridx in XPages — Entire Series

High Level Steps to Export

The Export module doesn’t really do the whole job for you; what it really does is provide you the data in CSV format and then you have to finish the job.

Here are the high-level steps that are required:

1. Include the Export module in the require statement
2. Write two functions to get the data to export, then open the page to write it out
3. Use a JSON RPC method to put that data into a scope variable
4. Open an XAgent page to actually write out the data
5. Add a button to call the JavaScript function to run the whole process

1. Including the Export Module

This module doesn’t get added to the grid, but it needs to be available in order to call from JavaScript.

Here’s the require statement from my sample page:

require([ 
  "gridx/Grid", 
  "dojo/store/Memory",
  "gridx/core/model/cache/Sync", 
  "gridx/modules/ColumnResizer",
  "gridx/modules/NestedSort", 
  "gridx/modules/Filter",
  "gridx/modules/filter/FilterBar",
  "gridx/modules/filter/QuickFilter",
  "gridx/modules/HiddenColumns", 
  "gridx/modules/Persist",
  "gridx/modules/HeaderMenu",
  "gridx/support/exporter/toCSV",
  "gridx/modules/VirtualVScroller",
  "gridx/modules/extendedSelect/Column",
  "gridx/modules/move/Column",
  "gridx/modules/dnd/Column",
  "dojo/date/locale",
  "dojo/currency",
  "gridx/modules/Bar",
  "dijit/Toolbar",
  "dijit/form/Button", 
  "dojo/domReady!" 
  ], 
  function(Grid, MemoryStore, Cache, ColumnResizer, NestedSort, Filter, FilterBar, QuickFilter, HiddenColumns, Persist, HeaderMenu, CSV_Export, VirtualVScroller, colSelect, colMove, colDnD, locale, currency, Bar, Toolbar, Button) {    

2. Functions to Retrieve Data and Write it Out

The first function uses the export module to prepare the data for export.

Note: it needs to be within the require() statement so the CSV_Export is within scope.

getGridData = function() { 
  var args = {
    selectedOnly: false,
    omitHeader: false,
    useStoreData: false,
    separator: ','
  };

  CSV_Export(grid, args).then(exportData);
};	

exportData() is a callback to run once the data is ready. (You can also pass in callbacks to run on error and as the export progresses, if you want to update a progress meter).

This function calls a JSON RPC method to put the data into a scope variable. When done, it opens a new window with an XAgent page to actually write out the data.

function exportData(data) {
    rpcExport.exportData(data).addCallback(function() {
    // Open the XAgent page to write out the data	
    window.open('ExportGridx.xsp');	
  })

3.JSON RPC method to put that data into a scope variable

JSON RPC ties everything together and coordinates the timing. When I first worked on exporting with the dojo EnhancedGrid, this was a sticking point, because there was sometimes a timing issue — the data wasn’t ready before the XAgent was opened, so I tried a few workarounds that weren’t always reliable.

With this method, the client-side JavaScript function passes in the data to export and the RPC method puts it into a scope variable so it can be picked up by the XAgent page. (Note: This control is available in the extension library, 8.5.3 Upgrade Pack 1, or Notes 9.)

<xe:jsonRpcService id="jsonRpcService1" serviceName="rpcExport">
  <xe:this.methods>
    <xe:remoteMethod name="exportData"
      script="sessionScope.gridxExport = csvData;">
      <xe:this.arguments>
        <xe:remoteMethodArg name="csvData" type="string"></xe:remoteMethodArg>
      </xe:this.arguments>
    </xe:remoteMethod>
  </xe:this.methods>
</xe:jsonRpcService>

On a callback that runs when the RPC method is done, the exportData() function opens the XAgent page. This makes the timing of the whole process flow smoothly.

(Note: if you’re not familiar with JSON RPC and you’ll be at ConnectED, check out my session with Paul Calhoun [BP105], where we’ll dig into the benfits of it.)

4. XAgent to Export Data

Once the data is ready, the code opens a separate window for an XAgent page. The page has rendered set to false and it runs code on afterRenderResponse to write out the data from the scope variable.

If you have Excel installed, you will have the opportunity to open the file directly in Excel. (You can also save it to the machine.)

Here is the entire source of my XAgent page:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core" rendered="false">

	<xp:this.afterRenderResponse><![CDATA[#{javascript:
// This XAgent just writes out the CSV data from the grid that is stored in a scope variable.
var exCon = facesContext.getExternalContext();
var writer = facesContext.getResponseWriter();
var response = exCon.getResponse();
response.setContentType("text/csv;charset=utf-8");
 
response.setHeader("Cache-Control", "no-cache");
response.setHeader("Content-Disposition", "attachment; filename=GridExport.csv");
writer.write(sessionScope.gridxExport);
writer.endDocument();}
]]>
	</xp:this.afterRenderResponse>
</xp:view>

5. Button to Run the Export

Finally, we just need a button to call the exportGridData() function.

<xp:button value="Export" id="button1">
  <xp:eventHandler event="onclick" submit="false">
    <xp:this.script><![CDATA[getGridData();]]></xp:this.script>
  </xp:eventHandler>
</xp:button>

Here’s an example of grid data:

Here’s the default layout in Excel after exporting:

Enhancements

In its current form, it will export everything visible in the grid. (If the grid is filtered, it will export the results of the filter.)

There are several things you can do to enhance the process:

• Export selected rows only
• Put the button to export the data into a toolbar
• Add formatters to modify the data as it’s exported
• Use Apache POI to write a proper Excel spreadsheet