PHP Developer Guide
Other documentationsDemoCommunityGitHub
  • Forest Admin
  • Getting started
    • How it works
    • Quick start
      • Symfony
      • Laravel
    • Create your agent
    • Troubleshooting
    • Migrating legacy agents
      • Pre-requisites
      • Recommendations
      • Migration steps
      • Code transformations
        • API Charts
        • Live Queries
        • Smart Charts
        • Route overrides
        • Smart Actions
        • Smart Fields
        • Smart Relationships
        • Smart Segments
  • Data Sources
    • Getting Started
      • Collection selection
      • Naming conflicts
      • Query interface and Native Queries
        • Fields and projections
        • Filters
        • Aggregations
    • Provided data sources
      • Doctrine
      • Eloquent
        • Polymorphic relationships
    • Write your own
      • Translation strategy
        • Structure declaration
        • Capabilities declaration
        • Read implementation
        • Write implementation
        • Intra-data source Relationships
      • Contribute
  • Agent customization
    • Getting Started
    • Actions
      • Scope and context
      • Result builder
      • Static Forms
      • Dynamic Forms
      • Related data invalidation
    • Charts
      • Value
      • Objective
      • Percentage
      • Distribution
      • Leaderboard
      • Time-based
    • Fields
      • Add fields
      • Move, rename and remove fields
      • Override binary field mode
      • Override writing behavior
      • Override filtering behavior
      • Override sorting behavior
      • Validation
    • Hooks
      • Collection hook
      • Collection override
    • Pagination
    • Plugins
      • Write your own
    • Relationships
      • To a single record
      • To multiple records
      • Computed foreign keys
      • Under the hood
    • Search
    • Segments
  • Frontend customization
    • Smart Charts
      • Create a table chart
      • Create a bar chart
      • Create a cohort chart
      • Create a density map
    • Smart Views
      • Create a Map view
      • Create a Calendar view
      • Create a Shipping view
      • Create a Gallery view
      • Create a custom tinder-like validation view
      • Create a custom moderation view
  • Deploying to production
    • Environments
      • Deploy on AWS
      • Deploy on Heroku
      • Deploy on GCP
      • Deploy on Ubuntu
    • Development workflow
    • Using branches
    • Deploying your changes
    • Forest Admin CLI commands
      • init
      • login
      • branch
      • switch
      • set-origin
      • push
      • environments:create
      • environments:reset
      • deploy
  • Upgrade
    • Laravel agent upgrade to v3
  • Under the hood
    • .forestadmin-schema.json
    • Data Model
      • Typing
      • Relationships
    • Security & Privacy
Powered by GitBook
On this page
  • What is a Smart View?
  • Creating a Smart View
  • Applying a Smart View

Was this helpful?

  1. Frontend customization

Smart Views

PreviousCreate a density mapNextCreate a Map view

Last updated 1 year ago

Was this helpful?

This is the official documentation of the forestadmin/laravel-forestadmin v2+ and forestadmin/symfony-forestadmin PHP agents.

What is a Smart View?

Smart Views let you code your List Views 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 Admin.

Creating a Smart View

Forest Admin 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.

You don’t need to know the Ember.js framework to create a Smart View. We will guide you here on all the basic requirements.

Available properties

Forest Admin 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

Number

The total number of available pages

records

array

Your data entries

searchValue

String

The current search

Getting your records

The records of your Collection are accessible from the records property. Here’s how to iterate over them in the template section:

