Embed a new Space

Create a new Space every time Flatfile is opened.

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.

Follow prompts from the new command.

ng new create-flatfile-angular-embed

cd example-flatfile-angular-embed

npm i @flatfile/angular-sdk @flatfile/plugin-record-hook @flatfile/listener

Build your importer

1. Initialize Flatfile

In your app.component.ts you’ll need to pass in a minimum of the publishableKey.

src/app/app.component.ts

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, RouterOutlet, SpaceModule],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css'
})
export class AppComponent {
  title = 'create-flatfile-angular-embed';
  showSpace: boolean = false;

  constructor(private spaceService: SpaceService) {}

  toggleSpace() {
    this.spaceService.OpenEmbed();
    this.showSpace = !this.showSpace;
  }

  closeSpace() {
    this.showSpace = false;
  }

  spaceProps: ISpace = {
    name: 'my space!',
    publishableKey: 'sk_1234',
    closeSpace: {
      operation: 'submitActionFg',
      onClose: this.closeSpace.bind(this),
    },
    displayAsModal: true,
  }
}

2. Start your client

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

  npm run start

3. Build a workbook

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

Add your config.ts file, and place the following code in it. After you have done so, import the configuration to app.component.ts, and update spaceProps to have the value of config under workbook. This config file has the configuration settings for your workbook, so feel free to edit however necessary to meet your needs.

src/config.ts

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

  export const config: Pick<
    Flatfile.CreateWorkbookConfig,
    "name" | "sheets" | "actions"
  > = {
    name: "Employees workbook",
    sheets: [
      {
        name: "TestSheet",
        slug: "TestSheet",
        fields: [
          {
            key: "first_name",
            type: "string",
            label: "First name",
            constraints: [
              {
                type: "required",
              },
            ],
          },
          {
            key: "last_name",
            type: "string",
            label: "last name",
          },
          {
            key: "email",
            type: "string",
            label: "Email",
          },
        ],
        actions: [
          {
            label: "Join fields",
            operation: "TestSheet:join-fields",
            description: "Would you like to join fields?",
            mode: "foreground",
            confirm: true,
          },
        ],
      },
    ],
    actions: [
      {
        label: "Submit",
        operation: "TestSheet:submit",
        description: "Would you like to submit your workbook?",
        mode: "foreground",
        primary: true,
        confirm: true,
      },
    ],
  };

4. Transform Data

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

1. Add a src/listeners/listener.ts file with this simple recordHook.
2. Update app.component.ts 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. Learn more about Handling Data

src/listeners/listener.ts

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

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

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

  listener.filter({ job: "workbook:submitActionFg" }, (configure) => {
    configure.on("job:ready", 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.",
          },
        });
      }
    });
  });
});

5. Match your brand

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

  themeConfig: {
    root: {
      primaryColor: "red",
      textColor: "white",
      logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
    },
  },

6. 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 Angular example project in the Flatfile GitHub repository.

create-flatfile-angular

Clone the Flatfile Angular tutorial here.