diff --git a/README.md b/README.md index 41a67ce..cb62679 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,12 @@ # Overview : +Generate CSV document according to given data. + +This data can be array of arrays , or array of literal objects or string which is the CSV content. + +# Example : ```js -import {CSVLink} from 'react-csv'; +import {CSVLink, CSVDownload} from 'react-csv'; const csvData =[ @@ -11,5 +16,103 @@ const csvData =[ ['Yezzi','Min l3b', 'ymin@cocococo.com'] ]; Download me +// or + +``` + +# Components: + +This package includes actually two components: `CSVLink` and `CSVDownload`. + +## 0. Common Props: + +The two components accepts the following `Props`: + +- **data** : a required property that represents the CSV data. +This data can be *array of arrays*, *array of literal objects* or *string*. + +**.i.e (array of arrays)** +```js +//array of arrays : each item is rendered as csv line +data = =[ + ['firstname', 'lastname', 'email'] , + ['Ahmed', 'Tomi' , 'ah@smthing.co.com'] , + ['Raed', 'Labes' , 'rl@smthing.co.com'] , + ['Yezzi','Min l3b', 'ymin@cocococo.com'] +]; +``` + +**.i.e (array of literal objects)** +```js +//array of literal objects : each item is rendered as csv line however the order of fields will be defined by headers props .If headers props is not defined , the component will generate headers from all data items. +data = [ + {firstname: 'Ahmed', lastname: 'Tomi' , email: 'ah@smthing.co.com'}, + {firstname:'Raed', lastname:'Labes' , email:'rl@smthing.co.com'} , + {firstname:'Yezzi', lastname:'Min l3b', email:'ymin@cocococo.com'} +]; +``` + +**.i.e (string)** + +```js +//if the data is string , this means the csv content is already generated by developer/3rd party package. + +data =`firstname,lastname +Ahmed,Tomi +Raed,Labes +Yezzi,Min l3b +`; +// or using 3rd party package +import json2csv from 'json2csv'; +data = json2csv(arrayOfLiteralObjects); ``` + +- **headers** : Specifying `headers` helps to define an order of CSV fields , so , the csv content will be generated accordingly. + +> Notes : +> - The meaning of headers with data of type `Array` is to order fields AND prepend those headers at the top of CSV content. +> - The meaning of headers with data of type `String` data is only prepending those headers as the first line of CSV content. + + + + +## 1. CSVLink Component: + +It renders a hyperlink , and clicking on it will trigger the download action of the CSV document. + +It does not accept only `data` and `headers` props , but also , it rendered all props of `HTMLAnchor` tag. (className, target,....) + +**example** + +```js +import {CSVLink} from 'react-csv'; + + + Download me + + +``` + + +## 2. CSVDownload Component: + +It triggers downloading ONLY on mounting the component. so , be careful to render this component whenever it is needed. + +It does not accept only `data` and `headers` props , but also , it takes advantage of all arguments of `window.open` function known that its signature is : + +```js +window.open(ARG0, target, specs, replace ) +``` + +Thus, `target`, `specs` and `replace` Props are available . + +**example** + +```js +import {CSVDownload} from 'react-csv'; + + +``` diff --git a/package.json b/package.json index 4c25766..3522b24 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "Build CSV files on the fly basing on Array/literal object of data ", "main": "index.js", "scripts": { - "compile": "babel --presets es2015,stage-0 -d lib/ src/", + "compile": "babel --presets es2015,stage-0,react -d lib/ src/", "prepublish": "npm run compile", "pretest": "npm run compile", "test2": "node_modules/.bin/_mocha test", diff --git a/src/components/CSVDownload.js b/src/components/CSVDownload.js deleted file mode 100644 index ea26f4c..0000000 --- a/src/components/CSVDownload.js +++ /dev/null @@ -1,21 +0,0 @@ -import React from 'react'; -import {buildURI} from '../core'; -import {defaultProps, PropTypes, PropsNotForwarded} from '../metaProps'; - -class CSVDownload extends React.Component { - constructor(props) { - super(props); - } - componentDidMount(){ - window.open(buildURI(this.props.data)); - } - - render(){ - return (null) - } -} - -CSVDownload.defaultProps = defaultProps; -CSVDownload.PropTypes = PropTypes; -CSVDownload.PropsNotForwarded = PropsNotForwarded; -export default CSVDownload; diff --git a/src/components/Download.js b/src/components/Download.js new file mode 100644 index 0000000..11e10db --- /dev/null +++ b/src/components/Download.js @@ -0,0 +1,31 @@ +import React from 'react'; +import {buildURI} from '../core'; +import {defaultProps as CommonDefaultProps, PropTypes} from '../metaProps'; + +const defaultProps = { + target: '_blank' +}; +class CSVDownload extends React.Component { + constructor(props) { + super(props); + } + componentDidMount(){ + this.page = window.open(buildURI(this.props.data, this.props.headers), this.props.target, this.props.specs, this.props.replace); + } + + getWindow() { + return this.page; + } + + render(){ + return (null) + } +} + +CSVDownload.defaultProps = Object.assign( + CommonDefaultProps, + defaultProps +); +CSVDownload.PropTypes = PropTypes; + +export default CSVDownload; diff --git a/src/components/CSVLink.js b/src/components/Link.js similarity index 68% rename from src/components/CSVLink.js rename to src/components/Link.js index c4b2a2e..0e3da47 100644 --- a/src/components/CSVLink.js +++ b/src/components/Link.js @@ -1,16 +1,17 @@ import React from 'react'; import {buildURI} from '../core'; import {defaultProps, PropTypes, PropsNotForwarded} from '../metaProps'; +import XObject from 'x-object/safe'; class CSVLink extends React.Component { constructor(props) { super(props); } - render(){ return ( - + !PropsNotForwarded.includes(k))} + href={buildURI(this.props.data, this.props.headers)}> {this.props.children} ) @@ -18,6 +19,5 @@ class CSVLink extends React.Component { } CSVLink.defaultProps = defaultProps; CSVLink.PropTypes = PropTypes; -CSVLink.PropsNotForwarded = PropsNotForwarded; export default CSVLink; diff --git a/src/index.js b/src/index.js index 4354a30..4dd8149 100644 --- a/src/index.js +++ b/src/index.js @@ -1,5 +1,5 @@ -import Download from './Download'; -import Link from './Link'; +import Download from './components/Download'; +import Link from './components/Link'; export const CSVDownload = Download; export const CSVLink = Link; diff --git a/src/metaProps.js b/src/metaProps.js index ee88c6d..6562a59 100644 --- a/src/metaProps.js +++ b/src/metaProps.js @@ -1,13 +1,28 @@ import React from 'react'; + + +export const PropTypes = { + data: React.PropTypes.oneOfType([ + React.PropTypes.string, + React.PropTypes.array + ]).isRequired, + headers: React.PropTypes.array, + target: React.PropTypes.string +}; + export const defaultProps = { }; -export const PropTypes = { - data: React.PropTypes.array.isRequired, - headers: React.PropTypes.array -}; - export const PropsNotForwarded = [ - `data` + `data`, + `headers` ]; + +// export const DownloadPropTypes = Object.assign( +// {}, +// PropTypes, +// { +// : , +// } +// );