dojox.grid.EnhancedGrid.plugins.Exporter ¶

Authors:	Zhu Xiao Wen
Project owner:	Nathan Toone
Available:	since V.1.6

Exporter plugin provides functions to export the grid data into a given format.

Contents

dojox.grid.EnhancedGrid.plugins.Exporter

Introduction ¶

Exporter is a plugin for dojox.grid.EnhancedGrid. It is designed as a framework to help implement various export formats for grid, e.g. CSV, HTML table, MS Excel, odt etc. The plugin itself does not export anything, it only goes through the grid row by row calling the implementation’s interface. It’s the implementation’s responsibility to transform the grid content to some desired format. The following of this document first describes how to use the export functions of some existing implementations. And then introduces the API of this framework in detail.

<script type="text/javascript" src="{{ baseUrl }}dojox/grid/tests/enhanced/support/test_write_store_music.js"></script>
<script type="text/javascript">
        dojo.require("dojox.grid.EnhancedGrid");
        dojo.require("dojox.grid.enhanced.plugins.exporter.CSVWriter");

        function exportAll(){
                dijit.byId("grid").exportGrid("csv", function(str){
                        dojo.byId("output").value = str;
                });
        };
        function exportSelected(){
                var str = dijit.byId("grid").exportSelected("csv");
                dojo.byId("output").value = str;
        };

        dojo.addOnLoad(function(){
                //See the ItemFileWriteStore defined in test_write_store_music.js
                var store = test_store[0];

                var layout = [
                        { field: "id"},
                        { field: "Genre"},
                        { field: "Artist"},
                        { field: "Album"},
                        { field: "Name"},
                        { field: "Track"},
                        { field: "Download Date"},
                        { field: "Last Played"}
                ];

                var grid = new dojox.grid.EnhancedGrid({
                        id: 'grid',
                        store: store,
                        structure: layout,
                        plugins: {
                                exporter: true
                        }
                });
                grid.placeAt('gridContainer');
                grid.startup();
        });
</script>

dojo.addOnLoad(function(){
                //See the ItemFileWriteStore defined in test_write_store_music.js
                var store = test_store[0];

var layout = [
                        { field: "id"},
                        { field: "Genre"},
                        { field: "Artist"},
                        { field: "Album"},
                        { field: "Name"},
                        { field: "Track"},
                        { field: "Download Date"},
                        { field: "Last Played"}
                ];

var grid = new dojox.grid.EnhancedGrid({
                        id: 'grid',
                        store: store,
                        structure: layout,
                        plugins: {
                                exporter: true
                        }
                });
                grid.placeAt('gridContainer');
                grid.startup();
        });
</script>

<div id="gridContainer"></div>
<button onclick="exportAll()">Export all to CSV</button>
<button onclick="exportSelected()">Export Selected Rows to CSV</button>
<br />
<textarea id="output"></textarea>

<style type="text/css">
@import "{{ baseUrl }}dojo/resources/dojo.css";
@import "{{ baseUrl }}dijit/themes/{{ theme }}/{{ theme }}.css";
@import "{{ baseUrl }}dijit/themes/{{ theme }}/document.css";
@import "{{ baseUrl }}dojox/grid/enhanced/resources/{{ theme }}/EnhancedGrid.css";
@import "{{ baseUrl }}dojox/grid/enhanced/resources/EnhancedGrid_rtl.css";

    #output{
            width: 100%;
            height: 150px;
    }
    #gridContainer{
            width: 100%;
            height: 250px;
    }
</style>

Configuration ¶

Prerequisites¶

This exporter plugin is only available for EnhancedGrid. So require the EnhancedGrid first:

dojo.require("dojox.grid.EnhancedGrid");

Unlike other grid plugins, you don't need to require this plugins directly. Instead, you should require the specific implementations (i.e. writers). For example, if a CSV format implementation is available, then:

dojo.require("dojox.grid.enhanced.plugins.exporter.CSVWriter");

This statement will automatically require "dojox.grid.enhanced.plugins.Exporter".

Plugin Declaration¶

The declaration name of this plugin is exporter . It is declared in the plugins property of grid.

If your grid is created declaratively:

<div id="grid" dojoType="dojox.grid.EnhancedGrid"
  store="mystore" structure="mystructure"
  plugins="{
    exporter: true
}" ></div>

If your grid is created in JavaScript:

var grid = new dojox.grid.EnhancedGrid({
  id:"grid",
  store:"mystore",
  structure:"mystructure",
  plugins:{
    exporter: true
  }
});

This plugin does not have any arguments.

Usage ¶

When this plugin is enabled, the following 2 methods are available for a grid widget:

exportGrid(type, args, onExported):: Export required rows(args.fetchArgs) to a kind of format(type), using the corresponding writer with given arguments(args.writerArgs), then pass the exported text to a given function(onExported).

