Build Documents

Documents are standalone webpages for your Flatfile Spaces. They can be rendered from Markdown syntax.

Often used for getting started guides, Documents become extremely powerful with dynamically generated content that stays updated as Events occur.

​

Create a Document

You can create Documents using the API:

import api from "@flatfile/api";

export default function flatfileEventListener(listener) {
  listener.on("file:created", async ({ context: { spaceId, fileId } }) => {
    const fileName = (await api.files.get(fileId)).data.name;
    const bodyText = `# Welcome
    ### Say hello to your first customer Space in the new Flatfile!
    Let's begin by first getting acquainted with what you're seeing in your Space initially.
    ---
    Your uploaded file, ${fileName}, is located in the Files area.`;

    const doc = await api.documents.create(spaceId, {
      title: "Getting Started",
      body: bodyText,
    });
  });
}

See full code example in our flatfile-docs-kitchen-sink Github repo.

This Document will now appear in the sidebar of your Space.

In this example, we create a Document when a file is uploaded, but you can also create Documents in response to any other Event. Read more about the different Events you can respond to.

​

Document Actions

Actions are optional and allow you to run custom operations in response to a user-triggered event from within a Document.

Define Actions on a Document using the actions parameter when a document is created:

import api from "@flatfile/api";

export default function flatfileEventListener(listener) {
  listener.on("upload:completed", async ({ context: { spaceId, fileId } }) => {
    const fileName = (await api.files.get(fileId)).data.name;
    const bodyText = `# Welcome
    ### Say hello to your first customer Space in the new Flatfile!
    Let's begin by first getting acquainted with what you're seeing in your Space initially.
    ---
    Your uploaded file, ${fileName}, is located in the Files area.`;

    const doc = await api.documents.create(spaceId, {
      title: "Getting Started",
      body: bodyText,
      actions: [
        {
          label: "Submit",
          operation: "contacts:submit",
          description: "Would you like to submit the contact data?",
          tooltip: "Submit the contact data",
          mode: "foreground",
          primary: true,
          confirm: true,
        },
      ],
    });
  });
}

See full code example in our flatfile-docs-kitchen-sink Github repo.

Then configure your listener to handle this Action, and define what should happen in response. Read more about Actions and how to handle them here.

Actions appear as buttons in the top right corner of your Document:

​

Document treatments

Documents have an optional treatments parameter which takes an array of treatments for your Document. Treatments can be used to categorize your Document. Certain treatments will cause your Document to look or behave differently.

​

Ephemeral documents

Giving your Document a treatment of "ephemeral" will cause the Document to appear as a full-screen takeover, and it will not appear in the sidebar of your Space like other Documents. You can use ephemeral Documents to create a more focused experience for your end users.

const ephemeralDoc = await api.documents.create(spaceId, {
  title: 'Getting started',
  body: '# Welcome ...',
  treatments: ['ephemeral'],
})

​

Adding Blocks to Documents

Blocks are dynamic, embedded entities that you can use to display data inside a Document. You can add a Block to a Document using the <embed> HTML entity in your markdown and specifying which Block type you want to show using the type attribute on the entity. Two Block types are currently supported: Embedded Sheet and Embedded Diff.

​

Embedded Sheet

Use this Block to render a Sheet along with all its data inside of a Document. You can embed a Sheet into your Document by passing a sheet ID, workbook ID, and name. You can also specify whether the embedded Sheet is expanded or collapsed when the document is loaded.

const doc = await api.documents.create(spaceId, {
  title: 'Getting started',
  body: `
    # Welcome
    
    Here is an embedded Sheet:
    
    <embed type='embedded-sheet' name='Contacts' defaultExpanded='true' sheetId='your_sheet_id' workbookId='your_workbook_id'>

    Here is another embedded Sheet:

    <embed type='embedded-sheet' name='Countries' sheetId='us_sh_TVW95224' workbookId='us_wb_8e0z52gI'>
  `,
})

​

Embedded Diff

Use this Block to show a side-by-side comparison of the data in a Sheet now versus at a previous point in time as captured by a Snapshot. Pass a Sheet ID, Workbook ID, and Snapshot ID. You can optionally pass a direction attribute which specified whether the changes are displayed with the Snapshot as the end state (sheet_to_snapshot) or the Sheet as the end state (snapshot_to_sheet). The default value for direction is sheet_to_snapshot.

const doc = await api.documents.create(spaceId, {
  title: 'Getting started',
  body: `
    # Welcome
    
    Here is an embedded Diff:
    
    <embed type='embedded-diff' sheetId='your_sheet_id' workbookId='your_workbook_id' snapshot_id='your_snapshot_id" direction="snapshot_to_sheet">
  `,
})

​

Markdown reference

Documents support Github-flavored Markdown. Check out this guide for a full reference on the entities you can use.

​

Example Project

Find the documents example in the Flatfile GitHub repository.