Getting started with Portal in JavaScript

It's easy to get started using Portal. For people using Javascript or jQuery, you have two distinct paths you can take. You can use our NPM package or a CDN to load Flatfile.

In this guide, we will use the bare minimum to get up and running with Flatfile, but in order to get the most out of Flatfile's Portal, continue to the next few pages in order to get data validation implemented.

note

You'll need a license key to continue. Log in to your account to access the Flatfile dashboard. Head to the Flows section in the left-hand navigation pane and find your license key under the Portal tab.

The Basics

Whether you're using the npm package and importing it into your code or working with static html files and the CDN, the very basics of how to work with Flatfile remain the same. The differences between the two implementations can be seen below in separate sections, but in this section, we will talk about each required piece of Flatfile.

note

If you're working with with static index.html files, you'll need to run some sort of a simple server in order to see Flatfile work locally. One of the simplest servers you can run is with a python server. If you have python installed (which comes included with most operating systems), then you can open a terminal or command line program, navigate to the directory where the index.html file is and run python -m SimpleHTTPServer 8000. Once the server is running, you'll be able to open a browser and go to localhost:8000 and see the served version of the webpage.

The first thing you will do is either import the Flatfile package or use a script tag to reference the CDN. Once that is complete, you'll need to start a new reference to the FlatfileImporter passing in your license key and the Flatfile options. The two required keys for the options are the type of import and the fields you'll want to have in your imports.

const importer = new FlatfileImporter("Replace me with your license key!", {
  type: "Import type",
  fields: [
    { label: "Name", key: "name" },
    { label: "Email", key: "email_address" },
  ],
});

One other required aspect of using Flatfile is referencing the user or customer with the setCustomer method. This helps you identify and match imports to their respective users from within your system. When calling the setCustomer method, you'll pass in an options which is a reference to the endUser object in our SDK. The only required key is the userId, but we recommend using all of the keys possible to help better identify the user uploading the files.

importer.setCustomer({
  userId: "54321",
  name: "John Doe",
  email: "john@doe.com",
  companyName: "Doe Industries",
  companyId: "12345",
});

The final piece to working with Flatfile is to start the import. When doing this, you will use the requestDataFromUser method to start the import which will create a Promise that you can chain with a .then() to grab your results and do something with them. You'll see here in this example that we have put this call inside of a function that we are using with a click event tied to an element with an id of 'flatfile-button'.

const startImport = () => {
  importer.requestDataFromUser().then(function (results) {
    console.log(results);
    // do something async with results
    new Promise(function resolve() {
      setTimeout(resolve, 1000);
    }).then(function () {
      importer.displaySuccess("Thank you for your import!");
    });
    importer.displayLoader("Custom loading message...");
  });
};

const flatfileButton = document.getElementById("flatfile-button");

flatfileButton.addEventListener("click", startImport);

Example using NPM

If you're using a modern framework like Angular or Vue (for React users, check out our React documentation and for Angular users, check out our Angular documentation), and for Vue.js users, check out our Vue.js documentation), or you have a nice build system like Webpack in place. You can install and use Flatfile as an external dependency via NPM. Also note that you'll need to use your license key. In the code snippet where it says, "Replace me with your license key!", you'll just want to replace the text inside the quotes with the license key you got from your dashboard above.

npm install @flatfile/adapter --save

Below is the full example. Do note that we are referencing an element with the id of flatfile-button and adding a click event to it in this example. In order for this to work properly, you will need some button or other element that matches this id.

import FlatfileImporter from "@flatfile/adapter";

const importer = new FlatfileImporter("Replace me with your license key!", {
  type: "Import type",
  fields: [
    { label: "Name", key: "name" },
    { label: "Email", key: "email_address" },
  ],
});

importer.setCustomer({
  userId: "54321",
  name: "John Doe",
  email: "john@doe.com",
  companyName: "Doe Industries",
  companyId: "12345",
});

const startImport = () => {
  importer.requestDataFromUser().then(function (results) {
    console.log(results);
    importer.displaySuccess("Thank you for your import!");
  });
};

const flatfileButton = document.getElementById("flatfile-button");

flatfileButton.addEventListener("click", startImport);

Example using CDN

The latest version of the package is available via CDN. You can add a script tag into your site/app and start using Flatfile. Add the following code before the ending </body> tag in your html.

<script src="https://unpkg.com/@flatfile/adapter/build/dist/index.min.js"></script>

Using a static html file

In the example below, you'll get a basic version of the Flatfile importer. Reminder, you'll need to use your license key. In the code snippet where it says, "Replace me with your license key!", you'll just want to replace the text inside the quotes with the license key you got from your dashboard above.

<!DOCTYPE html>
<html>
  <head>
    <title>Flatfile Test</title>
  </head>
  <body>
    <div>
      <button id="flatfile-button">Start Flatfile</button>
    </div>
    <script src="https://unpkg.com/@flatfile/adapter/build/dist/index.min.js"></script>
    <script>
      const importer = new FlatfileImporter(
        "Replace me with your license key!",
        {
          type: "Import type",
          fields: [
            { label: "Name", key: "name" },
            { label: "Email", key: "email_address" }
          ],
          managed: true
        }
      );

      importer.setCustomer({ userId: "54321", name: "John Doe", email: "john@doe.com", companyName: "Doe Industries", companyId: "12345" });

      const startImport = () => {
        importer.requestDataFromUser().then(function (results) {
          console.log(results);
          importer.displaySuccess("Thank you for your import!");
        });
      };

      const flatfileButton = document.getElementById("flatfile-button");

      flatfileButton.addEventListener("click", startImport);
    </script>
  </body>
</html>