Installation
Install the plugin using npm:Configuration & Parameters
The plugin accepts a configuration object with the following parameters:sheetSlug
- Type:
string
- Default:
'**'
- Description: The slug of the sheet to apply the validation to. The default
'**'
applies it to all sheets in the workspace.
isbnFields
- Type:
string[]
- Default:
['isbn']
- Description: An array of field keys that contain ISBN values to be validated.
autoFormat
- Type:
boolean
- Default:
true
- Description: If set to true, the plugin will automatically format valid ISBNs with hyphens (e.g., ‘9780306406157’ becomes ‘978-0-306-40615-7’).
format
- Type:
string
(optional) - Default:
undefined
- Description: If specified, the plugin will attempt to convert the ISBN to the given format. Possible values are
'isbn13'
,'isbn13h'
(with hyphens),'isbn10'
, and'isbn10h'
(with hyphens).
Usage Examples
Basic Usage
Custom Configuration
Standalone Validation Function
Troubleshooting
Common troubleshooting steps include:- Sheet Configuration: Verify that the
sheetSlug
in the configuration exactly matches the slug of the target sheet in your Flatfile Space. - Field Mapping: Ensure the strings in the
isbnFields
array match the field keys in your sheet’s data model. - Installation: Confirm that the plugin is correctly installed (
npm install @flatfile/plugin-validate-isbn
) and imported.
Notes
Default Behavior
By default, the plugin runs on all sheets, targets the field with the key ‘isbn’, and automatically formats any valid ISBNs by adding hyphens. It does not perform any format conversion unless theformat
option is explicitly set.
Dependencies
This plugin has an external dependency on theisbn3
library, which handles the core validation and conversion logic. The plugin operates using recordHook
, which is triggered by the commit:created
event. This means validation runs after a user submits their data but before the commit is finalized.
Error Handling
The plugin follows standard Flatfile error handling patterns:- For validation failures, it uses
record.addError(field, message)
to attach a blocking error to the specific field. - For successful formatting or conversion, it uses
record.addInfo(field, message)
to provide non-blocking feedback to the user. - If a configured ISBN field is empty or null for a given record, the plugin skips it without adding an error.