csonv.js

A tiny library to fetch CSV data like JSON

Introduction

Simplicity within web development is searching its way towards the client-side. With the power of Javascript, we are able to get further and further. A great example is DocumentCloud’s Backbone.js and Alex MacCaw’s Spine. Not only do they provide a lot of great features, but they are also compact (3.9kb and 2K respectively when compressed) and it’s installation (including the hosting system) is just a matter of copying the Javascript sources. So there is no need to install any server-side scripting software whatsoever.

With keeping simplicity in mind, I have created csonv.js which serves CSV data like JSON. I have chosen CSV because it’s very straightforward:

• a file represents a certain entity (equivalent to database tables)
• the CSV format is far less complex than the XML format
• CSV files consists of columns and rows which resembles attributes and records respectively
• there is no need to install extra software on the hosting server (unlike MySQL or SQLite databases)

I am aware that there are a couple of cons regarding this setup. But as I am a passionate Ruby and Javascript programmer, I have build this for sake of fun and exploring side-steps like this one! ^^

Installation

Just include csonv.js:

  <script src="path/to/csonv.js" type="text/javascript"></script>

Note: include csonv.min.js for the minified csonv.js library

Usage

Providing the CSV data

Requirements

Make sure you have hosted the CSV files on a public location. A CSV file has to satisfy the following:

• the first row has to contain keys – equivalent to attribute names
• the second row has to describe the value types – equivalent to data types
• the following rows have to represent the entries – equivalent to records

The data types available are:

• string or an array of strings
• integer or an array of integers
• float or an array of floats
• boolean or an array of booleans (options are: <empty>, 0 or 1)

There are two separators which csonv.js handles:

• Csonv.separators.column (default: ";") – Used to separate columns
• Csonv.separators.array (default: ",") – Used to separate array values

An example

  id;first_name;last_name;given_names;is_parent
  integer;string;string;strings;boolean
  1;Dirk;Engel;Dirk,Julius;1
  2;Anna;Engel;Anna,Octovina;1
  3;Bram;Engel;Abraham,Theofilus;0
  4;Paul;Engel;Paulus,Mathijs;

Fetching CSV as Javascript objects

There are two ways to fetch CSV data as objects. Let’s say you want to fetch all the family members from (the relative path) assets/family.csv:

Using String.toObjects()

  <script>
    var members = "assets/family.csv".toObjects();
  </script>

Using Csonv.fetch(url)

  <script>
    var members = Csonv.fetch("assets/family.csv");
  </script>

The resulted objects

When running JSON.stringify(members, null, 2), you get the following JSON string:

[
  {
    "id": 1,
    "first_name": "Dirk",
    "last_name": "Engel",
    "given_names": [
      "Dirk",
      "Julius"
    ],
    "is_parent": true
  },
  {
    "id": 2,
    "first_name": "Anna",
    "last_name": "Engel",
    "given_names": [
      "Anna",
      "Octovina"
    ],
    "is_parent": true
  },
  {
    "id": 3,
    "first_name": "Bram",
    "last_name": "Engel",
    "given_names": [
      "Abraham",
      "Theofilus"
    ],
    "is_parent": false
  },
  {
    "id": 4,
    "first_name": "Paul",
    "last_name": "Engel",
    "given_names": [
      "Paulus",
      "Mathijs"
    ],
    "is_parent": false
  }
]

Closing words

Well that’s about it! Doesn’t using csonv.js come close to simplicity? Have fun! ^^

Contact me

For support, remarks and requests please mail me at paul.engel@holder.nl.

Credit

The String.csvSplit() function is based on Ben Nadel’s (@bennadel) blog post:

http://www.bennadel.com/his-blog-post

License

Copyright © 2011 Paul Engel, released under the MIT license

http://holder.nl – http://github.com/archan937 – http://codehero.es – http://gettopup.com – http://twitter.com/archan937 – paul.engel@holder.nl

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.