Quickstart - jQuery

Estimated install time: 15 min.

Overview

Getting your Importer properly configured and running can be challenging if you're not implementing the correct tools. In this quick start guide, you'll learn how to use methods that are accessible in jQuery's library to activate features of the Importer for ease-of-use. Along with our code examples, we'll discuss how to handle the data output and field configuration for desired output.

Obtain your license key

Before we begin we'll need to initialize the application, please have your License Key ready to start this process. You can find out how to obtain the key by navigating to the Licenses option under the Account settings.

AccountMenu

Accessing jQuery library

jQuery using CDN (Content Delivery Network)

https://jquery.com/download/#using-jquery-with-a-cdn


CDNs can offer a performance benefit by hosting jQuery on servers spread across the globe. This also offers an advantage that if the visitor to your webpage has already downloaded a copy of jQuery from the same CDN, it won't have to be re-downloaded.

via jquery.com


Here's an example of the script used to access the jQuery library depending on your preferred CDN host and version of jQuery. This script can be inserted before the ending </body> tag in your html file. In this snippet, the Google CDN is utilized with compressed jQuery library version 3.4.1

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>

Activate the Flatfile Importer

Using CDN

The latest version of the package is available via CDN so you can just drop it into your website and start using it. Add the following code before the ending </body> tag in your html

<script src="https://unpkg.com/flatfile-csv-importer/build/dist/index.min.js"></script>

Use the license key found in your Account settings here link back to Get license key

<script>
const LICENSE_KEY = 'PASTE YOUR KEY HERE'
</script>

Field configuration for desired output

Mapping a user's data to your data model can be a tedious process, in this section we'll discuss how to setup your importer and configure the fields according to your database. If you'd like more information on the extent of fields, please refer to this guide: Field Config

If the output you'd like to receive from your user looks like this below:

[
{ name: 'John Doe', email: '[email protected]' },
{ name: 'Jane Smith', email: '[email protected]'}
]

Configure the Importer with this simple setup here:

<script>
var importer = new FlatfileImporter(LICENSE_KEY, {
fields: [
{
label: 'Full Name',
key: 'name'
},
{
label: 'Email Address',
key: 'email'
}
],
})
</script>

This configuration tells Flatfile how to build the UI necessary to help a user map their data to your database. You can provide helpful validators and describe a field to help the user understand what type of data to input.

Here's an example of what your Importer will display with the configuration above with Full Name and Email Address

Screenshot1

How to handle the data output

Write a javascript function you can use to upload the output from Flatfile to your server

  • This creates a background request to your API
  • If you don't have an API already here's information on how to handle the data
  • Enable managed:true and then you can access the data directly from Flatfile's API / UI
function uploadData (data) {
return $.post('postbin url', data);
}

$.post(URL, data, callback); jQuery's POST method has the following parameters:

  • URL - path for data output, required
  • data - that is being passed, optional
  • callback - function, optional
$.post('/your/bulk-endpoint', results.data).then(function(res) {
importer.displaySuccess('Success!')
}, function(err) {
importer.displayError('There was a problem uploading this data.')
})

Success

Examples using jQuery in Importer

In the snippet below, we're using jQuery to invoke the openDataImporter function once the button ID import-button is clicked

$(function() {
$("#import-button").click(function() {
openDataImporter()
})
})

After the Importer is activated and the user has finished mapping, fixing and reviewing their imported data, they will click the complete button Complete

This action sends the data to your application by resolving the .requestDataFromUser() promise and triggering a complete event

function openDataImporter() {
importer.requestDataFromUser().then(function(results) {
importer.displayLoader()
//See S-Ouput1 below
$("#output").val(JSON.stringify(results.data, null, 2));
})
}

Example of rendering the data to your page in JSON format targeting the output ID

$("#output").val(JSON.stringify(results.data, null, 2));

S-Output1 S-Output1

Copy-Paste Example

<html>
<head>
<script type="text/javascript" src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
<script src="https://unpkg.com/flatfile-csv-importer/build/dist/index.min.js"></script>
</head>
<body class>
<div class="content">
<h1>Import your customers</h1>
<a href="/create new customers csv">Click here to download a sample CSV file of customers.</a>
<hr>
<button id="import-button">Import Customers</button>
<hr>
<input type="text" id="filename">
<hr>
<textarea id="output" cols="80" rows="20"></textarea>
</div>
<script>
FlatfileImporter.setMountUrl("https://www.flatfile.io/importer/:INSERT LICENSE KEY HERE")
</script>
<script type="text/javascript">
const custImporter = new FlatfileImporter('Insert License Key Here', {
fields: [{
label: 'First Name',
key: 'first_name',
isRequired: true
}, {
label: 'Last Name',
key: 'last_name',
isRequired: true
}, {
label: 'Email Address',
key: 'email',
isRequired: true,
validator: {
validate: 'regex_matches',
regex: 'email',
error: 'Must be in email format'
}
}
]
})
</script>
<script>
$(function() {
$("#import-button").click(function () {
custImporter.requestDataFromUser().then(function (result) {
custImporter.displayLoader()
$.post("/your/bulk-endpoint", results.data).then
(function(res) {
custImporter.displaySuccess()
$("#output").val(JSON.stringify(result.validData, null, 2));
$("#filename").val(result.filename);
},
}).catch(function (error) { /* Handle error here */ })
})
})
</script>
</body>
</html>

CodeSandbox Example