Forest instantly provides all common admin tasks such as CRUD operations, simple chart rendering, user group management, and WYSIWYG interface editor. That’s what makes Forest a quick and easy solution to get your admin interface started.
This guide assists developers in having the admin completely tailored to cater to their specific needs. We’ve developed Forest so that your admin is 100% customizable. It means that you have full control over your data, your back-end business logic and the UI.
Forest provides a very simple API-based framework to handle all parts of your admin back-end configuration. You should be good to go in no time, with virtually no investments of time and resources.
This documentation is entirely based on the Forest Live Demo project using Rails 5 and hosted on Github here. A database dump (PostgreSQL) is also available if you want to run the Live Demo on your side. This project tends to illustrate with working examples all the possible features and available options. Please refer to the data model below every time you need it to get a global overview of the collections and relationships used everywhere in our examples.
Forest allows to handle even the most complex scenarios. The Smart label enables you to implement your own business logic with code, when necessary. Check this page out for more details on all Smart features
Term | Definition |
---|---|
Admin API | The API generated by the Forest Liana to manage all your application data and business operations. |
Collection | A set of records having the same type usually stored in the database. |
Data Token | A token used to authenticate your requests on your Admin API. |
Field | An attribute of a collection. |
Forest Liana | The locally-installed plugin that analyzes your data model and generates the Admin API |
Forest UI | The web application of Forest Admin, accessible from any browser at https://app.forestadmin.com |
Forest UI Schema | A schema of your data model generated by the Forest Liana in order to initialize your Forest UI |
FOREST_AUTH_SECRET | A private token - chosen by yourself - used to sign the data token. |
FOREST_ENV_SECRET | A private token - given by Forest Admin - used to identify your project environment in Forest. |
DATABASE_URL | The path to the database used by your app. |
Relationship | A connection between two collections. |
Segment | A subset of a collection gathering filtered records. |
Smart Action | A button that triggers server-side logic. |
Smart Collection | A group of records gathered from different sources and implemented following your business logic. |
Smart Field | A field that displays a computed value in your collection |
Smart Relationship | A relationship that displays a link to another collection. |
Smart Route | A route is simply the mapping between an API endpoint and the business logic behind this endpoint. |
Smart View | A custom view you can code using HTML/CSS/JSS to display data in any way you want. |
For the purpose of this guide and our Live Demo, we use third parties librairies that will be present in our coding examples:
Before you start writing a single line of code, it’s a good idea to get an overview of how Forest with Rails works. The magic of Forest lies in its architecture. Forest is divided into two main components:
When you launch your Rails application, the Forest Liana sends a schema - the Forest UI Schema - to the Forest’s servers to initialize the UI.
The main advantage of Forest’s architecture is that absolutely no data transits or crosses our servers. The user accesses application data directly from the client and Forest is just deployed as a service to display and interact with the data. Read more about hosting.
With Forest, your data are transferred directly from your application to your browser while remaining invisible to our servers. See how it works.
We use a two-step authentication to connect you to both Forest’s server and your Admin API.
The first step is to retrieve your UI configuration. When logging into your account, your credentials are sent to the Forest’s server which returns the UI token to authenticate your session.
The second step is to authenticate to your Rails app to get access to your data. Your password is sent to your Admin API which returns the data token signed by the FOREST_AUTH_SECRET you chose. Each of your requests to your Admin API are authenticated with the Data Token.
In a nutshell, your admin uses the UI token to make request about the UI configuration. Then the Data Token is used to make queries on your Admin API to manage your data. All our tokens are generated using the JWT standard.
If you haven’t done it yet, you should have Forest installed on your application. The relevant information is below. You should be set up in no more than a few minutes. If you encounter any issue, feel free to drop us a line at support@forestadmin.com or using the live chat available on our homepage.
After installing and customizing (see all the sections below) your admin, it’s time to deploy your Rails application to your production server. Then, you will be ready to onboard all your admin users and start using it in live.
After clicking on the “Deploy to production” link, you must provide your
FOREST_ENV_SECRET and the FOREST_AUTH_SECRET in the
environment variables of your production server. These variables are used in
the config/secrets.yml
file.
Then, fill the Application URL field. In our case, the Application URL is https://forest-live-demo.herokuapp.com.
We strongly recommend entering a HTTPS Application URL for security reason. Forest Admin will adapt its protocol based on your Application URL.
Last but not least, it wouldn’t be convenient to configure your UI from scratch again on your Forest Production environment. Forest gives you the possibility to copy the layout from one environment to another. Here, we will copy the Development environment layout to your Production environment.
You’re now ready to use Forest on production and invite all your teammates!
The Admin API is a REST API (encapsulated behind a Rails Engine) generated automatically by the Forest Liana when you launch your Rails application. This API covers all the common requirements of a fully functional Admin Interface (CRUD operations, search & filters, sort, pagination and more). The API is hosted on your side, so you have virtually no limitation to extend it.
However, to ease the customization of your admin, we’ve introduced the concept of Smart features which helps you to fully extend the API.
Before you start to deep dive into this documentation, it’s a good idea to see how the Admin API is designed.
Everytime you interact with your application data from the Forest UI, it
triggers an API call to your Rails admin backend. This API call is authenticated
using the Data Token. This token is a JWT token signed with
your FOREST_AUTH_SECRET
(see the Security section for more
information) and it is passed to the HTTP request through the Authorization
header.
The JWT Data Token contains all the details of the admin user. From a route,
you can retrieve them with the variable forest_user
. On our Live Demo example,
we’ve developed a Whoami
global Smart Action available that returns the full
name of the admin user.
You MUST configure the right
CORS headers to
allow the domain app.forestadmin.com
to trigger an API call on your
Application URL, which is a different domain name (e.g. localhost:3000 on
development).
We use the Rack CORS Gem for this purpose.
A route is simply the mapping between an API endpoint and the business logic behind this endpoint. In other words, the Admin API automatically generated by the Forest Liana consists of a series of routes.
Very often, you’ll need to be able to call business logic from your main/customer-facing application to avoid code duplication between your admin and your app. Another typical use case is simply to trigger a verification business logic before executing the logic.
So in summary, the Smart Route feature allows you to extend the default behavior of a Route.
On our Live Demo, we’ve overridden the DELETE
/forest/Company/:companyId
API call to only allow admin users that are part
of the Management
team. If you’re in the right team, we call simply
default_destroy
method to trigger the default destroy
implementation.
An action is a button that triggers server-side logic through an API call. Without a single line of code, Forest supports natively all common actions required on an admin interface such as CRUD (Create, Read, Update, Delete), sort, search, data export.
Sooner or later, you will need to perform actions on your data that are specific to your business. Moderating comments, logging into a customer’s account (a.k.a impersonate) or banning a user are exactly the kind of important tasks to unlock in order to manage your day-to-day operations.
On our Live Demo example, our Company
collection has many examples of Smart
Action. The simplest one is Mark as live
.
3 types of Smart Actions are available in Forest:
To specify the type of a Smart Action, use the option type.
On our Live Demo example, Mark as Live
is a Bulk Smart Action, Upload
Legal Docs
is a Single Smart Action and Import data
is a Global Smart
Action.
In the following example, the file lib/forest_liana/collections/company.rb
contains the Smart Action declaration. After declaring your Smart Action,
your Forest Admin UI will be updated with a new button baring the label of this
new action.
If you click on this new button, your browser will make an API call POST
/forest/actions/mask-as-live
. If you want to customize the call, check the
list of available options.
The payload of the HTTP request is based on a JSON API
document. The data.attributes.ids
key allows you to retrieve easily the
selected records from the UI and the data.attributes.values
key contains all
the values of your input fields (handling input values).
At this time, there’s no Smart Action Implementation because no route in
your Admin backend handles the API call yet. In the file
config/routes.rb
, we’ve declared a new route and we’ve implemented the business
logic behind the “Mark as Live” button in a new controller
/app/controllers/forest/companies_controller.rb
.
Forest takes care of the authentication thanks to the
ForestLiana::ApplicationController
parent class controller.
You MUST add the CORS headers to enable
the domain app.forestadmin.com
to trigger API call on your Application URL,
which is on a different domain name (e.g. localhost:3000).
The business logic in this Smart Action is extremely simple. We only update
here the attribute status
of the companies to the value live
.
Here are the list of available options to customize your Smart Action:
Name | Type | Description |
---|---|---|
type | string | (optional) Type of the action. Can be bulk , global or single . Default is bulk . Check the different types of Smart Actions section for more details. |
fields | array of objects | (optional) Check the handling input values section. |
download | boolean | (optional) If true , the action triggers a file download in the Browser. Default is false |
endpoint | string | (optional) Set the API route to call when clicking on the Smart Action. Default is 'forest/actions/name-of-the-action-dasherized' |
http_method | string | (optional) Set the HTTP method to use when clicking on the Smart Action. Default is POST . |
Very often, you will need to ask user inputs before triggering the logic behind a Smart Action.
For example, you might want to specify a reason if you want to block a user
account. Or set the amount to charge a user’s credit card. On our Live Demo
example, we’ve defined 4 input fields on the Smart Action Upload Legal Docs
on the collection Company
.
Here are the complete list of available options to customize your input form.
Name | Type | Description |
---|---|---|
field | string | Label of the input field. |
type | string | Type of the input field. Can be Boolean , Date , Number , String , File or Enum . |
enums | array of strings | (optional) Required only for the Enum type. This is where you list all the possible values for your input field. |
description | array of fields | (optional) Add a description for your admin users to help them fill correctly your form |
isRequired | boolean | (optional) If true , your input field will be set as required in the browser. Default is false . |
Forest Admin allows you to set default values to your form. In this example, we will prefill the form with data coming from the record itself (1), with just a few extra lines of code. We base ourselves on the Charge credit card
action which is used in the ‘Custom HTML response’ section a few lines below.
Returning a 204 status code to the HTTP request of the Smart Action shows the default notification message in the browser.
On our Live Demo example, if our Smart Action Mark as Live
route is implemented like this:
We will see a success message in the browser”
If we return a 200 status code with an object { success: '...' }
as the payload like this…
… the success notification will look like this:
Finally, returning a 400 status code allows you to return errors properly.
You can also return a HTML page as a response to give more feedback to the
admin user who has triggered your Smart Action. To do this, you just need to
return a 200 status code with an object { html: '...' }
.
On our Live Demo example, we’ve created a Charge credit card
Smart Action on
the Collection Customer
that returns a custom HTML response.
On our Live Demo, the collection Customer
has a Smart Action Generate
invoice
. In this use case, we want to download the generated PDF invoice
after clicking on the action. To indicate a Smart Action returns something to
download, you have to enable the option download
.
Don’t forget to expose the Content-Disposition
header in the CORS
configuration (as shown in the code below) to be able to customize the
filename to download.
Sometimes, you want to create a record in a related collection through a smart action done in a Summary view.
In the example below, the “Add new transaction” action (1) is accessible from the summary view (2). This action creates a new transaction and automatically refresh the “Emitted transactions” related data section (3) to see the new transaction.
Below is the sample code. We use the gem 'faker'
to easily generate fake data. Remember to add this gem to your Gemfile
and install it (bundle install
) if you wish to use it.
Sometimes, your Smart Action only makes sense depending on the state of
your records. On our Live Demo, it does not make any sense to enable the Mark
as Live
Smart Action on the Company
collection if the company is already
live, right?
In the collection settings, you can configure the UI options of your Smart Actions.
When using Forest with several teams and when you have clear roles defined it becomes relevant to restrict a smart action only to a few collaborators. This option is accessible through the Edit layout mode (1) in the Smart actions’ section (3) of the collection’s options (2), in a dropdown menu (4).
Enterprise-only
Critical actions for your business may need approval before being processed.
The option “This smart action requires an approval” (3) is accessible in the Smart action section (1) of your collection’s settings. In our example, the “Approve transaction” action (2) requires approval. You can select approvers among your users(4). Once this option is activated, a warning pop up indicates that the approval workflow is need to perform this action.
Actions requiring approval will be available in the Collaboration menu (5) in the “Approvals” section (6):
In “To Review” you will be able to reject or approve the request (8) with an optional message for more details.
You can access the detail on an action (9) to have more context (10) by clicking on it.
A field is simply an attribute defined in your database. Examples of fields:
first name
, gender
, status
, etc.
Forest allows you to customize how a field appears in your admin interface. You
can rename it, choose the right widget to display (e.g. text area
, image
viewer
, Google map
), add a description or even set the read/write access.
To customize a field, go to Collection Settings -> Fields, then select the field to start configuring it.
A field that displays a computed value in your collection.
A Smart Field is a column that displays processed-on-the-fly data. It can be as simple as concatenating attributes to make them human friendly, or more complex (e.g. total of orders).
On our Live Demo, the very simple Smart Field fullname
is available on the
Customer
collection.
Very often, the business logic behind the Smart Field is more complex and must
interact with the database. Here’s an example with the Smart Field
full_address
on the Customer
collection.
By default, your Smart Field is considered as read-only. If you want to update
a Smart Field, you just need to write the logic to “unzip” the data. Note
that the set method should always return the object it’s working on. In the
example hereunder, the user_params
is returned.
To perform a search on a Smart Field, you also need to write the logic to
“unzip” the data, then the search query which is specific to your zipping. In
the example hereunder, the firstname
and lastname
are searched separately
after having been unzipped.
⚠️ Note that, sorting on Smart Field is not supported in Forest. Indeed, being able to sort on Smart Field would mean that we have to compute the Smart Field values for all the records of your collection, and then sort the records on this value.
While this is something we could implement, it would not be something scalable. Imagine if your collection has millions of records.
If this sorting is really important for your operations, you should consider the creation of a dedicated column in the database.
Sometimes, searching on all fields is not relevant and may even involve big performance issues. You can restrict the search on specific fields only using the option searchFields
, which should be defined in your forest/
folder. In this example, we configure Forest to only search on the fields name
and industry
of our collection Company
.
Here are the list of available options to customize your Smart Field:
Name | Type | Description |
---|---|---|
field | string | The name of your Smart Field. |
type | string | Type of your field. Can be Boolean , Date , Enum , File , Number or String . |
enums | array of strings | (optional) Required only for the Enum type. This is where you list all the possible values for your input field. |
description | string | (optional) Add a description to your field. |
reference | string | (optional) Configure the Smart Field as a Smart Relationship. |
widget | string | (optional) Configure the widget to display in the browser. Can be color picker , document viewer , file picker , image viewer , JSON editor , link , map , price , rich text editor , text area or text input |
isReadOnly | boolean | (optional) If true , the Smart Field won’t be editable in the browser. Default is true if there’s no set option declared. |
isRequired | boolean | (optional) If true, your Smart Field will be set as required in the browser. Default is false. |
Note that if you are choosing the date picker
widget for a date field, you will be able to change the format
. Please refer to momentjs syntax for formatting options.
Widgets fields can be very handy and a great time saver to users with no technical knowledge. Depending on the type of your field, you can choose different widgets (see list below). You can find these options in your collection settings under the fields section.
Depending on the field type in your DB, you have different choices of Widgets available:
Type | Widget | Description |
---|---|---|
string | link | Display clickable link instead of a raw string |
text area | Enlarge the text area. | |
color picker | Change the field to a color picker (hexadecimal code). | |
image viewer | Display an image instead of a URL link. | |
file picker | Add a file from your computer. | |
rich text editor | Write formatted text. | |
JSON editor | Display a JSON field. | |
dropdown | Put a drop-down menu of fields among pre-defined options. | |
document viewer | Display your document in a preview window. | |
map | Display a location on a map (⚠️ your field must be a “string” respecting the following format “lat, long”). | |
address | Allow auto-complete on an address field. | |
date | text input | Convert your date into a string. |
date picker | Use the date picker to select a date. | |
number/integer | belongsTo select | Display a dropdown list of related data. |
price | Compute your number in the currency of your choice. | |
array | carrousel | Display an array of images URLs as a carrousel. |
You can see below some of the widgets and how they look:
A relationship is a connection between two collections.
Forest supports natively all the relationships defined in your ActiveRecord models
(belongsTo
, hasMany
, …). Check the Rails documentation to create new ones.
Sometimes, you want to create a virtual relationship between two set of data that does not exist in your database. A concrete example could be creating a relationship between two collections available in two different databases. Creating a Smart Relationship allows you to customize with code how your collections are linked together.
On the Live Demo example, we have an Order belongsTo a Customer
belongsTo an Address
. We’ve created here a BelongsTo Smart Relationship
that acts like a shortcut between the Order
and the delivery Address
.
A BelongsTo Smart Relationship is created like a Smart
Field with the reference
option to indicates on
which collection the Smart Relationship points to.
On the Live Demo example, we have a Product hasMany Orders
and an
Order belongsTo Customer
. We’ve created a Smart Relationship that
acts like a shortcut with Product hasMany Customer (buyers)
.
A HasMany Smart Relationship is created like a Smart
Field with the reference
option to indicates on
which collection the Smart Relationship points to.
Upon browsing, an API call is triggered when accessing the data of the HasMany
relationships in order to fetch them asynchronously. In the following example,
the API call is a GET on /Product/:product_id/relationships/buyers
.
We’ve built the right SQL query using Active Record to count and find all customers who bought the current product.
Then, you should handle pagination in order to avoid performance issue. The API call has a querystring available which gives you all the necessary parameters you need to enable pagination.
Finally, you don’t have to serialize the data yourself. The Forest Liana already
knows how to serialize your collection (Customer
in this example). You can
access to the serializer through the serialize_models()
function.
A collection is a set of data elements physically stored in the database displayed in tabular form (by default), with rows (i.e. records) and columns named (i.e. fields). A collection has a specified number of columns, but can have any number of rows.
Forest automatically analyses your data models and instantly make your collections available in the Forest UI. It covers the majority of use cases. If needed, you can create a Smart Collection to go one step further in the customization of your admin.
A Smart Collection is a Forest Collection based on your API implementation. It allows you to reconcile fields of data coming from different or external sources in a single tabular view (by default), without having to physically store them into your database.
Fields of data could be coming from many other sources such as other B2B SaaS (e.g. Zendesk, Salesforce, Stripe), in-memory database, message broker, etc.
On our Live Demo, we’ve stored the Legal Documents
of a Company
on Amazon
S3. In the following example, we show you how to create the Smart Collection to
see and manipulate them in your Forest admin.
First, we declare the LegalDoc
collection in the
lib/forest_liana/collections/
directory. In this Smart Collection, all fields
are related to S3 attributes except the field is_verified
that is stored on
our database in the table documents
. You can check out the list of
available field options here if you need it.
You MUST declare an id
field when creating a Smart Collection. The
value of this field for each record MUST be unique. On the following example, we
simply generate a random UUID.
You can add the option is_searchable: true
to your collection to display the search bar.
At this time, there’s no Smart Collection Implementation because no route in
your Rails app handles the API call yet. In the file
/app/controllers/forest/legal_docs_controller.rb
, we’ve created a new controller to implement the API behind the Smart Collection.
The logic here is to list all the files uploaded on a specific S3 Bucket. We
use a custom service /app/services/forest/s3-helper.rb
for this example. The
implementation code of this service is available on
Github.
Finally, the last step is to serialize the response data in the expected format which is simply a standard JSON API document.
To access the details view of a Smart Collection record, you have to catch the
GET API call on a specific record. One more time, we use a custom service
/app/services/forest/s3-helper.rb
that encapsulates the S3 business logic for
this example.
The implementation of the build_legal_doc()
and is_verified?()
methods are already described in the Implementing the GET (all
records) section.
To handle the update of a record we have to catch the PUT API call. In our
example, all S3-related fields are set as read-only and only is_verified
can be updated.
The implementation of the build_legal_doc()
and is_verified?()
methods are already described in the Implementing the GET (all
records) section.
Now we are able to see all the legal documents on Forest Admin, it’s time to implement the DELETE HTTP method in order to remove the documents on S3 when the admin user needs it.
A Segment is a subset of a collection gathering filtered records.
Segments are designed for those who want to systematically visualize data according to specific sets of filters. It allows you to save your filters configuration so you don’t have to compute the same actions every day (e.g. signup this week, pending transactions).
Forest provides a straightforward UI to configure the segments you want. The only information the UI needs to create a segment within a collection is a name and some filters.
Forest gives you a second option to create segment. SQL queries allow you to create advanced filters and connect your data through a few lines of code. In our example, through the Edit layout
(1) we access the Transactions
collection’s settings (2). Then, in Segments
(3), we create a New segment
(4) for which we choose a name
(5). Pick the Query
mode instead of the simple one (6), type in your SQL query (7) and do not forget to save (8).
Sometimes, segment filters are complicated and closely tied to your business. Forest allows you to code how the segment is computed.
On our Live Demo example, we’ve implemented a Smart Segment on the collection
Product
to allow admin users to see the bestsellers at a glance.
You’re free to implement the business logic you need. The only requirement is
to return a valid Active Record condition. Most of the time, your Smart Segment
should return something like { id: [ 1,2,3,4,5 ] }
.
On our implementation, we use a raw SQL query to filter and sort the product that was sold the most.
By default, Forest applies the same configuration to all segments of the same collection.
However, the “independent columns configuration” option (1) allows you to display different columns on your different segments.
As an admin user, KPIs are one of the most important things to follow day by day. Your customers’ growth, Monthly Recurring Revenue (MRR), Paid VS Free accounts are some common examples.
Forest can render four types of charts:
Ensure you’ve enabled the Layout Editor
mode to add, edit or delete a chart.
Forest provides a straightforward UI to configure the charts you want.
The only information the UI needs to handle such charts is:
Premium feature
Forest’s dashboard is handy when it comes to monitoring the overall KPIs. But you may find the analytics module useful for a more in-depth examination of a specific company, user or any other items.
“Analytics per record” only supports the Smart and Query mode.
?
to inject the current record the user
is currently seeing to your query. More details here.record_id
is automatically passed in the
HTTP body to access the record the user is currently seeing.Premium feature
The Query mode has been designed to provide you with a flexible, easy to use and accessible interface when hard questions need to be answered. Simply type SQL queries using the online editor and visualize your data graphically.
The syntax of the SQL examples below can be different depending on the database type (SQLite, MySQL, Postgres, SQL Server, etc.). Please, refer to your database documentation for more information.
The returned column must be name value
. In the following example, we simply
count the number of customers
.
The returned columns must be name value
and previous
. In the following
example, we simply count the number of Appointments booked in January 2018 and
compare this value to the number of Appointments booked in the previous month.
The returned columns must be name key
and value
. In the following
example, we simply count the number of transactions distributed by status.
The returned columns must be name key
and value
. In the following
example, we simply count the number of appointments
per month.
If you put the character ?
in your SQL query, it will automatically be
replaced by the current record opened in your Admin. Most of the time, it’s
required if you have charts declared in the Analytics per Account section.
Don’t forget this special character with quotes if the type requires it.
In the following example, we compute the number of transactions per month for
the company “Deliveroo”. The companies.id
is an integer here, so there’s no
need to quote it.
Sometimes, charts data are complicated and closely tied to your business. Forest allows you to code how the chart is computed. Choose “Smart” as the data source when configuring your chart. Forest will make the HTTP call to Smart Chart URL when retrieving the chart values for the rendering.
On our Live Demo, we have a MRR
value chart which computes our Monthly
Recurring Revenue. This chart queries the Stripe API to get all charges made in
the current month (in March for this example).
When serializing the data, we use the serialize_model()
method.
Check the value
syntax below.
On our Live Demo, we have a Charges
repartition chart which shows a
repartition chart distributed by credit card country. This chart queries the
Stripe API to get all charges made in the current month (in March for this
example) and check the credit card country.
When serializing the data, we use the serialize_model()
method.
Check the value
syntax below.
On our Live Demo, we have a Charges
time-based chart which shows the number
of charges per day. This chart queries the Stripe API to get all charges made
in the current month (in March for this example) and group data by day.
When serializing the data, we use the serialize_model()
method.
Check the value
syntax below.
A view is simply the way to visualize your data in the Forest UI. By default, Forest renders your data using a table view when you access multiple records and a form view to access, edit and create a specific record.
Premium feature
Smart Views lets you code your view using JS, HTML, and CSS. They are taking data visualization to the next level. Ditch the table view and display your orders on a Map, your events in a Calendar, your movies, pictures and profiles in a Gallery. All of that with the easiness of Forest.
Forest provides an online editor to inject your Smart View code. The editor is available on the collection’s settings, then in the “Smart views” tab.
The code of a Smart View is an Ember Component and simply consists of a Template and Javascript code.
Don’t panic, you don’t need to know the Ember.js framework to create a Forest Smart View. We will guide you here on all the basic requirements. For more advanced usage, you can still refer to the Ember Component and the Handlebars Template documentations.
The records of your collection are accessible from the records property. Here’s how to iterate over them in the template section:
For each record, you will access its attributes through the
forest-attribute
property. The forest-
preceding the field name
is required.
Accessing a belongsTo
relationship works in exactly the same way as accessing a simple field. Forest triggers automatically an API call to retrieve the data
from your Admin API only if it’s necessary.
On the Shipping
Smart View (in the collection named Order
) defined on our
Live Demo example, we’ve displayed the full name of the customer related to an
order.
Accessing a hasMany
relationship works in exactly the same way as accessing a simple field.. Forest triggers automatically an API call to retrieve the data
from your Admin API only if it’s necessary.
Trigger the fetchRecords
action in order to refresh the records on the page.
Trigger an API call to your Admin API in order to fetch records from any collection and with any filters you want.
We will use the store
service for that purpose. Check out the list of all
[available services] from your Smart View.
On our Live Demo example, the collection appointments
has a Calendar
Smart
View. When you click on the previous or next month, the Smart View fetches the
new events in the selected month. The result here is set to the property
appointments
. You can access it directly from your template.
Parameter | Type | Description |
filter | Object | A list of filters you want to apply. Example filter: { date: '>2018-01-28,<2018-03-11', name: 'Manuela Nolan' } . |
filterType | String | and or or . |
timezone | String | The timezone string. Example: America/Los_Angeles . |
page[number] | Number | The page number you want to fetch. |
page[size] | Number | The number of records per page you want to fetch. |
The deleteRecords
action lets you delete one or multiple records. A pop-up
will automatically ask for a confirmation when a user triggers the delete
action.
Here’s how to trigger your Smart Actions directly from
your Smart Views. You can pass an array or a single record. The first argument
is the collection
that has the Smart Action. The second argument is the Smart
Action name, here Reschedule
, and the third argument is an array of records
or a single one.
Forest automatically injects into your Smart View some properties to help you display your data like you want.
Property | Type | Description |
---|---|---|
collection |
Model | The current collection. |
currentPage |
Number | The current page. |
isLoading |
Boolean | Indicates if the UI is currently loading your records. |
numberOfPages |
Boolean | The total number of available pages |
records |
array | Your data entries. |
searchValue |
String | The current search. |
Forest automatically injects into your Smart View some actions to trigger the logic you want.
Action | Description |
---|---|
deleteRecords(records) |
Delete one or multiple records. |
triggerSmartAction(collection, actionName, record) |
Trigger a Smart Action defined on the specified collection on a record. |
On our Live Demo, we have 4 Smart Views defined:
deliveries
collection.appointments
collection.orders
collection.products
collection.Forest is able to leverage data from third party services by reconciliating it with your application’s data, providing it directly to your admin. All your admin actions can be performed at the same place, bringing additional intelligence to your admin and ensuring consistency.
Premium feature
Configuring the Stripe integration for Forest allows you to have your
customer’s payments, invoices and cards (1) alongside the corresponding
customer from your application. A Refund
Smart Action (2,3) is also implemented
out-of-the-box.
On our Live Demo, we’ve configured the Stripe integration on the Customer
collection. The Stripe Customer ID is already stored on the database under the
field stripe_id
.
Here are the complete list of available options to customize your Stripe integration.
Name | Type | Description |
---|---|---|
api_key | string | The API Secret key of your Stripe account. Should normally starts with sk_ . |
mapping | string | Indicates how to reconcile your Customer data from your Stripe account and your collection/field from your database. Format must be model_name.stripe_customer_id_field |
Premium feature
The Mixpanel integration allows you to fetch Mixpanel’s events and display them at a record level into Forest.
To benefit from Mixpanel integration, you need to add the gem 'mixpanel_client'
to your Gemfile.
Then, add the following code to your initializer. In our example we will map the Customer.email
with the data coming from Mixpanel. You may replace by your own relevant collection(s).
By default, Mixpanel is sending the following fields: id, event, date, city, region, country, timezone, os, osVersion, browser, browserVersion.
If you want to add other fields from Mixpanel, you have to add them in customProperties
:
You will then be able to see the Mixpanel events on a record, a Customer
in our example.
Premium feature
Configuring the Intercom integration for Forest allows you to display your user’s session data (location, browser type, …) and conversations.
You will find below the code and the gem needed to use the Intercom integration in Rails. The “mapping” option is the collection on which your integration is pointing.
You will have to restart your server to see Intercom plugged to your project.
Forest natively supports data creation but it’s sometimes more efficient to simply import it. This “How-to” shows a way to achieve that in your Forest admin.
In the following example, we’ve created the Smart Action Import data
on the
collection products
which contains two input fields: the CSV file
and the
Type
. The Type
input field is completely optional, we use it to import the
list of products with the good type set.
When clicking on the Import data
Smart Action, an API call to
/forest/products/actions/import-data
is triggered as indicated in the
endpoint
parameter of the action. We handle this call in the
config/routes.rb
file.
The CSV file passed into the body of the API call is serialized using a base64 encoding Data URI scheme.
To deserialize the base64 encoded CSV file, we use the NPM packageparse-data-uri. We also use the csv parser NPM package to iterate over each line of the CSV file.
You can find a sample CSV file we use here to feed our products table on the Live demo Github repository.
You may find below the coding examples you need to make this Smart action work:
Forest UI natively allows you to hide specific collections through the Edit layout. However, in case you want to hide a large number of collections, doing it with our UI could take a while.
Using Forest with Rails, you can add the following code to either define which models will be included in Forest or which models will be excluded.