vue-nested-json-to-csv
A component to allow nested JSON or nested javascript objects/arrays to be queried and exported to csv. A query result row is generated for each array element in the data object provided.
Getting Started
Installing
npm install vue-nested-json-to-csv
Basic Usage
The below is a basic example of using this component
<template>
<div id="app">
<vue-nested-json-to-csv
:fields="myFields"
:object="myData"
:show-table="true"
:show-export-button="true"
></vue-nested-json-to-csv>
</div>
</template>
<script>
export default {
data(){
return {
myFields: [
{
alias: 'A Friendly Display Name',
name: 'dataObject.stringProperty'
},
{
alias: 'Another Friendly Display Name',
name: 'dataObject.stringArrayProperty'
},
{
alias: 'Yet Another Friendly Display Name',
name: 'dataObject.objectArrayProperty.stringProperty'
},
{
alias: 'Yet Again Another Friendly Display Name',
name: 'dataObject.objectArrayProperty.arrayProperty'
},
],
myData: {
dataObject: [
{
stringProperty: "string1",
stringArrayProperty: [
"arrayString1",
"arrayString2",
"arrayString3",
],
objectArrayProperty: [
{
stringProperty: "objectArrayString1",
arrayProperty: [
"arrayString1",
"arrayString2",
],
},
{
stringProperty: "objectArrayString2",
},
{
stringProperty: "objectArrayString3",
},
]
},
{
stringProperty: "string2",
stringArrayProperty: [
"arrayString4",
"arrayString5",
"arrayString6",
],
objectArrayProperty: [
{
stringProperty: "objectArrayString4",
},
{
stringProperty: "objectArrayString5",
},
]
},
]
},
};
}
}
</script>
The above usage would result in the below if exported to CSV.
| A Friendly Display Name | Another Friendly Display Name | Another Friendly Display Name | Yet Again, Another Friendly Display Name |
|---|---|---|---|
| string1 | arrayString1 | arrayString2 | arrayString3 | objectArrayString1 | objectArrayString2 | objectArrayString3 | arrayString1 | arrayString2 |
| string2 | arrayString4 | arrayString5 | arrayString6 | objectArrayString4 | objectArrayString5 |
Expected Data Format
Whilst it is not necessary to export query results as a csv to utilise this component, the nature of the queries being performed and the data being returned lends itself to csv or tabular output.
Specifically, the component is designed to be used with an object such as that you might receive as the data portion of an API response, with a single property that is an array of similar objects where each element in this array corresponds to a csv or table row. Alternatively, the "object" provided can be an array of similar objects.
For example, following an API call, you may receive a response such as the below. The component is designed to be assigned the value of the data property of this response, or the entire response (if the latter, the component would likely be used to query the array against the data property).
{
"current_page": 1,
"data": [
{
"code": "EXAMPLE_CODE_1",
"attributes": {
"LOYALTY_POINTS": "288",
"GLOB__FINANCE_OPTIONS": [
"FINANCE_OPTION_1",
"FINANCE_OPTION_2",
"FINANCE_OPTION_3",
"FINANCE_OPTION_4"
],
}
},
{
"code": "EXAMPLE_CODE_2",
"attributes": {
"LOYALTY_POINTS": "288",
"GLOB__FINANCE_OPTIONS": [
"FINANCE_OPTION_1",
"FINANCE_OPTION_2",
"FINANCE_OPTION_3",
"FINANCE_OPTION_4"
],
}
},
{
"code": "EXAMPLE_CODE_3",
"attributes": {
"LOYALTY_POINTS": "608",
"GLOB__FINANCE_OPTIONS": [
"FINANCE_OPTION_1",
"FINANCE_OPTION_2",
"FINANCE_OPTION_3",
"FINANCE_OPTION_4"
],
}
}
],
"total": 115720
}
Concatenation
Where the values returned for a field are an array of strings or integers, these values will be returned in a single result "cell", concatenated and joined by a string which is determined by the concatenation-characters prop. For example, if the myObj.myArr field was retrieved from the below data (with a default concatenation-characters prop):
[
{
myObj: {
myArr: [
"string1",
"string2",
]
}
},
{
myObj: {
myArr: [
"string3",
"string4",
]
}
}
]
Then the below results would be present in the filteredData component data (e.g. what would be emitted in the data property of the object accompanying a filtered event):
[
[
"string1 | string2"
],
[
"string3 | string4"
]
]
Props
The above usage example includes only a few of the props that can be provided to the component. A full list follows:
file-name-function
Expects: Function
Default: returns Report<ms_since_1970>.csv
A function can be provided to the component to generate the file name that is used for exported csv files. The default function returns Report<ms_since_1970>.csv. The component does not append the .csv extension to the file name returned by this function (it is done within the function itself), so it is recommended that the provided function does this.
show-export-button
Expects: Boolean
Default: false
When true, the export-button slot is rendered.
show-table
Expects: Boolean
Default: false
When true, the table slot is rendered.
json
Expects: String (JSON format)
Default: Empty string
If this prop is provided and the object prop is not, the string provided is parsed and used as the data object to be queried.
object
Expects: Object (JSON format)
Default: Empty object
If this prop is provided, this will be used as the data object to be queried regardless of the presence of the json prop.
fields
Expects: Array of dot-notated field names or array of objects each containing an alias and name property
Default: Empty array
This prop determines which fields should be returned. The first item in the array is used to determine how the prop should be processed. For example, if this is a string (i.e. a field name), then the rest of the array is expected to be the same.
An array of objects can be provided in this prop, each with an alias and name property. The alias property will be used for display purposes (e.g. what is shown in the exported csv or results table). The name property should be the dot-notated string specifying the property to be returned.
If a simple array of strings is provided in this prop, each string is effectively treated as both the name and alias properties.
errors
Expects: Boolean
Default: true
If this prop is set to true, the component can generate console errors and warnings to aid with debugging and implementation.
concatenation-characters
Expects: String
Default: " | "
This prop controls the string used to concatenate array results for queried properties. For example, where the queried property's value is an array of strings, the returned result would be: arr_el_1<concatenation_string>arr_el_2<concatenation_string>...arr_el_n
export-function
Expects: Function
Default: Function to export data as csv
This prop controls the function that is called when the default export-button is clicked. By default, this function is passed two parameters. These are the aliasedFields and filteredData component data - the former is used as a header row for the resultant csv, whilst the latter forms the body of the csv. The default function also triggers exporting and exported events appropriately.
If you desire some other functionality to be performed when clicking the default export-button, utilise this prop.
Slots
The below slots can be used to customise the appearance of the component
table
The default content for this slot renders a table (utilising Bulma classes) which has a column for each element in the fields prop, with a column header for each field (where an alias property has been provided for the field, this will be used as the column header). The table then contains a row for each element (an array) in the component's filteredData data, with each element of that array being displayed as a "cell" in the table.
When customising the content of this slot, please note the above if you intend on achieving similar results.
Note: the contents of this slot are only rendered if the show-table prop is set to true
export-button
The default content for this slot renders a button (utilising Bulma classes), which performs the export-function prop on click. By default, the function is passed the aliasedFields and filteredData component data.
Note: the contents of this slot are only rendered if the show-export-button prop is set to true
Events
This component triggers various events when processing data. These can be hooked into to improve your implementation of the component.
filtering
Triggered when: the fields, object or json props change.
Passes data: an object containing an unaliasedFields property this is an array of the field names being used to query the data object
filtered
Triggered when: the query results are about to be returned
Passes data: an object containing unaliasedFields, aliasedFields and data properties, which represent the dot-notated field names, display field names and query results respectively
exporting
Triggered when: the default export-function is called
Passes data: an object containing fields and data properties. These represent the aliased field names and query results respectively
exported
Triggered when: the default export-function has completed
Passes data: an object containing a csv property, which is an array whose first element is an array of aliased field names. The rest of the elements represent "rows" of query results - with each row being an array with each element representing the result for a queried field for the given row.
Authors
- Dan Clark - email me with a question
License
This project is licensed under the MIT License - see the LICENSE file for details