Connecting to CSV data

This guide illustrates how to connect Flexmonster to a CSV data source.

You can connect to your CSV data using the client-side or the server-side approach. To connect to a CSV file smaller than 100 MB, use the client-side approach, which is described in this guide.
To connect to a CSV file larger than 100 MB, we recommend using Flexmonster Data Server — our server-side solution for processing large datasets. For more details, refer to the Connecting to CSV using Flexmonster Data Server guide.

Prerequisites

Your CSV data should be specified in the following format:

The first record contains field names.
Each record is located on a separate line.
Fields in records are separated by , or ;.
To specify another character that separates fields in your CSV file, use the dataSource.fieldSeparator property.
Fields can be enclosed in double quotation marks.
Fields containing line breaks or field separators (e.g., commas) must be enclosed in double quotation marks.
Note If your CSV file has fields with line breaks, set the dataSource.ignoreQuotedLineBreaks property to false.
If a field is quoted, double quotation marks inside the field must be represented by two double-quote characters. For instance, Speciality "Bike" Shop must be specified as "Speciality ""Bike"" Shop".

Example of a valid CSV file

Category,Color,Country,Price
Accessories,red,Australia,174
Components,blue,France,768
Clothing,green,Canada,512

Other CSV formats aren’t officially supported and may have unexpected results.

Note Ensure that dates are also specified in a supported format.

Step 1. Embed Flexmonster into your webpage

If Flexmonster is not yet embedded, set up an empty component in your webpage:

In pure JavaScript

Complete the Integrating Flexmonster guide. Your code should look similar to the following example:

const pivot = new Flexmonster({
  container: "pivotContainer",
  toolbar: true
});

In React

Complete the Integration with React guide. Your code should look similar to the following example:

<FlexmonsterReact.Pivot
 toolbar={true}
/>

In Angular

Complete the Integration with Angular guide. Your code should look similar to the following example:

<fm-pivot
 [toolbar]="true">
</fm-pivot>

In Vue

Complete the Integration with Vue guide. Your code should look similar to the following example:

<Pivot
 toolbar
/>

Step 2. Connect to your CSV data

You can connect Flexmonster to remote or local CSV data.

Connect to remote CSV data (from a file or a server-side script)

Remote CSV data can be a remote CSV file or data generated by a server-side script. Flexmonster can be connected to remote CSV data in one of the following ways:

Via UI
In the report
Using API calls

Via UI

To connect to remote СSV data via UI, use the Toolbar:

Step 1. On the Toolbar, select Connect > To remote CSV. As a result, the Open remote CSV pop-up window will appear.

Step 2. Enter the URL to your CSV data in the input field and click Open.

In the report

To connect to remote CSV data in the report, use the dataSource.filename property:

report: {
  dataSource: {
    filename: "<url-to-remote-csv-data>"
  }
}

Live example

Using API calls

To connect to remote CSV data at runtime, use the connectTo() or updateData() API call with the DataSourceObject input parameter. For details on data source configurations, go to the In the report tab:

To load the data and clear the report, use the connectTo() API call:
```
pivot.connectTo({
  filename: "<url-to-remote-csv-data>"
});
```
Live example

To load the data without clearing the report, use the updateData() API call:
```
pivot.updateData({
  filename: "<url-to-remote-csv-data>"
});
```
Live example

Connect to a CSV file from your computer

The pivot table can be connected to a CSV file from your computer in one of the following ways:

Via UI
In the report
Using API calls

Via UI

To connect to a local СSV file via UI, use the Toolbar:

Step 1. On the Toolbar, select Connect > To local CSV. As a result, the file manager will appear.

Step 2. Select the file via the file manager.

In the report

To connect to a local CSV file in the report, use the dataSource.browseForFile property:

report: {
  dataSource: {
    type: "csv",
    browseForFile: true
  }
}

Note The type property must be defined explicitly.

Live example

Using API calls

To connect to a local CSV file at runtime, use the connectTo() or updateData() API call with the DataSourceObject input parameter. For details on data source configurations, go to the In the report tab:

To load the file and clear the report, use the connectTo() API call:
```
pivot.connectTo({
  type: "csv",
  browseForFile: true
});
```
Note The type property must be defined explicitly.
Live example

To load the file without clearing the report, use the updateData() API call:
```
pivot.updateData({
  type: "csv",
  browseForFile: true
});
```
Note The type property must be defined explicitly.
Live example

List of supported configuration parameters

When connecting to CSV data, you can use the following properties to configure the DataSourceObject:

List of properties

