Embed a new Space

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

Install packages

Make a new directory.

mkdir example-flatfile-react-embed

Go into that directory.

cd example-flatfile-react-embed

Follow prompts from the init command.

npm init

Install packages.

npm i @flatfile/react @flatfile/listener @flatfile/plugin-record-hook @flatfile/api flatfile react react-dom react-scripts

Create your file structure

Setup your app to look something like this:

├── public/
   └── index.html
   └── styles.css
├── src/
   └── App.tsx
   └── index.tsx
   └── workbook.ts (wait to add this)
   └── listener.ts (wait to add this)
├── tsconfig.json
├── package.json <--- already created
└── package-lock.json <--- already created

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 App.tsx file, which initializes Flatfile and passes in available options.

Build your importer

1. Add a Flatfile button

Add a button to your application to open Flatfile 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" />
    <meta name="theme-color" content="#000000" />
    <meta
      name="description"
      content="Web site created using create-react-app"
    />
    <!--
      manifest.json provides metadata used when your web app is installed on a
      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
    -->
    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
    <!--
      Notice the use of %PUBLIC_URL% in the tags above.
      It will be replaced with the URL of the `public` folder during the build.
      Only files inside the `public` folder can be referenced from the HTML.

      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
      work correctly both with client-side routing and a non-root public URL.
      Learn how to configure a non-root public URL by running `npm run build`.
    -->

    <link rel="stylesheet" type="text/css" href="./styles.css" />

    <title>React App</title>

  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <!--
      This HTML file is a template.
      If you open it directly in the browser, you will see an empty page.

      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

      To begin the development, run `npm start` or `yarn start`.
      To create a production bundle, use `npm run build` or `yarn build`.
    -->

  </body>
</html>

2. Initialize Flatfile

In your App.tsx, at minimum, you’ll need to pass in the publishableKey. Also, add the content here to your index.tsx, tsconfig.json, manifest.json, and config-overries.js.

import { Dispatch, SetStateAction, useState } from "react";
import { ISpace, initializeFlatfile } from "@flatfile/react";
import { workbook } from "./workbook";
import { listener } from "./listeners/simple";

export default function App() {
  const spaceProps: ISpace = {
    name: "Embedded Space",
    publishableKey: "pk_1234",
  };

  const [showSpace, setShowSpace] = useState(false);

  const { Space, OpenEmbed } = initializeFlatfile({
    ...spaceProps,
    sidebarConfig: {
      showSidebar: false,
    },
    closeSpace: {
      operation: "submitActionFg",
      onClose: () => setShowSpace(false),
    },
  });

  const onOpenSpace = async () => {
    setShowSpace(!showSpace);
    await OpenEmbed();
  };

  return (
    <div className="content">
      <h2>
        <code>&lt;Flatfile /&gt;</code>
      </h2>
      <p>Embed Flatfile in just a few lines of code.</p>
      {/*Button to trigger the modal */}
      <div>
        <button className="contrast" onClick={onOpenSpace}>
          {showSpace === true ? "Close" : "Open and create new"} Space
        </button>
        {showSpace && <Space />}
      </div>
    </div>
  );
}

3. Start your client

Update your package.json to include this script:

"scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
}

Now, start your front end by heading to terminal and running the following command.

npm run start

You’ll get an alert: We’re unable to detect target browsers. Would you like to add the defaults to your package.json? Say yes.

To see that it’s running, visit: https://localhost:3000 (or the port it is running on) and you should see your page and a button. Click the button and see that an empty Space gets created.

4. Build a Workbook

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

Add a src/workbook.ts file with this simple Blueprint.
Update App.tsx 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.

import { Flatfile } from "@flatfile/api";

export const workbook: Flatfile.CreateWorkbookConfig = {
  name: "All Data",
  labels: ["pinned"],
  sheets: [
    {
      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",
        },
      ],
    },
  ],
  actions: [
    {
      operation: "submitActionFg",
      mode: "foreground",
      label: "Submit foreground",
      description: "Submit data to webhook.site",
      primary: true,
    },
  ],
};

