fuse-importer 0.23.0 → 0.23.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +258 -0
  2. package/lib/main.js +1 -1
  3. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,258 @@
1
+ <div>
2
+ <center>
3
+ <a href="https://fuse.flatironsdevelopment.com/users/sign-up?utm_source=npmjs&utm_medium=Fuse+importer+logo&utm_campaign=NPM">
4
+ <img alt="Flatirons Fuse" src="https://wp.flatironsdevelopment.com/wp-content/uploads/2022/07/fuse-logo.png">
5
+ </a>
6
+ </center>
7
+ <br>
8
+ <br>
9
+ <p>
10
+ Flatirons Fuse is a customizable and powerful CSV Importer that works with all front-end languages.
11
+ </p>
12
+ </div>
13
+
14
+ ## Table of Contents
15
+
16
+ - [Installation](#installation)
17
+ - [Introduction](#introduction)
18
+ - [Registration](#registration)
19
+ - [Create Your First Template](#create-your-first-template)
20
+ - [Getting started](#getting-started)
21
+ - [More Examples](#more-examples)
22
+ - [Usage](#usage)
23
+ - [FuseImporter Hooks](#fuseimporter-hooks)
24
+ - [`show`](#show)
25
+ - [`close`](#close)
26
+ - [`onClose`](#onclose)
27
+ - [`onValidateRecord`](#onvalidaterecord)
28
+ - [`formatRecord`](#formatrecord)
29
+ - [`onSubmit`](#onsubmit)
30
+
31
+ ## Installation
32
+
33
+ You can use Yarn, NPM, or a CDN to install the importer.
34
+
35
+ Install with npm:
36
+
37
+ ```bash
38
+ npm install fuse-importer --save
39
+ ```
40
+
41
+ Install with yarn:
42
+
43
+ ```bash
44
+ yarn add fuse-importer
45
+ ```
46
+
47
+ Install with CDN:
48
+
49
+ ```html
50
+ <script
51
+ type="text/javascript"
52
+ src="https://unpkg.com/fuse-importer@latest.js"
53
+ ></script>
54
+ ```
55
+
56
+ ## Introduction
57
+
58
+ Flatirons Fuse is our solution to the inevitable difficulties of getting customer data into your solution. We provide a white-labeled, customizable CSV and Spreadsheet import experience that is above all effective and flexible. Not only do we save you the time and effort of developing your own import solution, but we also ensure that setup and integration with your systems are a breeze.
59
+
60
+ To get started with our solution, you're going to need a free account and to create a template on our platform: [Flatirons Fuse](https://fuse.flatironsdevelopment.com/users/sign-up?utm_source=npmjs&utm_medium=Flatirons+Fuse+Get+Started&utm_campaign=NPM)
61
+
62
+ To use the importer you will need two keys:
63
+
64
+ - Your **Organization's API key**: You can find this at the top of the [Templates page](#create-your-first-template).
65
+ - Your **Template's ID**: You can find this in the table on the [Templates page](#create-your-first-template).
66
+
67
+ For more information see our [full documentation.](https://fuse-docs.flatironsdevelopment.com?utm_source=npmjs&utm_medium=Fuse+importer+Full+Documentation&utm_campaign=NPM)
68
+
69
+ Check it out in action:
70
+
71
+ <div>
72
+ <center>
73
+ <img alt="Check it out in action" src="https://wp.flatironsdevelopment.com/wp-content/uploads/2022/07/ezgif-1-242e10926e.gif">
74
+ </center>
75
+ </div>
76
+
77
+ ## Registration
78
+
79
+ If you don't have an account yet, you can go over the [Registration](https://fuse-docs.flatironsdevelopment.com/getting-started/registration?utm_source=npmjs&utm_medium=Registration&utm_campaign=NPM).
80
+
81
+ ## Create Your First Template
82
+
83
+ If you don’t have a Template yet, you can go over [Create Your First Template](https://fuse-docs.flatironsdevelopment.com/getting-started/create-your-first-template?utm_source=npmjs&utm_medium=Create+Your+First+Template&utm_campaign=NPM). Template represents the fields and validations that your own system accepts, also known as your data schema.
84
+
85
+ ## Getting started
86
+
87
+ ```html
88
+ <!DOCTYPE html>
89
+ <html>
90
+ <head>
91
+ <script
92
+ type="text/javascript"
93
+ src="https://unpkg.com/fuse-importer@latest"
94
+ ></script>
95
+ <script type="text/javascript">
96
+ const organizationApiKey = "YOUR ORGANIZATIONS API KEY";
97
+ const templateId = "YOUR TEMPLATE ID";
98
+ const importer = new FuseImporter(organizationApiKey, templateId);
99
+
100
+ importer.onValidateRecord = async (record) => {
101
+ // return no frontend validation errors
102
+ return {};
103
+ };
104
+
105
+ importer.onSubmit = async (records) => {
106
+ // an empty hash will tell us the import was successful!
107
+ return {
108
+ message: "Your data was imported successfully",
109
+ errors: {},
110
+ };
111
+ };
112
+
113
+ window.showFuseImporter = () => {
114
+ if (
115
+ organizationApiKey.indexOf("YOUR") !== -1 ||
116
+ templateId.indexOf("YOUR") !== -1
117
+ ) {
118
+ window.confirm(
119
+ "You need to configure your organization api key and template id."
120
+ );
121
+ return;
122
+ }
123
+ importer.show();
124
+ };
125
+ </script>
126
+ </head>
127
+
128
+ <body>
129
+ <button onclick="javascript:showFuseImporter()">Show Importer</button>
130
+ </body>
131
+ </html>
132
+ ```
133
+
134
+ ## More Examples
135
+
136
+ - [Quickstart Examples](https://fuse-docs.flatironsdevelopment.com/installation/quickstart-examples?utm_source=npmjs&utm_medium=More+Examples+Quickstart+Examples&utm_campaign=NPM)
137
+ - [React.js](https://fuse-docs.flatironsdevelopment.com/use-cases/react.js-csv-importer?utm_source=npmjs&utm_medium=More+Examples+React&utm_campaign=NPM)
138
+ - [Angular](https://fuse-docs.flatironsdevelopment.com/use-cases/angular-csv-importer?utm_source=npmjs&utm_medium=More+Examples+Angular&utm_campaign=NPM)
139
+ - [Vue.js](https://fuse-docs.flatironsdevelopment.com/use-cases/vue.js-csv-importer?utm_source=npmjs&utm_medium=More+Examples+Vue&utm_campaign=NPM)
140
+
141
+ ## Usage
142
+
143
+ ```typescript
144
+ import FuseImporter from "fuse-importer";
145
+
146
+ const organizationApiKey = "YOUR ORGANIZATIONS API KEY";
147
+ const templateId = "YOUR TEMPLATE ID";
148
+ const importer = new FuseImporter(organizationApiKey, templateId);
149
+ ```
150
+
151
+ ### FuseImporter Hooks
152
+
153
+ Hooks allow you to show the importer, run validations, and submit records to your backend.
154
+
155
+ #### `show`
156
+
157
+ The show function does exactly what it sounds like; it launches the importer. Ensure you have initialized the importer properly beforehand. Use this function like so:
158
+
159
+ ```typescript
160
+ importer.show();
161
+ ```
162
+
163
+ #### `close`
164
+
165
+ The close function allows you to remove the importer from the view.
166
+
167
+ ```typescript
168
+ importer.close();
169
+ ```
170
+
171
+ #### `onClose`
172
+
173
+ The onClose function allows you to be notified when the importer is removed from the view.
174
+
175
+ ```typescript
176
+ importer.onClose = () => {
177
+ console.log("The importer was closed!");
178
+ };
179
+ ```
180
+
181
+ #### `onValidateRecord`
182
+
183
+ The `onValidationRecord` hook is called for each row (record) that a customer uploads. It allows you to specify custom frontend validations and display error messages in the importer for the user to fix. When you create a Template, each column contains an `internal key`. These internal keys represent the
184
+
185
+ Return values:
186
+
187
+ - If the record has no errors, we expect you to return an empty object: `return {}`;
188
+ - If the record has validation errors, you can specify them like so:
189
+
190
+ ```typescript
191
+ importer.onValidateRecord = async (record) => {
192
+ const errors = {};
193
+
194
+ // force emails to include gmail
195
+ if (!record.email?.includes("gmail")) {
196
+ errors["email"] = "Email must be from Gmail";
197
+ }
198
+
199
+ return errors;
200
+ };
201
+ ```
202
+
203
+ #### `formatRecord`
204
+
205
+ The `formatRecord` hook can be used to format data automatically on behalf of a user. For example, if you have a field called `first_name` and you know that your system always requires `first_name` to be capitalized, you can use this callback to uppercase all `first_name` records like so:
206
+
207
+ ```typescript
208
+ importer.formatRecord = (record) => {
209
+ const newRecord = { ...record };
210
+
211
+ // capitalize first letter in first_name
212
+ if (typeof newRecord.first_name === "string") {
213
+ newRecord.first_name =
214
+ newRecord.first_name.charAt(0).toUpperCase() +
215
+ newRecord.first_name.slice(1);
216
+ }
217
+
218
+ return newRecord;
219
+ };
220
+ ```
221
+
222
+ #### `onSubmit`
223
+
224
+ `onSubmit` will pass all records to you after the user has made any necessary corrections to frontend validations. This callback expects you to submit the records to your backend in whatever way you typically would, we do not submit the records for you.
225
+
226
+ This callback also allows you to pass back any backend errors for specific rows. Each record passed to this callback will have a unique identifier under the key `record._meta.id`. In this case of a backend validation or error occurring, you can tell the importer to show a specific error to the user for a row. Note that after submission, only records with errors will remain visible to the user.
227
+
228
+ Return values:
229
+
230
+ - If there were no backend errors, pass back an empty errors object and a message to show to the user like so:
231
+
232
+ ```typescript
233
+ importer.onSubmit = async (records) => {
234
+ // submit to backend here
235
+ let message = "Data imported successfully";
236
+ return {
237
+ message,
238
+ errors: {},
239
+ };
240
+ };
241
+ ```
242
+
243
+ - If you find an error with a record in your backend, you can tell the importer to show the error to the user like so:
244
+
245
+ ```typescript
246
+ importer.onSubmit = async (records) => {
247
+ // submit to your backend here
248
+
249
+ return {
250
+ errors: {
251
+ [records[0]._meta.id]: {
252
+ email: "Email is already taken. Emails must be unique.",
253
+ first_name: "First Name must be capitalized.",
254
+ },
255
+ },
256
+ };
257
+ };
258
+ ```