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