5. Transform Data

Next, we'll listen for data changes and respond using an event listener.

Add a src/listener.ts file with this simple recordHook.
Update App.tsx to import the listener.

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.

import { FlatfileListener } from "@flatfile/listener";
import api from "@flatfile/api";
import { recordHook } from "@flatfile/plugin-record-hook";

/**
 * Example Listener
 */
export const listener = FlatfileListener.create((listener) => {
  listener.on("**", (event) => {
    console.log(`Received event: ${event.topic}`);
  });

  listener.use(
    recordHook("contacts", (record) => {
      const firstName = record.get("firstName");
      console.log({ firstName });
      record.set("lastName", "Rock");
      return record;
    })
  );
});

6. Match your brand

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

src/App.tsx (snippet)

  const space = useSpace({
    ...spaceProps,
    workbook,
    listener,
    sidebarConfig: {
      showSidebar: false,
    },
    themeConfig: {
      root: {
        primaryColor: "red",
      },
      sidebar: {
        logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
      },
    },
    closeSpace: {
      operation: "contacts:submit",
      onClose: () => setShowSpace(false),
    },
  });
  return space;
};

7. Set the destination

Finally, let's get the data out of our system and to your destination.

Update your listener.ts with this simple submit action.

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

src/listener.ts

import { FlatfileListener } from "@flatfile/listener";
import api from "@flatfile/api";
import { recordHook } from "@flatfile/plugin-record-hook";

/**
 * Example Listener
 */
export const listener = FlatfileListener.create((listener) => {
  listener.on("**", (event) => {
    console.log(`Received event: ${event.topic}`);
  });

  listener.use(
    recordHook("contacts", (record) => {
      const firstName = record.get("firstName");
      console.log({ firstName });
      record.set("lastName", "Rock");
      return record;
    })
  );

  listener.on(
    "job:ready",
    { job: "workbook:submitActionFg" },
    async ({ context: { jobId } }) => {
      try {
        await api.jobs.ack(jobId, {
          info: "Getting started.",
          progress: 10,
        });

        // Make changes after cells in a Sheet have been updated
        console.log("Make changes here when an action is clicked");

        await api.jobs.complete(jobId, {
          outcome: {
            acknowledge: true,
            message: "This is now complete.",
            next: {
              type: "wait",
            },
          },
        });
      } catch (error: any) {
        console.error("Error:", error.stack);

        await api.jobs.fail(jobId, {
          outcome: {
            message: "This job encountered an error.",
          },
        });
      }
    }
  );
});

8. Add customizations

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

Example Project

Find this React example project in the Flatfile GitHub repository.

create-flatfile-react

Clone the Flatfile React tutorial here.

Quickstart Before you begin

On this page

Before you begin
Get your keys
Prepare your project
Install packages
Create your file structure
Build your importer
1. Add a Flatfile button
2. Initialize Flatfile
3. Start your client
4. Build a Workbook
5. Transform Data
6. Match your brand
7. Set the destination
8. Add customizations
Example Project

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

Install packages

Make a new directory.

mkdir example-flatfile-react-embed

Go into that directory.

cd example-flatfile-react-embed

Follow prompts from the init command.

npm init

Install packages.

npm i @flatfile/react @flatfile/listener @flatfile/plugin-record-hook @flatfile/api flatfile react react-dom react-scripts

Create your file structure

Setup your app to look something like this:

├── public/
   └── index.html
   └── styles.css
├── src/
   └── App.tsx
   └── index.tsx
   └── workbook.ts (wait to add this)
   └── listener.ts (wait to add this)
├── tsconfig.json
├── package.json <--- already created
└── package-lock.json <--- already created

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 App.tsx file, which initializes Flatfile and passes in available options.

Build your importer

1. Add a Flatfile button

