Home

html5csv.js

defines a single global object CSV

useful for defining operations on tabular or matrix data

CSV.begin(data, options)..middleware...go(finalCallback);

For begin and a tutorial, please see the README.md file on the main page

usage

can chain as many "middleware" calls as you like, go begins execution of the chain

CSV.begin(datasource)....middleware()....go(finalCallback);

can also create functions to call later, that represent the entire chained workflow

var handler = CSV.begin(datasource)....middleware()....finalize(finalCallback); // returns function


handler();  // same as using ....go(finalCallback)
// or maybe use it with jQuery. multiple calls to "handler()" are automatically debounced
$('#someButton').on('click', handler);

optional finalCallback(e,D)

If undefined, then finalCallback = function(e,D){ if(e) console.log(e); }

e is the error/exception string from CSV operations, or null for no error

D is an object supplied by CSV containing:

• the row data in D.rows
• perhaps meta data in D.meta

D will be null on error

currently defined middleware

###.save(csvName). saves data in browser local storage or by ajax push if shared.ajaxMapper is defined

###.download(csvFileName). reformats data rows to a csv file and pushes file out the browser, as if it were a download works on recent Chrome and Firefox

###.push(newrow,..., ). adds new rows to the internal data in shared.data.rows

###.hslice(beginRowNumber,endRowNumber). filters the dataset to only include rows that pass the filter the header is preserved as row 0

###.hslice(filterObject). always keeps the header row

filterObject = {colName1: [low,high], colName2: [low,high], ...} in the object, range restrictions on zero or more columns are defined.
You may set low or high to 'null' to obtain a one sided test.

or

filterObject = [ [low,high], [low,high], ..., [low,high] ] where in the array form the number of pairs must match the number of columns in the header row.

where colName1 is a string column name from the header row.

The default is to apply an inclusive range test, i.e. to test that low <= value && value <= high

If either low or high is null, the test becomes one sided. If low and high are the same value, then both are tests are performed and the result is an equality test.

###.appendCol(colName,coldataOrFunction, needRowPropsBoolean). appends a new column to all rows

###.table(divId,options,beginRowNumber,endRowNumber). creates an HTML table from the row data, first slicing on [beginRow, endRow)

###.editor(divId,headerBool,beginRowNumber,endRowNumber,precallback,onCellCallback). create an editor the editor is very basic and does not include adding or deleting rows

###.jqplot(plotSpecArray, afterCallback). create one or more plots. Calls optional afterCallback(plotsObject) after calling jqPlot

var plotSpecArray = [ [name1,pairs1,options1], ... ] // plotSpecArray is an array of triplets

name is a string giving the plot name, and is the key of the plotsObject returned to afterCallback

pairs1 is an Array of Pairs, as in

[['x','y'],['x','z']]

to put y vs x and z vs x on the same axes

options1 is an Object of jqplot options, passed directly to jqplot

To learn how to make specific plots, like bar plots vs lines vs points, see the jqPlot documentation.

###.ols(fitSpecArray).

Performs linear fitting via Ordinary Least Squares

###.call(customFunction). calls programmer defined customFunction(next) with this=shared and first parameter "next"

• Important style request -- In your function's first line, please use: var shared = this;
• The data rows are then in shared.data.rows
• The meta data, if any, is in shared.data.meta
• next(), the first parameter supplied to your customFunction, can be called to go to the next task.
  • If you forget to call next and just return, thats ok too.
  • If you need to defer the next task, e.g., for ajax, return 'defer'; from customFunction
• To skip future middleware on an error, simply throw "Oh No! My detailed error message goes here";

If you refine a call customFunction enough for reuse, it can be set up as an extension very easily.

defining extensions

CSV.extend(middlewareExtensions, sharedExtensions);

A simple middleware extension to numerically difference rows

var extension = {
    'diff':  function(){
        var shared = this; // pick up shared object from this, will be set internally by func.apply
        // the rows of data are in shared.data.rows
        // this code assumes shared.data.rows[0] is a header row, and later rows are numeric data  
        var newrows = [shared.data.rows[0].slice(0)]; // copy old header row
        var i,l,j,k,newrow,r0,r1;
        for(i=2,l=shared.data.rows.length;i<l;++i){
            newrow = [];
            r0 = shared.data.rows[i-1];
            r1 = shared.data.rows[i];
            for(j=0,k=r0.length;j<k;++j) newrow[j]=r1[j]-r0[j]
            newrows.push(newrow);
        }
        shared.data.rows = newrows;
    }
};

CSV.extend(extension); // attach to list of known middleware

CSV.begin(datasource)...diff()....go();  // diff should now work