Dashboards API

Per-option reference for dashboards. For task-oriented documentation and worked examples, see the Dashboards guide.

Options are class attributes set on the dashboard class. Any option can also be a Proc — it is evaluated through Avo::ExecutionContext, where you gain access to all its attributes plus the dashboard.

# app/avo/dashboards/dashy.rb
class Avo::Dashboards::Dashy < Avo::Dashboards::BaseDashboard
  self.id = "dashy"
  self.name = "Dashy"
  # options listed below

  def cards
    # register cards here
  end
end

Identity and layout

-> self.id

The dashboard's unique identifier. Used as the route param, so it must be unique across all dashboards.

self.id = "dashy"

• Type: String
• Default: nil
• Required: yes

-> self.name

The title shown to the user at the top of the dashboard.

self.name = "Dashy"
# or
self.name = -> { I18n.t("avo.dashboards.dashy.name") }

• Type: String or Proc
• Default: nil

-> self.description

Subtitle rendered under the dashboard name for extra context.

self.description = "Key metrics at a glance"

• Type: String or Proc
• Default: nil

-> self.grid_cols

How many columns the card grid has.

self.grid_cols = 4

• Type: Integer
• Default: 3
• Values: 3, 4, 5, or 6 — any other value falls back to 3

Ranges

-> self.global_ranges

Renders a row of range buttons at the top of the dashboard that update every card's range at once. Each entry is a number of days; its button label comes from the avo.<days> translation key.

self.global_ranges = [7, 30, 60, 365]

• Type: Array of Integers
• Default: [] (no global range bar)

-> self.refresh_button

Renders a control next to the dashboard's title that reloads every card at once. Cards reload in place, so the page never navigates and each card keeps its selected range.

self.refresh_button = true

• Type: Boolean
• Default: false

INFO

Off by default because refreshing a dashboard runs every card's query at once. The per-card control is a separate opt-in under the same name — setting one does not set the other.

Visibility and authorization

-> self.visible

Controls whether the dashboard appears in the sidebar and can be reached. As a Proc it is evaluated through Avo::ExecutionContext, so you have access to params, current_user, context, and dashboard.

self.visible = -> { current_user.admin? }

• Type: Boolean or Proc
• Default: true

INFO

A dashboard that fails authorize is treated as not visible regardless of this option.

-> self.authorize

Authorization gate for the dashboard. Return a falsy value to deny access. Evaluated through Avo::ExecutionContext, with access to current_user, params, request, context, and view_context.

self.authorize = -> { current_user.is_admin? }

• Type: Proc
• Default: -> { true }