Skip to content

Commit f1e4e4f

Browse files
evanplaiceevanplaice
committed
Add new README.md
1 parent c4164b7 commit f1e4e4f

File tree

1 file changed

+203
-0
lines changed

1 file changed

+203
-0
lines changed

‎README.md

+203
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
#jquery-csv
2+
3+
##Summary
4+
5+
Javascript is growing up and HTML is finally maturing the point where webapps are being built to completely displace desktop applications. It's about time that the supporting libraries grow up too.
6+
7+
Looking for a complete, end-to-end, battle tested, performance optimized CSV parser that's available in the familiar jQuery syntax style? Welcome...
8+
9+
This library is a different creature, featuring a slim Chomsky - Type III parser implementation. Full (that means 100%) [IETF RFC 4180](http://tools.ietf.org/html/rfc4180) compliance. Including coverage for a few edge cases that even the spec fails to cover.
10+
11+
Enough with the wind-up...
12+
13+
Want to see it in action? Check out the Basic Usage Demo. Want more? The Use Cases section below has what you need.
14+
15+
Aside: To the script kiddies... Don't be sad, we bet there are still plenty of people who would like to hear you outline the merits of `str.split()`.
16+
17+
##Features
18+
19+
* Convert a CSV String to an array
20+
* Convert a multi-line CSV string to a 2D array
21+
* Convert a multi-line CSV string to an array of objects (ie header:value pairs)
22+
* Convert an array of values to CSV (under development)
23+
* Convert an array of objects to CSV (under development)
24+
* Hooks/Callbacks to extend the default parsing process
25+
* Customizable delimiter (default: ") and separator (default: ,) characters
26+
* Node.js support (ie CommonJS importing and async callback support)
27+
28+
## Syntax
29+
30+
###Importing
31+
32+
**Client-Side** (ie browser) - import via the script element.
33+
```javascript
34+
<script src="jquery-csv.js"></script>
35+
```
36+
37+
**Server-Side** (ie Node.js) - Import via the standard CommonJS approach.
38+
```javascript
39+
var $ = jQuery = require('jquery');
40+
require('./jquery.csv.js');
41+
```
42+
43+
###Usage
44+
45+
Each one of the methods can be called with the following form:
46+
```javascript
47+
$.csv.function(csv, {options}, callback);
48+
```
49+
50+
| Name | | Description |
51+
|-----------|-----------|:------------|
52+
| csv | required | The csv data to be transformed. |
53+
| options | optional | An object containing user-defined overrides for the default options. |
54+
| callback | optional | Used for Node.js-style async callbacks. Uses the form function(err, data). |
55+
56+
###Methods
57+
58+
**toArray**
59+
60+
Parse a single entry string to an array
61+
```javascript
62+
$.csv.toArray(csv);
63+
```
64+
*Documented under API#$.csv.toArray().*
65+
66+
**toArrays**
67+
68+
Parse a multi-line CSV string to a 2D array
69+
```javascript
70+
$.csv.toArrays(csv);
71+
```
72+
*Documented under API#$.csv.toArrays().*
73+
74+
**toObjects**
75+
76+
Parse a multi-line CSV string to an array of objects
77+
```javascript
78+
$.csv.toObjects(csv);
79+
```
80+
*Documented under API#$.csv.toObjects().*
81+
82+
**fromArrays**
83+
84+
Convert array data to a CSV string
85+
```javascript
86+
$.csv.fromArrays(arrays);
87+
```
88+
89+
**fromObjects**
90+
91+
Convert an array of objects to a CSV string
92+
```javascript
93+
$.csv.fromObjects(objects);
94+
```
95+
96+
## Documentation
97+
98+
- [API](./docs/api.md)
99+
- [Hooks & Callbacks](./docs/hooks-callbacks.md)
100+
- [Algorithm](./docs/algorithm.md)
101+
102+
## Use Cases
103+
104+
What fun is having a shiny new library without examples to play with?
105+
106+
No fun that's what... That is coming from a guy who has spent entirely too much time mucking through API documentation when he'd much rather be out at the beach, surfing, or chasing girls.
107+
108+
Instead of the typical useless contrived example code, I have provided a handful of simple yet powerful demos. Not only are they fun to play with but a quick peak at the source will show you how simple and easy they were to implement.
109+
110+
Who knows... maybe this whole 'having fun' concept may spread to some of the other Open Source libraries as a result. One can dream...
111+
112+
### Basic Usage
113+
114+
Want to play with the parser and maybe validate your CSV data without all the frills? No need to download the source first, there's a demo for that...
115+
116+
[jQuery-CSV - Basic Usage Demonstration](./examples/basic-usage.html)
117+
118+
### Client-Side File Handling
119+
120+
Yes, you read that right. It's now possible to open local files in the browser without firing a single request to the server.
121+
122+
The functionality is still pretty new so not all browsers support it (I'm looking @ you IE). If that's not an issue I highly suggest you try it. It's much easier than the traditional client/server approach.
123+
124+
[jQuery-CSV - File Handling Demonstration](./examples/file-handling.html)
125+
126+
### jQuery-CSV + Flot
127+
128+
Hands down, the most exciting addition to the demo collection so far...
129+
130+
You can input the data set using either the text area provided or via uploading CSV data files.
131+
132+
Want to plot 5 data sets on the same grid, no problem; Just upload 5 files containing one dataset each. The jQuery-CSV will handle the plumbing while Flot will make it all look pretty.
133+
134+
[jQuery-CSV - Flot Demonstration](./examples/flot.html)
135+
136+
### jQuery-CSV + Google Visualization API
137+
138+
OK, I lied. This one is even cooler than Flot. Hike up your fancy pants because these things look slick.
139+
140+
Don't want to draw a line graph, no problem you can tap into the massive collection of different graph types available. Embedded is a fully configurable dashboard.
141+
142+
Warning: You may experience multiple spontaneous 'oh my got that's soo awesome' fits of excitement. Maybe even get stoked. Happens to the best us...
143+
144+
[jQuery-CSV - Google Visualization API Demonstration](./examples/google-visualization.html)
145+
146+
### jQuery-CSV + Node.js
147+
148+
What's better than a powerful JavaScript? platform in the browser. A second, even more powerful JavaScript? platform on the server.
149+
150+
And... jQuery-CSV fully supports it. There is not online demo because it requires a Node.js server to run but a stub is provided to help get you started.
151+
152+
Dependencies:
153+
154+
To make this example work, you'll also need to install jQuery via the NPM.
155+
156+
```npm install jquery```
157+
158+
The link to the stub:
159+
160+
[node-usage.js](./examples/node-usage.js)
161+
162+
### Client-Side Database Import
163+
164+
Wait... what? Don't databases require a server-side API? Not if the data access layer implements a REST API that accepts JSON POST updates.
165+
166+
When it comes to databases, CSV is still a favored format for data dumps because it's simple, lightweight, and platform agnostic. It's possible to expose a server-side SaaS service to handle the data conversion but that would involve more web requests, more bandwidth, more CPU time, and more unnecessary strain on the webserver.
167+
168+
I hear web browsers are becoming more powerful, lets use those...
169+
170+
It will require [jQuery-JSON]() to handle the data (de)serialization but the chain from a CSV file to an AJAX POST request is very simple.
171+
172+
Open a .csv file Locally (HTML5 File API) -> jQuery-CSV -> jQuery.JSON -> jQuery.POST
173+
174+
(planned HTML example needs to be added to the repository)
175+
176+
## Long-Term Development
177+
178+
1.0 will be the first long-term stable release. The API will be locked until the next major release. New functionality-breaking and/or backwards incompatible changes will be introduced into the master branch.
179+
180+
## Short-Term Development
181+
182+
0.8.0 The first stable release following the migration to GitHub from Google Code.
183+
184+
* The parser is fully featured and mostly bug free
185+
* The TODO list includes re-vamping of the Documentation & examples
186+
* Tests will be revisited and work will be done to add headless browser testing support.
187+
* NPM support will be added
188+
* Hopefully, Bower support can be transferred over from Mirlord and updated to the latest.
189+
190+
## How You Can Help
191+
192+
**Run the test runner:** Just run the **tests** in your particular brand of browser and report any failures.
193+
194+
**We need performance tests:** Performance tests in javascript would add a lot of value to the project. If that's your forte, don't be shy.
195+
196+
**Provide feedback:** If you have a good suggestion, a useful use case, or just want to share your experience, don't hesitate to get involved.
197+
198+
Without your contributions and the contributions of the community, this would be just another half-baked CSV to add to the pile of literally thousands of broken/incomplete implementations. The quality of projects like these is a direct result of a greater community that is willing to suggest improvements and test the code.
199+
200+
**jQuery-CSV** coding style is inherited from the [JQuery Core Style Guidelines](https://contribute.jquery.org/style-guide/)
201+
202+
by **Evan Plaice**
203+

0 commit comments

Comments
 (0)