# Dashboard

Dashboards are configured under the ay_dashboard_widget table, the following options can be configured.

# Types of Widgets

# Value

A widget that will show a value (e.g. the total number of users).

The following attributes can be used.

{
  "icon": "icon-users",
  "unit": "%"
}

unit can be used to concatenate a string to the value.

An example of a source of data.

{
  "sql": "SELECT count(*) as value
          FROM player
          WHERE tenant_id=[user.tenant_id]"
}

** Notice that the special field [user.tenant_id] is also possible to use in widgets.**

# Bar

Widget used to show vertical/horizontal bar or line chart.

The following attributes can be used.

{
  "type": "line" | "bar",
  "colors": ["#AABB44", "#5589AA"],
  "orientation": "vertical" | "horizontal",
  "x_name": "week",
  "y_name": "# sessions",
  "smooth": false
}

x_name and y_name are the axis title for the chart.
smooth will set the type of line, if true it created a curvy line instead of a hard straight line between the data points.

An example of a source of data.

{
  "sql": "SELECT count(*) as value, IF(mobile = 0, 'Desktop', 'Mobile') as name
          FROM player
          WHERE tenant_id = [user.tenant_id]
          GROUP BY name
          ORDER BY value DESC"
}

# Donut

Widget used to show a donut / pie chart.

The following attributes can be used.

{
  "pie": true | false,
  "colors": ["#AABB44", "#5589AA"]
}

An example of a source of data.

{
  "sql": "SELECT count(*) as value, IF(mobile = 0, 'Desktop', 'Mobile') as name
          FROM player
          WHERE tenant_id = [user.tenant_id]
          GROUP BY name
          ORDER BY value DESC"
}

# Fulltable

# Table

Widget used to show a table of values. If FULLTABLE is used as type it also shows pagination on the bottom of the widget, and total results on the top right corner.

{
  "header": [
    {
      "label": "Username",
      "field": "username",
      "width": 60
    },
    {
      "label": "Last login",
      "field": "last_login",
      "width": 40
    }
  ]
}

An example of a source of data.

{
  "sql": "SELECT username, last_login FROM ay_user LIMIT 5"
}

# Iframe

Loads and external iframe, used to make custom UI elements.

{
  "url": "https://domain.xyz"
}

# The GUI property

This column will store the UI information (size and positions on a grid) of the widget. The UI is using CSS Grid Layout so a valid configuration would be:

{
  "gridColumn": "1 / span 3",
  "gridRow": "1/ span 1"
}

Themes

It's possible to load an echart theme to make easier and more powerfull changes on the charts look and feel. The file should be placed under /api/assets/mays/echarts-theme.json. Consult echarts official page to get more information about themes.

# Cached Widgets

Instead of using "sql" on each widget we can use "func" width the name of a function of the CustomDashboard class.

An example of a source of data.

{
  "func": "getLastLogins"
}

The CustomDashboard is not part of the framework but you can add the class using the following example.

<?php

namespace mays\core;

use mays\core\DBConnector;

class CustomDashboard
{
  private $cache;

  public function getLastLogins()
  {
    $com = "SELECT username, last_login FROM ay_user LIMIT 5";
    $this->cache = DBConnector::executeSelect($com);
    return $this->cache;
  }

  public function getCustomMultiSeries()
  {
    return [
      [
        90, 12, 14
      ],
      [
        40, 2, 4
      ],
      [
        190, 212, 314
      ]
    ];
  }
}

Notice we can simply call a sql command and store the result on any custom classe property for future use on another widget (the same instance of CustomDashboard will be used on all dashboards of the same schema).

Using custom dashboards is also the only way to implement multi-series graphs.

Multi series need to be returned as a multi dimensional array of values just like the example above. Notice that on this case you should add on the attributes of the widget information about the x and y axis, here it is an example of that.

{
  "orientation": "vertical",
  "yAxis": [
    {
      "type": "value"
    },
    {
      "type": "value"
    }
  ],
  "xAxis": [
    {
      "data": ["Label X1", "Label X2", "Label X3"]
    }
  ],
  "series": [
    {
      "type": "bar"
    },
    {
      "type": "bar"
    },
    {
      "type": "line",
      "yAxisIndex": 1
    }
  ]
}

On the above example we are creating a chart with two bar series and a third series that will be a line. We also use a different yAxis for this third series (it will appear a second Y axis on the right side).

For the yAxis and xAxis is it possible to pass any valid property of eCharts, they will be use directly by the UI. For example.

"yAxis": [
  {
    "type": "value",
    "name": "series2",
    "min": 0,
    "max": 250,
    "interval": 50,
    "axisLabel": {
      "formatter": "{value} ml"
    }
  }
]

More information about eCharts here: https://www.echartsjs.com/examples

# Filters

It's possible to define filters at the level of the dashboard (page), that are available to all widgets of the same dashboard. It's also possible to have specific filters for a widget, in this case it only affects the widget which is associated.

The filters can be of 3 types, combobox, datetime or text.

{
  "filters": [
    {
      "type": "datetime",
      "name": "date"
    },
    {
      "type": "combobox",
      "name": "list",
      "src": [
        {
          "id": 1,
          "name": "Filtro 1"
        },
        {
          "id": 2,
          "name": "Filtro 2"
        }
      ]
    }
  ]
}

Combobox type also supports the "sql" mode to support dynamic queries (check the combobox field type for more information).

← Get started Reports →