{{#each @records as |record|}}{{/each}}

Accessing a specific record

For each record, you will access its attributes through the forest-attribute property. The forest- preceding the field name is required.

{{#each @records as |record|}}
  <p>status: {{record.forest-shipping_status}}</p>
{{/each}}

Accessing belongsTo relationships

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.

{{#each @records as |record|}}
  <h2>
    Order to
    {{record.forest-customer.forest-firstname}}
    {{record.forest-customer.forest-lastname}}
  </h2>
{{/each}}

Accessing hasMany relationships

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.

{{#each @records as |record|}}
  {{#each @record.forest-comments as |comment|}}
    <p>{{comment.forest-text}}</p>
  {{/each}}
{{/each}}

Refreshing data

Trigger the fetchRecords action in order to refresh the records on the page.

<button {{on 'click' @fetchRecords}}>
  Refresh data
</button>

Fetching data

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.

In 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 propertyappointments. You can access it directly from your template.

component.js
import Component from '@glimmer/component';
import { inject as service } from '@ember/service';
import { tracked } from '@glimmer/tracking';

export default class extends Component {
  @service store;
  @tracked appointments;

  async fetchData(startDate, endDate) {
    const params = {
      filters: JSON.stringify({
        aggregator: 'And',
        conditions: [
          { field: 'start_date', operator: 'GreaterThan', value: startDate },
          { field: 'start_date', operator: 'LessThan', value: endDate },
        ],
      }),
      timezone: 'America/Los_Angeles',
      'page[number]': 1,
      'page[size]': 50,
    };

    this.appointments = await this.store.query('forest_appointment', params);
  }
  // ...
}
template.hbs
{{#each this.appointments as |appointment|}}
  <p>{{appointment.id}}</p>
  <p>{{appointment.forest-name}}</p>
{{/each}}

Available parameters

Parameter
Type
Description

filters

Object

A stringified JSON object containing either:

  • a filter

  • an aggregation of several filters

A filter is built using the following template:

{

field: <a field name>

operator: <an operator name>

value: <a value>

}

An aggregation is built using the following template

{

aggregator: <and or or>

conditions: <an array of filters or aggregations>

}

List of available operators is: less_than, greater_than, equal, after, before, contains, starts_with, ends_with, not_contains, present, not_equal, blank

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.

Available actions

Forest Admin 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 an action defined on the specified collection on a record.

Deleting records

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.

template.hbs
{{#each @records as |record|}}
  <Button::BetaButton
    @type='danger'
    @text='Delete record'
    @action={{fn this.deleteRecords record}}
    @async={{false}}
  />
{{/each}}

Triggering an Action

Please note that the Action triggering in the context of the Smart View editor can be broken as you might not have access to all the required information. We advise you to test the Action execution from the Smart View applied to the Collection view.

<Button::BetaButton
  @type='primary'
  @text='Reschedule appointment'
  @action={{fn this.triggerSmartAction @collection 'Reschedule' record}}
/>
import Component from '@glimmer/component';
import { action } from '@ember/object';
import { triggerSmartAction } from 'client/utils/smart-view-utils';

export default class extends Component {
  @action
  triggerSmartAction(...args) {
    return triggerSmartAction(this, ...args);
  }

  @action
  deleteRecords(...args) {
    return deleteRecords(this, ...args);
  }
}

triggerSmartAction function imported from 'client/utils/smart-view-utils' has the following signature:

function triggerSmartAction(
  context,
  collection,
  actionName,
  records,
  callback = () => {},
  values = null,
) {
  // ...
}
Argument name
Description

context

The reference to the component, in the Smart View it is accessible through the keyword this

collection

The collection where the Action is defined

actionName

The Action name

records

An array of records or a single one

callback

A function executed after the action that takes as the single parameter the result of the action execution

values

An object containing the values to be passed for the action fields

<Button::BetaButton
  @type='primary'
  @text='Reschedule appointment'
  @action={{fn this.rescheduleToNewTime record}}
/>
import Component from '@glimmer/component';
import { action } from '@ember/object';
import { triggerSmartAction } from 'client/utils/smart-view-utils';
import { tracked } from '@glimmer/tracking';

export default class extends Component {
  @tracked newTime = '11:00';

  @action
  triggerSmartAction(actionName, records, values) {
    return triggerSmartAction(
      this,
      this.args.collection,
      actionName,
      records,
      () => {},
      values,
    );
  }

  @action
  rescheduleToNewTime(record) {
    this.triggerSmartAction('Reschedule', record, { newTime });
  }

  @action
  deleteRecords(...args) {
    return deleteRecords(this, ...args);
  }
}

Applying a Smart View

To apply a Smart View you created, turn on the Layout Editor mode (1), click on the table button (2) and drag & drop your Smart View's name in first position inside the dropdown (3):

Your view will refresh automatically. You can now turn off the Layout Editor mode (4).

Impact on related data

Once your Smart view is applied, it will also be displayed in your record's related data.

In the related data section

In the summary view

As of today, it's not possible to set different views for your Table/Summary/Related Data Views.

The code of a Smart View is a and simply consists of a Template and JavaScript code.

For more advanced usage, you can still refer to the and the documentations.

Here’s how to trigger your directly from your Smart Views.

Here is an example of how to trigger the Action with the values passed from the code, you only need to do it if you don't want to use the built-in

Glimmer Component ↗
Glimmer Component ↗
Handlebars Template ↗
Actions
Action Form