Arguments	Type	Optional/Mandatory	Description
type	String	Mandatory	A registered export format name.
args	Object	Optional(default to {})	An argument to define fetchArgs and writerArgs like: { fetchArgs: {...}, writerArgs: {...} } fetchArgs is some arguments for store.fetch. writerArgs is some arguments for the current wirter.
onExported	function(string)	Mandatory	Call back function when export result is ready.

exportSelected(type, writerArgs):: Export only the selected rows of a grid to the specified format. Returns the exported string.

Arguments	Type	Optional/Mandatory	Description
type	String	Mandatory	A registered export format name.
writerArgs	Object	Optional(default to {})	Some arguments for the current wirter.

For example:

//Export the whole grid to CSV format, with separator of ":".
grid.exportGrid("csv", {writerArgs: {separator:":"}}, function(str){
  // do something interesting with str
});
//Export the first 10 rows to CSV format.
grid.exportGrid("csv", {fetchArgs: {start: 0, count: 10}}, function(str){
  // do something interesting with str
});
//Only export the selected rows to CSV format.
var str = grid.exportSelected("csv", {separator:":"});

Create Export Writer -- A Framework for Grid Export ¶

To create your own exporter, you should use this export framework by extending an abstract class: _ExportWriter.

_ExportWriter – The Base Class¶

This is an abstract class for all of the writers used in the Exporter plugin. It applies the strategy pattern to break the export work into several stages, and provides interfaces for all of them. Implementations might choose to override some of the functions in this class thus providing their own functionality. The Exporter will go through the grid row by row. In every row, all the Views will be reached and the header row is only handled once. The APIs exposed by this class to implementors is shown below. You can implement them by extending "dojox.grid.enhanced.plugins.exporter._ExportWriter".

beforeHeader(grid):: We are going to start moving through the grid. Is there anything we should do now?

Arguments	Type	Description
grid	dojox.grid.EnhancedGrid	The grid widget.
[return]	Boolean	true: go on handling the header row and then call afterHeader. false: skip the header row, won't call afterHeader.

afterHeader():: The header has been handled.
beforeContent(items):: We are ready to go through all the contents(items).

Arguments	Type	Description
items	Array	All the items fetched from the store.
[return]	Boolean	true: go on handling the contents and then call afterContent. false: skip all the contents, won't call afterContent.

afterContent():: We have finished the entire grid travel. Do some clean up work if you need to.
beforeContentRow(argObj):: Before handling a line of data (not a header).

Arguments	Type	Description
argObj	Object	An object with at least the following context properties available: { grid, isHeader, row,rowIdx, spCols }
[return]	Boolean	true: go on handling the current data row and then call afterContentRow. false: skip the current data row, won't call afterContentRow.

afterContentRow(argObj):: After handling a line of data (not header).

Arguments	Type	Description
argObj	Object	An object with at least the following context properties available: { grid, isHeader, row,rowIdx, spCols }

beforeView(argObj):: Before handling a view.

Arguments	Type	Description
argObj	Object	An object with at least the following context properties available: { grid, isHeader, row, rowIdx, spCols }
[return]	Boolean	true: go on handling the current view and then call afterView. false: skip the current view, won't call afterView.

afterView(argObj):: After handling a view.

Arguments	Type	Description
argObj	Object	An object with at least the following context properties available: { grid, isHeader, row, rowIdx, spCols }

beforeSubrow(argObj):: Before handling a subrow (defined in the grid structure as "rows").

argObj	Object	An object with at least the following context properties available: { grid, isHeader, row, rowIdx, view, viewIdx, subrow, subrowIdx, spCols }
[return]	Boolean	true: go on handling the current subrow and then call afterSubrow. false: skip the current subrow, won't call afterSubrow.

afterSubrow(argObj):: After handling a subrow (defined in the grid structure as "rows").

Arguments	Type	Description
argObj	Object	An object with at least the following context properties available: { grid, isHeader, row, rowIdx, view, viewIdx, subrow, subrowIdx, spCols }

handleCell(argObj):: Handle a header cell or data cell.

Arguments	Type	Description
argObj	Object	An object with at least the following context properties available: { grid, isHeader, row, rowIdx, view, viewIdx, subrow,subrowIdx, cell, cellIdx, spCols, colOffset }

toString():: Export to a string.

Arguments	Type	Description
[return]	String	The exported result string.

The argument argObj represents the context of each function when they are called and may have the following properties:

