README.md

Heihō

Quick spreadsheet viewer in vanilla JS

What it does ?

The heiho.js script is quick and simple spreadsheet viewer. It is meant to preview the contents of csv files inside your browser without needing any other tools. It uses plain vanilla javascript so it has no dependencies, but for the applied styling from the css file.

This is not a spreadsheet editor, this is a preview tool only.

How to use ?

Simply include both the javascript file and the css stylesheet in your HTML document. It's best if you put them at the bottom, close to the closing <\body> tag.

<link rel="stylesheet" href="/path/to/heiho.css" />
<script src="/path/to/heiho.js"></script>

Or include it via jsDelivr CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/kktsvetkov/heiho@latest/heiho.css" />
<script src="https://cdn.jsdelivr.net/gh/kktsvetkov/heiho@latest/heiho.js"></script>

Once included in your document, simply call Heiho() and pass the data as argument

var data = [ ['a', 'b', 'c'], [1,2,3], [4,5,6] ];
Heiho(data);

You can modify some of the output using a second argument that passes additional options

Heiho(data, {max:20}); // shows only 20 rows from data

Explore more cases in the examples section below.

Options

There is a small set of options used to influence the output of the spreadsheet preview.

• options.header is boolean value whether to style the first row in the
  preview differently; this meant to be used with CSV files, where the first row holds the column titles; default value is null which triggers an attempt to auto-detect whether the first row is header or not.

• options.max is an integer value that restricts how many rows to be included in the preview; you can use 0 to disable it, and its' default value is 100.

• options.title this is used to output the header title; you can use a string to just pass a text to be inserted there, or you can use a function that manipulates the HTML element that is the header title (look in the examples below)

• options.truncate is a function used to render the output in the "truncate" element of the preview; this element appears if the rows of the data previewed are more than options.max as an acknowledgement that the data was truncated (look in the examples below to see how this work)

Options are passed as a second argument to Heiho() function.

Heiho(data, { max: 20, title: 'proba.csv' });

You can add more elements to the options argument which you can later use in some of the functions inside it such as options.title and options.truncate.

Examples

Let's explore few examples of what you can do with Heihō

Title

You can modify what is rendered in the header title of the preview. The basic approach here is to just pass the title as a string in the options, like this:

Heiho(data, { title: 'users.csv' });

You can also do more with it if you pass a function as the title. In that case it will be executed to populate the contents of the header title will be. The arguments are the header title element, and the options used.

var file = {filename: 'Proba.csv', size: '123KB', created: '2009-08-21 14:01:36'}
Heiho(data, { title: function(el, o)
	{
		el.innerHTML = '<b>'
			+ file.filename + '<\/b> <code>'
			+ file.size + '<\/code> '
			+ file.created;
	}
});

Truncate

Similar to how options.title is used as a function, options.truncate is used to populate the contents of the "truncate" element (the warning shown when there are more rows to preview than the options.max restriction). This function gets more arguments:

/**
* @param {DomElement} el the truncate element
* @param {Integer} max
* @param {Array|Object} data data previewed
* @param {Object} o options
*/
options.truncate = function(el, max, data, o)
{
	el.innerHTML = 'Showing only first ' + max + ' rows';
	el.style.display = '';
}

Papa Parse

You can use the popular Papa Parse (github) library to parse CSV data inside your browser. You can use it together with Heihō to preview the result from the CSV parsing

Papa.parse(file, {
	complete: function(results) {
		Heiho(results.data);
	}
});

Explore all the examples on papaparse.com, they are a blast!

Here's an example of Papa Parse and Heiho previewing a remote csv file:

Papa.parse("http://example.com/file.csv", {
	download: true,
	complete: function(results) {
		Heiho(results.data);
	}
});