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.
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:
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.
When creating database-driven data sources, ensure that the dimension, dimension fields, and metric columns are indexed for optimal query performance.
October CMS includes the following widget types:
| Type | Description |
|---|---|
| Indicator | displays a single data source metric value, such as the total number of pageviews over the selected dashboard period. |
| Table | capable of displaying multiple dimension values and metrics, like product names, numbers of units sold, and total sales amount. |
| Chart | supports line and bar charts. In line charts, the horizontal axis shows dimension values, while the vertical axis shows metric values. |
| Section Title | Shows a static section title, such as 'Traffic Information'. This widget can also display the currently selected reporting interval. |
| Text Notice | contains a static title and paragraph text to present any information related to the dashboard. |
Plugins can create and install custom dashboards in October CMS by using the seeding feature. To create a plugin dashboard, first create a dashboard manually, then export it using the dashboard's built-in Export Dashboard feature. Save the exported JSON file in a plugin directory. Afterwards, employ the Dashboard model’s import function to import the JSON file as a new dashboard.
use Backend\Models\Dashboard;
...
$content = file_get_contents(__DIR__.'/default-dashboard.json');
Dashboard::import($content, null, true);The second argument of the call should always be null for seeding purposes. The third argument specifies whether the dashboard should be accessible to all users. If set to false, the dashboard will be accessible only to users with dashboard management permissions.