Add a button to your application to open Flatfile 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" />
    <meta name="theme-color" content="#000000" />
    <meta
      name="description"
      content="Web site created using create-react-app"
    />
    <!--
      manifest.json provides metadata used when your web app is installed on a
      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
    -->
    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
    <!--
      Notice the use of %PUBLIC_URL% in the tags above.
      It will be replaced with the URL of the `public` folder during the build.
      Only files inside the `public` folder can be referenced from the HTML.

      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
      work correctly both with client-side routing and a non-root public URL.
      Learn how to configure a non-root public URL by running `npm run build`.
    -->

    <link rel="stylesheet" type="text/css" href="./styles.css" />

    <title>React App</title>

  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <!--
      This HTML file is a template.
      If you open it directly in the browser, you will see an empty page.

      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

      To begin the development, run `npm start` or `yarn start`.
      To create a production bundle, use `npm run build` or `yarn build`.
    -->

  </body>
</html>

2. Initialize Flatfile

In your App.tsx, at minimum, you’ll need to pass in the publishableKey. Also, add the content here to your index.tsx, tsconfig.json, manifest.json, and config-overries.js.

import { Dispatch, SetStateAction, useState } from "react";
import { ISpace, initializeFlatfile } from "@flatfile/react";
import { workbook } from "./workbook";
import { listener } from "./listeners/simple";

export default function App() {
  const spaceProps: ISpace = {
    name: "Embedded Space",
    publishableKey: "pk_1234",
  };

  const [showSpace, setShowSpace] = useState(false);

  const { Space, OpenEmbed } = initializeFlatfile({
    ...spaceProps,
    sidebarConfig: {
      showSidebar: false,
    },
    closeSpace: {
      operation: "submitActionFg",
      onClose: () => setShowSpace(false),
    },
  });

  const onOpenSpace = async () => {
    setShowSpace(!showSpace);
    await OpenEmbed();
  };

  return (
    <div className="content">
      <h2>
        <code>&lt;Flatfile /&gt;</code>
      </h2>
      <p>Embed Flatfile in just a few lines of code.</p>
      {/*Button to trigger the modal */}
      <div>
        <button className="contrast" onClick={onOpenSpace}>
          {showSpace === true ? "Close" : "Open and create new"} Space
        </button>
        {showSpace && <Space />}
      </div>
    </div>
  );
}

3. Start your client

Update your package.json to include this script:

"scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
}

Now, start your front end by heading to terminal and running the following command.

npm run start

You’ll get an alert: We’re unable to detect target browsers. Would you like to add the defaults to your package.json? Say yes.

To see that it’s running, visit: https://localhost:3000 (or the port it is running on) and you should see your page and a button. Click the button and see that an empty Space gets created.

4. Build a Workbook

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

Add a src/workbook.ts file with this simple Blueprint.
Update App.tsx to import the Workbook.

import { Flatfile } from "@flatfile/api";

export const workbook: Flatfile.CreateWorkbookConfig = {
  name: "All Data",
  labels: ["pinned"],
  sheets: [
    {
      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",
        },
      ],
    },
  ],
  actions: [
    {
      operation: "submitActionFg",
      mode: "foreground",
      label: "Submit foreground",
      description: "Submit data to webhook.site",
      primary: true,
    },
  ],
};

5. Transform Data

Next, we'll listen for data changes and respond using an event listener.

Add a src/listener.ts file with this simple recordHook.
Update App.tsx to import the listener.

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.

import { FlatfileListener } from "@flatfile/listener";
import api from "@flatfile/api";
import { recordHook } from "@flatfile/plugin-record-hook";

/**
 * Example Listener
 */
export const listener = FlatfileListener.create((listener) => {
  listener.on("**", (event) => {
    console.log(`Received event: ${event.topic}`);
  });

  listener.use(
    recordHook("contacts", (record) => {
      const firstName = record.get("firstName");
      console.log({ firstName });
      record.set("lastName", "Rock");
      return record;
    })
  );
});

6. Match your brand

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

src/App.tsx (snippet)

  const space = useSpace({
    ...spaceProps,
    workbook,
    listener,
    sidebarConfig: {
      showSidebar: false,
    },
    themeConfig: {
      root: {
        primaryColor: "red",
      },
      sidebar: {
        logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
      },
    },
    closeSpace: {
      operation: "contacts:submit",
      onClose: () => setShowSpace(false),
    },
  });
  return space;
};