Property/Type	Description
type String	The data source type. When connecting to CSV data, set the type to `"csv"`. You do not need to specify this property when loading static CSV files with a `.csv` extension.
browseForFile Boolean	optional Define `browseForFile` to load a file from the local file system. When set to `true`, this property opens the file manager, where you can select the necessary file with the data Live example. Default value: `false`.
filename String	The URL to a CSV file or to a server-side script that generates CSV data.
fieldSeparator String	optional Defines the specific fields separator to split each CSV row. There is no need to define it if the CSV fields are separated by `,` or `;`. This property is required only if another character separates fields. For example, if you use TSV, where a tab character is used to separate fields, then the `fieldSeparator` parameter should be set to `"\t"`. Alternatively, you can specify the field separator in the CSV file's first row using the `sep` prefix. Supported prefix formats are the following: `sep=fieldSep` and `"sep=fieldSep"`. For example: sep=\| Country\|Color\|Price Canada\|blue\|1000
thousandsSeparator String	optional If commas separate groups of digits in numbers (e.g., `1,000` for one thousand) in your CSV file, set `thousandsSeparator` to `","`.
ignoreQuotedLineBreaks Boolean	optional Indicates whether line breaks in quotes should be ignored (`true`) or not (`false`). When set to `true`, CSV parsing is faster. Set this property to `false` only if your data source has important line breaks in quotes. Note that this might slow down CSV parsing a little bit. Default value: `true`.
mapping MappingObject \| String	optional Defines how fields from the data source are treated and presented within the component. For example, you can specify the field’s captions, define a type for a field, configure multilevel hierarchies, etc. Read more in the Mapping guide. Can be either an inline MappingObject or a URL to a JSON file with the mapping Live example.
requestHeaders Object	optional Adds custom request headers. Consists of `"key": "value"` pairs, where `"key"` is a header name and `"value"` is its value Live example. Note The `requestHeaders` property is not saved when obtaining the report via `save()` and `getReport()` API calls.
withCredentials Boolean	optional Indicates whether cross-site `Access-Control` requests should be made using credentials such as authorization headers (`true`) or not (`false`). For more details, refer to MDN web docs. Setting the `withCredentials` flag to `true` is recommended when using Windows authentication and other types of server authentication. When set to `false`, the browser does not ask for credentials and does not include them in outgoing requests. Default value: `false`.

Configure fields from the data

You can define how fields from the data source are treated and presented within the component using the mapping. For example, you can:

Specify a caption for a field.
Define a field's data type.
Hide a field.
Define available aggregations for a field.
Configure multilevel hierarchies.

Note If you are using column prefixes to set data types in CSV, we recommend migrating from CSV prefixes to the mapping.

Migrate from CSV prefixes to the MappingObject

For easy migration of field types from CSV prefixes to the mapping, see the table below.

Migration table

CSV prefix	Mapping type	Description
`+`	`"string"`	The field is a dimension.
`-`	`"number"`	The field is a value.
`m+`	`"month"`	The field stores months.
`w+`	`"weekday"`	The field stores days of the week.
`d+`	`"date"`	The field stores a date. The field of this type is split into 3 different fields: Year, Month, and Day.
`D+`	`"year/month/day"`	The field stores a date. It’s displayed as a multilevel hierarchy with the following levels: Year > Month > Day.
`D4+`	`"year/quarter/month/day"`	The field is a date. It’s displayed as a multilevel hierarchy with the following levels: Year > Quarter > Month > Day.
`ds+`	`"date string"`	The field stores a date. It can be formatted using the `datePattern` option (default is `"dd/MM/yyyy"`).
`t+`	`"time"`	The field stores time.
`dt+`	`"datetime"`	The field stores a date. It can be formatted using the `dateTimePattern` option (default is `"dd/MM/yyyy HH:mm:ss"`).
`id+`	`"id"`	The field is an id. The field of this type can be used for editing data. It’s not shown in the Field List.

Display non-Latin characters correctly

If your data contains non-Latin characters, ensure you have set UTF-8 encoding for your data and page. This is required to display the data correctly in the component.

Troubleshooting

If you run into any issues, visit our troubleshooting page.

What's next?

You may be interested in the following articles:

Changes to Flexmonster Software License Agreement

Connecting to CSV data

Prerequisites

Step 1. Embed Flexmonster into your webpage

In pure JavaScript

In React

In Angular

In Vue

Step 2. Connect to your CSV data

Connect to remote CSV data (from a file or a server-side script)

Via UI

In the report

Using API calls

Connect to a CSV file from your computer

Via UI

In the report

Using API calls

List of supported configuration parameters

Configure fields from the data

Migrate from CSV prefixes to the MappingObject

Display non-Latin characters correctly

Troubleshooting

What's next?