@soton.ac.uk/cape3-mapper

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 using npm:

npm install cape-mapper

Using the CAPE mapper CLI

Once the cape-mapper npm package has been installed, the CLI can be called as follows:

cape-mapper -config [config.json] -source [source.json]

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 the PHP mapper only.
  • data_dir - String. Ignored.
  • base_file_name - String|Array of String. Ignored.
• Used by CAPE, checked and passed through as-is by the mapper
  • title - Required. String. Title of the dataset.
  • id_field - Required. String. The ID of a field that is to be used for the record IDs
  • sort - Required. Array of Strings. A list of the IDs one or more field that will be used to sort the dataset.
  • result_mode - Allowed values 'search', 'filter'. Default: 'filter.
  • extra_pages - A list of strings of additional pages. eg. "foo","bar". For each page you must include a templateFoo template in index.html

Properties in the field object:

• id - String. Required. Must be unique within this dataset.
• type - String. Allowed values: 'string', 'date', 'integer', 'enum', 'ignore'. Ignore is used to indicate source headings to intentionally ignore as an unreferenced heading will generate a warning. Ignored fields are not included in the output JSON.
• multiple - Boolean. Default: false. Indicates if the values are single or a list.
• source_heading - 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.
• source_split - 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*'
• source_chars - 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.

Additional properties ignored by the mapper, passed through to the site JSON

• label - String. Required by CAPE but may be omitted for "ignore" fields in the mapper.
• placeholder->{is} - String. used as a placeholder text in the input for the field in "is" mode.
• placeholder->{between} - Array of exactly 2 strings for the placeholder for the minimum and maximum fields.
• default - Array of one or more strings.
  • On text filters the first value only is the default
  • On integer and date "is" filters then the first value in the array is the default
  • On integer and date "between" filters then the first and second values in the array are the defaults
  • On enum "is" filters, then the first value in the array is the default
  • On enum "one-of" filters, then all the values are the default
• change_filter_mode - Boolean. Default true. If set to false then the filter mode can't be altered.
• default_filter_mode - one of is,one-of,between,set,not-set
• description - String. A longer description of the field used in mouse over or whatever the template wants.
• quick_search - Boolean. Default false. If true, this field will appear in the quick search in the UX. It is visible without selecting "advanced search".
• search - Boolean. Default true. If false this field will not appear in any search -- quick or advanced.
• style->{is} - type=enum only. One of "radio" or "select". Default "select". Pick the UI for selecting a value.
• style->{one-of} - type=enum only. One of "checkbox" and "multiselect". Default "multiselect". Pick the UI for selecting multiple values.
• min - type=integer only. Integer. Minimum value allowed in input.
• max - type=integer only. Integer. Maximum value allowed in input.
• step - type=integer only. Integer. Step value for input. Use, for example, to make allowed values multiples of 100.

Notes:

• integer fields will be forced to be integers.