importOK

Examples

Javascript

importOK is a reusable custom web component that embeds an import wizard into your app. You can follow this installation guide to set it up with vanilla Javascript.

Preview in Stackblitz @importok/javascript

Installation

For the sake of simplicity, we are going to install and configure importOK to import a list of Contacts. Our app will be expecting four fields: first name last name email and phone

First, import the Javascript package for importOK:

1npm install @importok/javascript

To embed the wizard, add the following into your page. The wizard will be added as a child element to the first argument provided, so make sure to adjust that accordingly.

 1import ImportOK from './node_modules/@importok/javascript/importok.js';
 2window.onload = function () {
 3  /**
 4  * Import fields to be mapped
 5  * Check https://importok.io/docs/fields for more details
 6  */
 7  const importFields = {
 8    first_name: {
 9      label: 'First Name',
10      transformers: 'capitalize|trim'
11    },
12    last_name: {
13      label: 'Last Name',
14      validators: 'required',
15      transformers: 'capitalize|trim'
16    },
17    email: {
18      label: 'Email',
19      validators: 'email|required',
20      transformers: 'lowercase|trim'
21    },
22    phone: {
23      label: 'Phone',
24      transformers: 'trim'
25    }
26  };
27 
28  /**
29    * Custom transformers
30    * Check https://importok.io/docs/custom-transformers for more details
31    */
32  const customTransformers = {};
33 
34  /**
35    * Custom validators
36    * Check https://importok.io/docs/custom-validators for more details
37    */
38  const customValidators = {};
39 
40  /**
41    * Custom providers
42    * Check https://importok.io/docs/data-providers for more details
43    */
44  const customProviders = {};
45 
46  /**
47    * Push the provided record to the API
48    * Check https://importok.io/docs/webhooks for more details
49    */
50  const saveRecord = async function (record, meta) {
51    return await fetch('https://httpstat.us/200');
52  };
53 
54  /**
55    * Initialize the wizard and append it to the provided element
56    */
57  ImportOK.add(
58    document.getElementById('import-wizard'),
59    {
60      fields: importFields,
61      meta: {
62        user_id: 1,
63      },
64        transformers: customTransformers,
65        validators: customValidators,
66        providers: customProviders,
67        onRecordReady: saveRecord
68      }
69    );
70  }

That's all! You can now open your page and give a try. Keep in mind that that there is a limit of 20 records for each import during the trial. Once subscribed, you will receive access to the private packages and lift the trial limits.

Props

title

Description Primary text to be displayed at the top of the wizard, across all steps.
Type string
Default Import

subtitles

Description Secondary text to be displayed at each wizard step.
Type string[]
Default 
[
'Upload your file to get started',
'Match source to target columns',
'Review validation errors and fix your data',
'Please do not close this window during the import process.',
]

fields

Description Fields to be mapped - refer to Fields for more details.
Type { [key: string]: ImportField; }
Default {}

transformers

Description Custom transformers - refer to Build your own transformers for more details.
Type { [key: string]: (record: ImportRecord, key: string, ...args: string[]); }
Default {}

validators

Description Custom validators - refer to Build your own validators for more details.
Type { [key: string]: (record: ImportRecord, key: string, ...args: string[]); }
Default {}

providers

Description Custom providers - refer to Data providers for more details.
Type { [key: string]: DataProvider; }
Default {}

mapper

Description Custom mapping strategy - refer to Mapping strategy for more details.
Type MapperStrategy
Default LevenshteinMappingStrategy

style

Description Custom CSS rules. Please refer to Styling for more details.
Type string
Default undefined

locale

Description The locale to use. Please refer to Internalization for more details.
Type string
Default en

translations

Description Provide additional translations, or overwrite the existing ones. Please refer to Internalization for more details.
Type { [key: string]: { [key: string]: string } }

sampleFile

Description Example file that can be download in the first step as an example.
Type string
Default ''

uploadedFile

Description Raw file to be imported. Useful if your application already offers an upload area.
Type File
Default undefined

throttle

Description Throttle the import process - applicable when used with onRecordReady
Type number
Default 0 (no throttle)

meta

Description Meta data to be passed to onRecordReady and onImportReady.
Type object
Default {}

onRecordReady

Description Callback to import a single record.
Type function(record: ImportRecord, meta: object): Promise<any>
Event props
  • record The record to be imported.
  • meta The meta object passed in the meta prop (if any), plus additional meta data from import include the file size and type.
Default undefined

onImportReady

Description Callback to import multiple records at once.
Type function(records: ImportRecord[], meta: object): Promise<any>
Event props
  • records The records to be imported.
  • meta The meta object passed in the meta prop (if any), plus additional meta data from import include the file size and type.
Default undefined

onImportProgress

Description Triggered when the progress changes.
Event props
  • processed How many records processed so far, including failed.
  • failed How many records failed so far.
  • total Total number of records.

onStepEnter

Description Triggered when the user enters a new step of the wizard.
Event props
  • step The index of the step the user is entering.
  • previousStep The index of the step the user is leaving.

onStepExit

Description Triggered when the user is about to exit the current step.
Event props
  • step The index of the step the user is exiting.
  • nextStep The index of the step the user previously exited.