Quickstart

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

For synchronous data import/exchange completed in one session, create a new Space each time Flatfile is opened. This suits situations where a clean slate for every interaction is preferred.

Before you begin

Get your keys

To complete this tutorial, you'll need to retrieve your Publishable key from your development environment.

Note: The Publishable Key is safe to be used in client-side applications as it has limited access to the Flatfile API.

Prepare your project

Create your file structure

Setup your app to look something like this:

├── public/
   └── index.html
   └── styles.css
├── src/
   └── blueprint.js

In this file structure, your app should have two main directories, public and src. The public directory contains the index.html file, which is the entry point of the application’s front-end, and the “style.css” file for styling the iframe. The src directory contains the main components and logic of the application, including the blueprint.js file, which defines your schema.

Build your importer

1. Initialize Flatfile

Initialize Flatfile to open in a modal. Pass in your publishableKey and a new Space will be created on each page load. Also, add the content here to your styles.css.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Hello, world!</title>
    <script src="https://unpkg.com/@flatfile/javascript@^0.3.1/dist/index.js"></script>
    <script src="../src/blueprint.js"></script>
    <link rel="stylesheet" type="text/css" href="./styles.css" />

    <script>
      window.onload = function () {
        FlatFileJavaScript.startFlatfile({
          publishableKey: "pk_1234",
          spaceBody: {
            namespace: "portal",
          },
          onSubmit: async ({ sheet }) => {
            const data = await sheet.allData();
            console.log("onSubmit", data);
          },
          onRecordHook: (record) => {
            const firstName = record.get("firstName");
            console.log({ firstName });
            record.set("lastName", "Rock");
            return record;
          },
          themeConfig: {
            root: {
              primaryColor: "red",
              textColor: "white",
              logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
            },
          },
        });
      };
    </script>
  </head>
</html>

:root {
  --ff-primary-color: #4c48ef !important;
  --ff-secondary-color: #616a7d !important;
  --ff-text-color: #090b2b !important;
  --ff-dialog-border-radius: 4px !important;
  --ff-border-radius: 5px !important;
  --ff-bg-fade: rgba(0, 0, 0, 0.2) !important;
}

/* The default mount element */
/* #flatfile_iFrameContainer {
} */

/* A div around the iframe that contains Flatfile */
/* .flatfile_iframe-wrapper {
} */

/* The actual iframe that contains Flatfile */
/* #flatfile_iframe {
} */

/* Begin style overrides for when Flatfile is displayed as a modal */

/* This class gets appended to the flatfile_iframe-wrapper div */
.flatfile_displayAsModal {
  padding: 50px !important;
  width: calc(100% - 100px) !important;
  height: calc(100vh - 100px) !important;
}

.flatfile_iframe-wrapper.flatfile_displayAsModal {
  background: var(--ff-bg-fade);
}

/* The close button in top right to close modal */
/* .flatfile_displayAsModal .flatfile-close-button {
} */

/* The icon for the close button in top right to close modal */
.flatfile_displayAsModal .flatfile-close-button svg {
  fill: var(--ff-secondary-color);
}

/* The actual iframe that contains Flatfile */
.flatfile_displayAsModal #flatfile_iframe {
  border-radius: var(--ff-border-radius);
}

/* Begin style overrides for when you cancel out of the Flatfile modal */

/* The outer container of the modal that opens when you cancel out of Flatfile */
.flatfile_outer-shell {
  background-color: var(--ff-bg-fade);
  border-radius: var(--ff-border-radius);
}

/* The inner container of the modal that opens when you cancel out of Flatfile */
/* .flatfile_inner-shell {
} */

/* The white box inside the modal that opens when you cancel out of Flatfile */
.flatfile_modal {
  border-radius: var(--ff-dialog-border-radius);
}

/* The container for the buttons you see in the close modal */
/* .flatfile_button-group {
} */

/* Style the buttons you see in the close modal */
/* .flatfile_button {
} */

/* The "yes, cancel" button you see in the close modal */
.flatfile_primary {
  border: 1px solid var(--ff-primary-color);
  background-color: var(--ff-primary-color);
  color: #fff;
}

/* The "no, stay" button you see in the close modal */
.flatfile_secondary {
  color: var(--ff-secondary-color);
}

/* The heading text you see in the close modal */
.flatfile_modal-heading {
  color: var(--ff-text-color);
}

/* The description text you see in the close modal */
.flatfile_modal-text {
  color: var(--ff-secondary-color);
}

/* End style overrides for when you cancel out of the Flatfile modal */

/* End style overrides for when Flatfile is displayed as a modal */

