Dash Controller

October CMS features a flexible dashboard system capable of hosting multiple dashboards with configurable access. Each dashboard can contain multiple widgets to display various data types. October CMS comes with several widget types, including graph, table and others. The default widgets are sufficiently flexible to cover most common reporting scenarios, such as displaying sales or traffic information. In addition, developers can create new widget types for scenarios where the default widgets do not meet their needs.

# Data Sources

Most built-in dashboard widgets in October CMS work with server-side data sources. These data sources supply structured data in the form of dimensions, metrics, and metric values. This approach enables developers to use the same widget types with various data. For instance, the Table widget can display data regarding CMS traffic or eCommerce sales. In this scenario, the Table widget must be connected to different data sources and refer to various dimensions and metrics provided by those sources.

For most reporting needs, developers should include data sources in their plugins, rather than creating custom widgets.

This documentation uses the following terms when describing data sources and widgets:

• Dimension - is an aspect or category of data used for organizing and grouping information in a report. Dimensions often represent qualitative data, such as product names or page names, which help in segmenting the data into more meaningful and comprehensible units. For example, in a sales report, Product could be a dimension that categorizes sales data by different products.
• Metric - is a quantitative measurement that provides values for a dimension. Metrics represent the actual data points being measured, such as sales figures, traffic counts, or conversion rates. Metrics give numerical values to each category or unit defined by a dimension. For instance, if Product Name is a dimension, the corresponding metric could be the number of units sold or revenue generated for each product.
• Dimension field - dimensions can include dimension fields, which represent additional information related to a dimension and are displayed in reports. For the Product dimension, it is logical to register the Brand dimension field.

It's important to note that although you should specify table column names for metric and dimension objects, the dashboard system is data-nature agnostic. This means that in your data source class, you have the flexibility to decide how to generate the data, and it's not necessarily limited to data loaded from a database. There is a class ReportDataQueryBuilder that greatly simplifies building database-driven data sources, but its use is optional.

# Default Widget Types

October CMS includes the following widget types:

# Registering Plugin Dashboards

Plugins can supply their own dashboards by overriding the registerDashboards method in the plugin registration file. Each dashboard is keyed by a unique code, which is also used in its URL, and refers to a YAML file containing the dashboard definition.

public function registerDashboards()
{
    return [
        'dashboards' => [
            'sales' => '$/acme/shop/dashboards/sales.yaml'
        ]
    ];
}

The definition file supports the same properties as a dashboard in the Dash Behavior configuration. The optional permissions property hides the dashboard from users without any of the listed permissions, and showInterval can be set to false when the reports do not use the date range picker.

name: Sales
icon: ph ph-shopping-cart
permissions:
    - acme.shop.view_sales

reports:
    sales_title:
        row: 1
        width: 20
        type: section-title
        title: Sales

Report properties match the widget settings in the dashboard editor, for example chartType: doughnut for a chart, or metric and goal for an indicator.

Registered dashboards appear on the backend dashboard as system dashboards, listed after the existing ones. Administrators can rename, hide, reorder and customize them, and the Reset to Default button restores the registered layout. A dashboard that has not been customized always follows the latest definition from the plugin, and it is removed when the plugin is disabled or uninstalled. A customized dashboard is kept as a regular dashboard that can be deleted.

The same method also registers report widgets and data sources with the widgets and dataSources keys. When a plugin only registers dashboards, the method can return them directly.

public function registerDashboards()
{
    return [
        'sales' => '$/acme/shop/dashboards/sales.yaml'
    ];
}

# Default Date Range

You can configure the default date range and grouping interval for a dashboard using the following properties in the dashboard YAML configuration file.

For example, to default a finance dashboard to show data from the start of the year, grouped by month:

finance:
    name: Finance
    icon: icon-chart-bar
    defaultStart: year
    defaultEnd: today
    defaultInterval: month

These defaults apply when the user first visits the dashboard and no date range is selected in the URL. Once the user selects a different range, their selection takes precedence.