CAPE Mapper

Introduction

This tool converts a JSON config file and one or more CSV or Excel documents into a CAPE JSON file. This CAPE json file can then be consumed by the CAPE3 project to search and display the source data.

Suggested workflow

The normal workflow to generate a CAPE JSON file is as follows:

• Create or obtain a sample source spreadsheet (Excel or CSV)
• Create a config.json file that describes the source spreadsheet.
• Run the CAPE mapper CLI to generate the CAPE JSON file.
• Consume the CAPE JSON file in a CAPE3 project.

Installing the CAPE mapper

Install globally using npm:

npm install --global cape-mapper

Using the CAPE mapper CLI

Once the cape-mapper npm package has been installed, the CLI can be used to convert your source data files into a CAPE JSON dataset.

Command Syntax

cape-mapper --config <config-file> --source <source-file(s)>

Command Line Arguments

| Argument | Required | Description | |----------|----------|-------------| | --config <filename> | Yes | The path to the CAPE config JSON file that describes the dataset schema and field mappings. | | --source <filename...> | Yes | The path(s) to the source data file(s) in CSV or Excel format. Multiple files can be specified by separating them with spaces. | | --version | No | Display the version number of the cape-mapper tool. | | --help | No | Display help information showing all available options. |

Output

The CLI outputs the generated CAPE JSON dataset to STDOUT (standard output). To save the output to a file, redirect it using the > operator.

Usage Examples

Basic usage with a single CSV file:

cape-mapper --config config.json --source dataset.csv

Redirect output to a JSON file:

cape-mapper --config config.json --source dataset.csv > output.json

Process multiple source files:

cape-mapper --config config.json --source file1.csv file2.csv file3.csv > combined-output.json

Using Excel files:

cape-mapper --config config.json --source data.xlsx > output.json

Display version:

cape-mapper --version

Display help:

cape-mapper --help

Config file properties

All properties are optional unless marked "Required".

Properties in the dataset object

• Properties used by the NODE mapper:
  • format - The format of the tabular data. Allowed values: 'xlsx', 'csv'. Default: 'csv'.
  • fields - Required. An array of field description objects (see below).
• Used by CAPE, checked and passed through as-is by the mapper
  • title - Required. String. Title of the dataset.
  • idField - Required. String. The ID of a field that is to be used for the record IDs. This should be the ID of a field described in this dataset.
  • sortableFields - Required. Array of Strings. A list of the IDs one or more field that will be used to sort the dataset. These all should be the ID of a field described in this dataset.
  • resultMode - Allowed values 'search', 'filter'. Default: 'filter.
  • metadata - (see below) This contains information that should be embedded with the dataset such as copyright and license information. These fields can be used in the site Vue templates.
  • ignoredSourceHeadings - an array of headings in the spreadsheet that are not used in any fields. Otherwise unused headings will raise an error.

Properties in the field object:

• Properties used by the NODE mapper:
  • id - String. Required. Must be unique within this dataset.
  • type - String. Allowed values: 'string', 'date', 'integer', 'enum'.
  • isMultiple - Boolean. Default: false. Indicates if the values are single or a list.
  • sourceHeading - String. Indicates the column heading(s) to take the value of this field from. This may be a list of columns if so then all values are returned if the field is multiple, or the first non-null value if it is not. Any columns with this heading plus a space and number are also added. So "Author" would include values from "Author 1", "Author 2" etc. This field may also be set to 'AUTO' in which case the values will be automatically set as a sequence of integers. This is a work around for datasets without a unique ID but is not recommended as deletions will renumber records.
  • sourceSplit - String. A regular expression used to split values for a multiple field. If multiple headings are specified this will apply to all the values. eg. '/s*;/s*'
  • sourceChars - Integer. If set, this will trim the length of values. A use for this is to convert ISO dates in the form 2020-03-04 into years by setting source_chars to 4.
• [text]
• Additional properties ignored by the mapper, passed through to the site JSON
  • label - String. Required.
  • description - String. A longer description of the field used in mouse over or whatever the template wants.
  • filterDisplay - 'hide','quick','advanced'. Indicates if this field's filter should only be shown on the advanced mode, always, or never. defaults to 'advanced'.
  • changeFilterMode - Boolean. Default true. If set to false then the filter mode can't be altered.
  • default - a string or array of strings
  • text field specific:
    • placeHolderIs - String. used as a placeholder text in the input for the field in "is" mode.
    • placeHolderContains - String. used as a placeholder text in the input for the field in "is" mode.
    • defaultFilterMode - set|notSet|is|contains
  • enum field specific:
    • placeHolderIs - String. used as a placeholder text in the input for the field in "is" mode.
    • defaultFilterMode - set|notSet|is|oneOf
    • values - an array of all the allowed values for this field (mapper will calculate this from the source data)
  • number field specific:
    • placeHolderIs - String. used as a placeholder text in the input for the field in "is" mode.
    • placeHolderBetween - Array of 2 strings. used as a placeholder text in the input for the field in "between" mode.
    • defaultFilterMode - set|notSet|is|between
    • min - Integer. the minimum input value
    • max - Integer. the maximum input value
    • step - Integer. the steps between input values.
  • date field specific:
    • placeHolderIs - String. used as a placeholder text in the input for the field in "is" mode.
    • placeHolderBetween - Array of 2 strings. used as a placeholder text in the input for the field in "between" mode.
    • defaultFilterMode - set|notSet|is|between
    • min - Integer. the minimum input value
    • max - Integer. the maximum input value

Notes:

• integer fields will be forced to be JSON integers.

Properties of the metadata object

These are all passed onto the output dataset JSON but are only validated by the mapper, not used. Unlike other objects, metadata may have additional fields.

• license - an object with the string values "title" and "url"
• copyright - an object with the string values "title" and "url"
• attribution - an object with the string values "title" and "url"
• creators - an array of objects with the string values "name" and "email"