7. Set the destination

Finally, let's get the data out of our system and to your destination.

Update your listener.ts with this simple submit action.

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

src/listener.ts

import { FlatfileListener } from "@flatfile/listener";
import api from "@flatfile/api";
import { recordHook } from "@flatfile/plugin-record-hook";

/**
 * Example Listener
 */
export const listener = FlatfileListener.create((listener) => {
  listener.on("**", (event) => {
    console.log(`Received event: ${event.topic}`);
  });

  listener.use(
    recordHook("contacts", (record) => {
      const firstName = record.get("firstName");
      console.log({ firstName });
      record.set("lastName", "Rock");
      return record;
    })
  );

  listener.on(
    "job:ready",
    { job: "workbook:submitActionFg" },
    async ({ context: { jobId } }) => {
      try {
        await api.jobs.ack(jobId, {
          info: "Getting started.",
          progress: 10,
        });

        // Make changes after cells in a Sheet have been updated
        console.log("Make changes here when an action is clicked");

        await api.jobs.complete(jobId, {
          outcome: {
            acknowledge: true,
            message: "This is now complete.",
            next: {
              type: "wait",
            },
          },
        });
      } catch (error: any) {
        console.error("Error:", error.stack);

        await api.jobs.fail(jobId, {
          outcome: {
            message: "This job encountered an error.",
          },
        });
      }
    }
  );
});

8. Add customizations

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

Example Project

Find this React example project in the Flatfile GitHub repository.

create-flatfile-react

Clone the Flatfile React tutorial here.

Quickstart Before you begin

On this page

Before you begin
Get your keys
Prepare your project
Install packages
Create your file structure
Build your importer
1. Add a Flatfile button
2. Initialize Flatfile
3. Start your client
4. Build a Workbook
5. Transform Data
6. Match your brand
7. Set the destination
8. Add customizations
Example Project

Before you begin

Get your keys

Prepare your project

Install packages

Create your file structure

Build your importer

1. Add a Flatfile button

2. Initialize Flatfile

3. Start your client

4. Build a Workbook

5. Transform Data

6. Match your brand

7. Set the destination

8. Add customizations

Example Project

create-flatfile-react

Documentation

Platform Apps

Orchestration

Automation

Embed a new Space

Before you begin

Get your keys

Prepare your project

Install packages

Create your file structure

Build your importer

1. Add a Flatfile button

2. Initialize Flatfile

3. Start your client

4. Build a Workbook

5. Transform Data

6. Match your brand

7. Set the destination

8. Add customizations

Example Project

create-flatfile-react

​Before you begin

​Get your keys

​Prepare your project

​Install packages

​Create your file structure

​Build your importer

​1. Add a Flatfile button

​2. Initialize Flatfile

​3. Start your client

​4. Build a Workbook

​5. Transform Data

​6. Match your brand

​7. Set the destination

​8. Add customizations

​Example Project

create-flatfile-react

Documentation

Platform Apps

Orchestration

Automation

​Before you begin

​Get your keys

​Prepare your project

​Install packages

​Create your file structure

​Build your importer

​1. Add a Flatfile button

​2. Initialize Flatfile

​3. Start your client

​4. Build a Workbook

​5. Transform Data

​6. Match your brand

​7. Set the destination

​8. Add customizations

​Example Project

create-flatfile-react

Before you begin

Get your keys

Prepare your project

Install packages

Create your file structure

Build your importer

1. Add a Flatfile button

2. Initialize Flatfile

3. Start your client

4. Build a Workbook

5. Transform Data

6. Match your brand

7. Set the destination

8. Add customizations

Example Project

Before you begin

Get your keys

Prepare your project

Install packages

Create your file structure

Build your importer

1. Add a Flatfile button

2. Initialize Flatfile

3. Start your client

4. Build a Workbook

5. Transform Data

6. Match your brand

7. Set the destination

8. Add customizations

Example Project