Building a workspace
Last updated
Was this helpful?
Last updated
Was this helpful?
Before you can use a workspace, you'll have to build it. To do so, switch to edit mode using the top-right "Edit layout" button.
Components are the bricks of your workspace. To add a component, simply drag & drop it from the right-side component menu.
Naming your component can help you keep your workspace easy to understand and maintain. Components are given a default name upon creation, but this can be changed from the top-left of the settings panel of your component.
To delete a component, click on the ellipsis icon at the top-right of the settings panel of your component. In the dropdown, select "Delete component".
Deleting a component may impact other components. If this is the case, you'll be warned before proceeding.
Components to design your workspace in an intuitive way.
The section component lets you regroup multiple components into a single area.
It also enable you to drag the components inside altogether.
The tabs component can hold between 1 and 10 tabs.
Write anything you wish to display, then customize how it's displayed using the style options.
The link component lets you create a link on the workspace. There are 2 modes:
Custom: you can set the url you want, and in this url you can use the value of another component selected record. e.g.: https://mydomain/posts/{{collection1.selectedRecord.id}}
Redirect to record: clicking the link will redirect you on the record's detail page.
You can use the horizontal and vertical dividers to create a visual separation between components.
Components to set the context of your workspace.
Use the Search component to quickly select a record within a given Collection.
You can customize the field used to display the search results.
The collection component lets you visualize your data and select records in a workspace. There are 2 types for the collection component, Collection and Relationship.
The Collection type behaves as a regular collection in Forest Admin. You can select records, trigger actions, filter and so on.
The Relationship type lets you visualize your has-many relationships. To make it work, you need to use another workspace component as the source. Let's say you have a user collection, and one user can have multiple documents. You can use a search component to search for a user, and use the Collection Relationship component to list all the documents of a selected user.
For the 2 types of collection components, you can do the following (independently from the regular collection settings):
Add a custom filter on the collection
Add a custom sorting field and sorting order
Customize the displayed columns
Reorder the displayed columns
Disable the search, or the actions for this component
The Dropdown is a great UI classic. Here's how you can set it up:
Choose a mode between "Static", "Dynamic > Simple" and "Dynamic > Smart"
Static
In Static mode, you hard-code values. You may re-order them using the handles.
Dynamic > Simple
In Simple mode, you choose a collection, a field and optionally a filter: this defines the values that will appear in the dropdown.
Dynamic > Smart
Smart mode lets you fetch values from an external endpoint.
As explained in the tooltip, the expected response format is:
The date picker component lets your operator choose a date. You can set maximum and / or minimum dates that are enabled.
You can use the {{currentDate}} templating to ensure the selected date is in a good range, for example:
Minimum date: {{currentDate.subtract.days.1}}
Maximum date: {{currentDate.add.days.1}}
The toggle component can be used as an input, to dynamically filter another source component.
You have to pick a value type (String, Number, Boolean, etc..), then set the value the component will have when it has the toggled on state. The value of the toggle component is used only when toggled on.
Example:
Let's say you have a collection component using your Users collection. You can add many toggle components to enable quick filtering with combined filters on your collection component.
You can have a String toggle with value "onboarding" to filter the user status.
You can have a Boolean toggle with value true to filter on the user isEmailVerified field.
Or
You can create multiple Date toggle and use the templating for the value, like:
{{currentDate.startOf.months}}
{{currentDate.subtract.days.15}}
{{currentDate.startOf.days}}
And use these toggles in a OR filter on the collection component
The input component is an input.
You should use it when you want to dynamically filter a collection or a search component using a text or a number.
Components to interact with your data.
The Action component can be used to trigger global, single, and bulk Smart Actions as well as CRUD operations.
If you've selected an action that requires selected record(s) to apply to, then you'll need to specify a source component:
Here we have linked the action2 component so that when you select a record from thecollection1 component, you'll be able to trigger the Edit a company action in 1 click.
If you have a Collection component in your workspace, make sure its "On row click" option is set to "Select a record": this will allow you to select a record in your table, which in turn feeds the Field component.
In the Field component, select collection1 as the source and choose which field value you wish to display: here we chose name.
You may have a more complex use case, where you'd want to display a property further away. To achieve this, you'll have to click the Toggle to input code button:
For instance, if your collection is Company and it is linked to a Country collection, you may want to display {{country.name}} or even {{country.headquarter.address}}.
Widgets & labels
Lastly you may also choose whether to display the label and customize it.
Components to visualize your data.
All you have to do to embed your Metabase dashboard into Forest Admin workspace is to create a new Metabase component and fill in all necesary informations.
Url
This corresponds to the url of your Metabase instance. For example, if your Metabase instance is accessible through https://myanalytics.mycompany.com, then you must set it to the url option.
Token
The token is a JWT token and ensures valid authentication when retrieving the Metabase dashboard. The simplest way to do this is to generate it online using https://token.dev. To sign it, you need to use the METABASE_SECRET_KEY provided by Metabase.
You must replace METABASE_DASHBOARD_ID by the correct dashboard ID provided by Metabase.
JWT Payload:
Query
Here are the parameters that the dashboard can take into account. This is a basic query string based input that can interact with workspace context.
For example if your dashboard take projectId as parameters, you can put the following as option input.
or
This opens an autocomplete dropdown which helps you use the correct syntax.
Here are some examples:
{{collection1.selectedRecord.email}}
Displays the column "email" of the select row of collection1
{{currentUser.fullName}}
Displays the current user's fullname
{{currentUser.email}}
Displays the current user's email
{{currentUser.team}}
Displays the current user's team
{{currentUser.tags.some-tag}}
Displays the current user's value of the tag "some-tag"
{{currentDate.option}}
Displays a date manipulated from the current date
If you rename your components, the syntax adjusts automatically in all components using templating.
Templating is also useful within the Chart component: you may use other components' data to filter on your chart(s).
For instance, if you want to display the number of fast boats belonging to a user, you may use a Collection component in combination with a "Single Value" chart with a filter set up as below:
Templating also works within Query mode, i.e within your SQL queries, like so:
Bonus: it's also possible to use templating in the Timeframe property of Time-based charts. This means that you could for instance create a Dropdown component with values Day, Week, Month and Year and using that dropdown would automatically refresh the chart based on the selected timeframe!
This is how you would set it up:
Every component has a Visible option - at the bottom of its settings panel - which allows you to control when it is displayed:
The default choice is Always, but there are 2 other options that we'll explain shortly:
Only when a component is visible
Only when dynamic variables are defined / Only when source record is selected
This lets you basically select another component and make your component visible when that other component is.
A pretty basic example of this is if you want to show dividers only if the component they are splitting the view for is visible.
Similarly, you can make a Section component hidden unless a component inside of it is displayed.
Here's an example:
:pointup: This is a Collection component (collection2) that is filtered on another Collection component (collection1). See how the filter contains _dynamic variables (a.k.a templating)? Well, choosing the "Only when dynamic variables are defined" option means collection2 will appear only if a record of collection1 is selected.
For components with style options, you can change the color, the font, the alignment and the formatting of the displayed text.
It enables you to configure the for all the components inside only through the Section component.
Like the , the tabs components lets you regroup multiple components into a single area, only the active tab components are displayed.
You can add on this component.
You can add on this component.
You can add on this component.
You can use this component as a source for other components (, , ) or use it in filters.
You can use this component as a source for other components (, , ) or use it in filters.
The inbox component lets your operator treat their tasks directly from a workspace.
You can use this component as a source for other components (, , ) or use it in filters.
Minimum and maximum dates can be hardcoded or use to get a date from a selected record.
The Field component lets you read data of a record that you selected in a component.
Note that you may also choose which to use to display your field.
Some of your components display data. You may want this data to influence other components. If you've read the section above, you've seen a simple way to make that happen. But there is another way: using templating.
Templating is pseudo-code that will fetch the piece of data you want from a component.
To start using it, simply type {{ in a text input:
This feature is only available from version 9.0.0 for Express/Sequelize and Express/Mongoose and version 1.4.0 for agent-nodejs. If you're seeing this tooltip, you must upgrade first to benefit from the feature
As covered in the section above, components can be set up to depend on information from another component, using templating. This visibility option makes it so that the component is visible only if information from the other component it depends on is available.
