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!

Integrating Flatfile into a Bubble.io app involves embedding the provided Flatfile JavaScript code into an HTML element within Bubble.

​
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

​
1. Add the HTML Structure

Since Bubble doesn’t allow direct script tags in its HTML elements for security reasons, you’ll need to use Bubble’s “HTML” element to embed the HTML structure. In your Bubble editor, drag and drop an HTML element onto the page where you want the Flatfile integration.

​
2. Create a button

  1. From the design toolbox (usually on the left side of the screen), drag and drop a Button element onto your page.
  2. Once you’ve placed the button on the page, click on it to open its properties.
  3. Go to Settings > General > Check “Expose the option to set an ID attribute to HTML element”
  4. Set the ID of the button in the Properties for that button to: startFlatfileButton

​
Build your importer

​
1. Initialize Flatfile

Initialize Flatfile to open in a modal from your Bubble.io webpage. Pass in your publishableKey and a new Space will be created on each page load. Optionally, you can add styles inline above your <script> tag.

<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>
      function initializeFlatfile() {
        const startFlatfileButton = document.getElementById(
          "startFlatfileButton"
        );

        startFlatfileButton.addEventListener("click", function () {
          FlatFileJavaScript.startFlatfile({
            publishableKey: "pk_d694c973c59348ab8261251907bcfb29",
            spaceBody: {
              namespace: "portal",
            },
          });
        });
      }
      window.onload = initializeFlatfile;
    </script>
  </head>
</html>

​
2. Test the integration

  1. Look for the “Preview” button in the Bubble.io editor. This is usually located at the top right of the page, near the “Deploy” button.
  2. Click the “Preview” button. This will open a new tab or window in your browser showing how your page will look and function in a live environment.
  3. Click the button to Open Flatfile. You should see that Flatfile opens and an empty Space gets created.

​
3. Build a Workbook (via Flatfile Blueprint)

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

  1. Add the blueprint const right below the <script> tag.
  2. Update your startFlatfile function to import the Blueprint.

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"
    }
  ]
}

​
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
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
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
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;
  },
  themeConfig: {
    root: {
      primaryColor: "red",
      textColor: "white",
      logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
    },
  },
});

​
8. 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.

Using our API