Name	Data Type	When Available	Description
grid	dojox.grid.EnhancedGrid	Always	The grid widget we are now handling.
isHeader	Boolean	Always	Indicating which context we're handling, header or content.
view	dojox.grid._View	beforeView afterView beforeSubrow afterSubrow handleCell	Reference to the current _View object.
viewIdx	Integer	beforeView afterView beforeSubrow afterSubrow handleCell	The index of the current _View object in the views array. If the grid does not have any rowselector view, it conforms to the index in the _ViewManager.views.
row	data item	beforeContentRow afterContentRow beforeSubrow afterSubrow handleCell	The current row of data (logically), a.k.a.: current item.
rowIdx	Integer	beforeContentRow afterContentRow beforeSubrow afterSubrow handleCell	The index of the current row (item).
subrow	dojox.grid.cells._base[]	beforeSubrow afterSubrow handleCell	Reference to the current subrow. A subrow describe the innter structure of a row in a view, it's an array of cells
subrowIdx	Integer	beforeSubrow afterSubrow handleCell	The index of the current subrow in the subrow array: _View.structure.cells.
cell	dojox.grid.cells._base	handleCell	Reference to the current cell.
cellIdx	Integer	handleCell	The index of the current cell in the current subrow. It's different from cell.index, which is the index in the whole line.
spCols	Integer[]	beforeContentRow afterContentRow beforeView afterView beforeSubrow afterSubrow handleCell	The header line has been handled. An array of special column indexes(flat,not regarding structure). Special columns are typically attached to grid as a kind of UI facility by the grid widget, instead of some real data. For example: indirect selectors and row indexers. Users can choose to export it or not.
colOffset	Integer	handleCell	If the grid has a _RowSelector view or something else, this view will NOT be passed to the user in argObj. So the column index (cell.index) will appear shifted (start from 1 instead of 0). This colOffset is provided to remove this shift.

Register Your Own Writer¶

Once you have implemented your own export writer, tell the framework about the name of your format. For the "CSV" case, you should write the following line in your implementation file:

dojox.grid.enhanced.plugins.Exporter.registerWriter("csv", "dojox.grid.enhanced.plugins.exporter.CSVWriter");

Available Export Writers¶

The following writers are currently available in the dojox/grid/enhanced/plugins/exporter package:

Writer Class	Format Name	Writer Argument
CSVWriter	"csv"	"separator"
TableWriter	"table"	HTML table attributes

Example¶

Here is the structure of the implementation file of the CSVWriter, demonstrating how to write an export writer. It only implements 3 interfaces.

//First delcare your class.
dojo.provide("dojox.grid.enhanced.plugins.exporter.CSVWriter");

//Require the base class.
dojo.require("dojox.grid.enhanced.plugins.exporter._ExportWriter");

//Register the CSV format name.
dojox.grid.enhanced.plugins.Exporter.registerWriter("csv",
  "dojox.grid.enhanced.plugins.exporter.CSVWriter");

//Extend from the base class.
dojo.declare("dojox.grid.enhanced.plugins.exporter.CSVWriter",
dojox.grid.enhanced.plugins.exporter._ExportWriter,{
  //Separator is the only argument.
  _separator: ',',

  constructor: function(/* object? */writerArgs){
    //Handle arguments (separator in this case), and do some initialization here.
  },

  _formatCSVCell: function(/* string */cellValue){
    //Format cell value to follow CSV standard.
    //See: http://en.wikipedia.org/wiki/Comma-separated_values
  },

  beforeContentRow: function(/* object */argObj){
    //Overrided from _ExportWriter
    //For each column,
    //        get the cell data of the current row, and format them with _formatCSVCell
    //Join these cell data together with the separater.
    //Save the result.
    //return false, because we don't need to go into the row. Thus improves the performance.
  },

  handleCell: function(/* object */arg_obj){
    // summary:
    //                Overrided from _ExportWriter
    //Check if arg_obj.isHeader is true. We have already handled content cells in the above function,
    //here we only need to deal with the header cells.
    //You can get the header name by arg_obj.cell.name.
  },

  toString: function(){
    //Overrided from _ExportWriter
    //Join all the saved result together and return.
  }
});

dojox.grid.EnhancedGrid.plugins.Exporter ¶

Introduction ¶

Configuration ¶

Prerequisites¶

Plugin Declaration¶

Usage ¶

Create Export Writer -- A Framework for Grid Export ¶

_ExportWriter – The Base Class¶

Register Your Own Writer¶

Available Export Writers¶

Example¶

See Also ¶

Table of Contents

dojox.grid.EnhancedGrid.plugins.Exporter¶

Introduction¶

Configuration¶

Prerequisites¶

Plugin Declaration¶

Usage¶

Create Export Writer -- A Framework for Grid Export¶

_ExportWriter – The Base Class¶

Register Your Own Writer¶

Available Export Writers¶

Example¶

See Also¶

Table of Contents

dojox.grid.EnhancedGrid.plugins.Exporter ¶

Introduction ¶

Configuration ¶

Usage ¶

Create Export Writer -- A Framework for Grid Export ¶

See Also ¶