Programmatically set up and configure a new Flatfile Space with workbooks, sheets, documents, and metadata from a single configuration object.
@flatfile/plugin-space-configure
plugin is designed to programmatically set up and configure a new Flatfile Space. It operates within a server-side listener, typically responding to the ‘space:configure’ event which is triggered when a new Space is created.
Its primary purpose is to define the entire structure of a Space from a single configuration object. This includes creating one or more Workbooks, defining their Sheets with specific fields and actions, setting Space-level properties like metadata and themes, and adding initial documents such as a welcome guide.
The plugin also includes a secondary utility, dataChecklistPlugin
, which can automatically generate and maintain a “Data Checklist” document within the Space. This document provides a summary of all the fields and data types defined in the Space’s workbooks, serving as a handy reference for users.
This plugin is essential for developers who want to create templatized, repeatable, or dynamically generated Space configurations for their users.
configureSpace
function takes a setup
object as its primary configuration. This can be a static object or a function that returns an object.
The setup
object has the following properties:
Partial<Flatfile.CreateWorkbookConfig>[]
[]
.Partial<Flatfile.SpaceConfig>
primaryWorkbookId
to the ID of the first workbook created. Other properties are unset by default.Flatfile.DocumentConfig[]
object
maintainWorkbookOrder
(boolean): If set to true
, the plugin will configure the Space’s sidebar to display the workbooks in the same order they are defined in the workbooks
array.{ maintainWorkbookOrder: false }
job:ready
event with the topic space:configure
. When triggered, it configures the Space according to the provided setup. It handles creating workbooks, updating the space with a primary workbook, and creating documents.
Parameters:
setupFactory
: Setup | (event: FlatfileEvent) => Setup | Promise<Setup>
callback
: (event: FlatfileEvent, workbookIds: string[], tick: TickFunction) => any | Promise<any>
(Optional)
event
: The original FlatfileEvent that triggered the job.workbookIds
: An array of strings containing the IDs of the workbooks that were created.tick
: A function to update the job’s progress percentage and message.(listener: FlatfileListener) => void
workbook:created
and workbook:updated
events, then inspects all workbooks and sheets to generate an HTML document summarizing the data model.
Parameters: None
Returns: (listener: FlatfileListener) => void
space:configure
job will show an error message detailing what went wrong.
Common issues include:
configureSpace
plugin is specifically tied to the space:configure
job topic. It will not run on other eventsdataChecklistPlugin
listens for workbook:created
and workbook:updated
events. It will automatically update its document if you add or change workbooks in the Space after the initial configuration@flatfile/plugin-job-handler
, which provides robust job management. If any of the API calls made by the plugin fail, the job handler will catch the error, mark the job as ‘failed’, and provide the error message in the Flatfile UIcallback
function, you are responsible for your own error handling. It is best practice to use try/catch
blocks. If you rethrow an error from the callback, the job will be marked as ‘failed’primaryWorkbookId
to the ID of the first workbook createdmaintainWorkbookOrder
is set to true