/* The container of the error component */
/* .ff_error_container {
}*/

/* The heading text you see in the error component */
/* .ff_error_heading {
}*/

/* The description text you see in the error component */
/* .ff_error_text {
}*/

2. Run in browser

Now, open index.html in a browser. You should see that Flatfile opens on page load and an empty Space gets created.

3. Build a Workbook

Now, let's build a Workbook inside the Space for next time.

Update your blueprint.js with this simple Blueprint.
Update index.html to import the Workbook.

Next time you open Flatfile, you'll see a Workbook called "Contacts" that has one Sheet with three fields. Your Workbook will also have a Submit action. We will configure this action in the next step.

const blueprint = {
  "name": "Contacts",
  "slug": "contacts",
  "fields": [
    {
      "key": "firstName",
      "type": "string",
      "label": "First Name"
    },
    {
      "key": "lastName",
      "type": "string",
      "label": "Last Name"
    },
    {
      "key": "email",
      "type": "string",
      "label": "Email"
    }
  ]
}

window.onload = function () {
  FlatFileJavaScript.startFlatfile({
    publishableKey: "pk_1234",
    spaceBody: {
      namespace: "portal",
    },
    sheet: blueprint,
  });
};

4. Set the destination

Finally, let's get the data out of our system and to your destination with onSubmit. Once you add this code, when the submit button is clicked, this will be the place you can egress your data. Learn more about Egress Out

public/index.html

window.onload = function () {
  FlatFileJavaScript.startFlatfile({
    publishableKey: "pk_1234",
    spaceBody: {
      namespace: "portal",
    },
    sheet: blueprint,
    onSubmit: async ({ sheet }) => {
      const data = await sheet.allData();
      console.log("onSubmit", data);
    },
  });
};

5. Transform Data

Next, we'll listen for data changes and respond onRecordHook, Once you add this code, when a change occurs, we'll log the entered first name and update the last name to "Rock." You'll immediately see this begin to work when you add or update any records. Learn more about Handling Data

public/index.html

window.onload = function () {
  FlatFileJavaScript.startFlatfile({
    publishableKey: "pk_1234",
    spaceBody: {
      namespace: "portal",
    },
    sheet: blueprint,
    onSubmit: async ({ sheet }) => {
      const data = await sheet.allData();
      console.log("onSubmit", data);
    },
    onRecordHook: (record) => {
      const firstName = record.get("firstName");
      console.log({ firstName });
      record.set("lastName", "Rock");
      return record;
    },
  });
};

6. Match your brand

By attaching a themeConfig, we will now override colors in your Space to match your brand. See all of the options here in the Theming Reference.

public/index.html

window.onload = function () {
  FlatFileJavaScript.startFlatfile({
    publishableKey: "pk_1234",
    spaceBody: {
      namespace: "portal",
    },
    sheet: blueprint,
    onSubmit: async ({ sheet }) => {
      const data = await sheet.allData();
      console.log("onSubmit", data);
    },
    onRecordHook: (record) => {
      const name = record.get("name");
      if (name) {
        record.set("name", name.toUpperCase());
        record.addInfo("name", "We updated the values to all uppercase");
      }
      return record;
    },
    themeConfig: {
      root: {
        primaryColor: "red",
        textColor: "white",
        logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
      },
    },
  });
};

7. Customize

You can stop here or you can view our full reference to see all the ways you can customize your importer.

Example Projects

Find these Javascript example projects in the Flatfile GitHub repository.

create-flatfile-javascript-simplified

Clone the simplified Flatfile Javascript tutorial using a CDN here.

create-flatfile-javascript

Want to get started? Clone the Flatfile JavaScript tutorial here.

Documentation

Platform Apps

Orchestration

Automation

Before you begin

Get your keys

Prepare your project

Create your file structure

Build your importer

1. Initialize Flatfile

2. Run in browser

3. Build a Workbook

4. Set the destination

5. Transform Data

6. Match your brand

7. Customize

Example Projects

create-flatfile-javascript-simplified

create-flatfile-javascript

​Before you begin

​Get your keys

​Prepare your project

​Create your file structure

​Build your importer

​1. Initialize Flatfile

​2. Run in browser

​3. Build a Workbook

​4. Set the destination

​5. Transform Data

​6. Match your brand

​7. Customize

​Example Projects

create-flatfile-javascript-simplified

create-flatfile-javascript

Before you begin

Get your keys

Prepare your project

Create your file structure

Build your importer

1. Initialize Flatfile

2. Run in browser

3. Build a Workbook

4. Set the destination

5. Transform Data

6. Match your brand

7. Customize

Example Projects