DashboardSegment

Choose and persist a Matomo segment per dashboard widget — with a dashboard-wide default that individual widgets can override or opt out of.

Matomo's dashboards only support one global segment applied to every widget at once. That makes mixed dashboards impossible — e.g. an "LLM / AI analysis" dashboard where most widgets should use an AI Referrer segment, but the AI‑chatbot widgets must show all data (they have no AI referrer by definition). DashboardSegment fixes that.

Features

• Per‑widget segment: pick a saved segment for any individual widget from a control in its header.
• Dashboard default: set one default segment for the whole dashboard; widgets inherit it.
• Three states per widget: inherit the default · a specific segment · No segment (all data) (__none__) which wins even over a dashboard default.
• Per instance: the same widget can appear twice on a dashboard with different segments (useful for side‑by‑side comparison).
• Per site: segments are chosen and applied separately for each site; only the current site's saved segments are offered and applied.
• A small bar under the widget header shows the active segment, with a × to remove it (fall back to all data).

Precedence: per‑widget override > dashboard default > Matomo's global segment selector.

How it works (no core patches)

The plugin is purely additive — it never modifies Matomo core or the bundled Dashboard plugin, so it survives Matomo updates:

• It wraps the global widgetsHelper.loadWidgetAjax (the single function every widget request flows through) and rewrites the segment request parameter per widget instance.
• Each widget instance is tagged with a stable id stored in the dashboard layout (via the Dashboard plugin's own save), so duplicated widgets stay distinguishable.
• Overrides live in the plugin's own table dashboard_widget_settings, keyed by (login, iddashboard, idsite, widget instance).
• The segment list reuses the existing SegmentEditor segments.

To create a new segment (e.g. AI Referrer), use Matomo's normal segment editor once; it then appears in the per‑widget picker.

Requirements

• Matomo 5.x
• The bundled Dashboard and SegmentEditor plugins (active by default).

Installation

1. Copy this folder to plugins/DashboardSegment in your Matomo installation.
2. Activate it: Administration → Plugins → DashboardSegment → Activate, or on the CLI:

   ./console plugin:activate DashboardSegment
   ./console core:clear-caches
   

   Activation creates the dashboard_widget_settings table.

Usage

1. Open a dashboard.
2. Use the segment button in a widget's header to pick a segment, "No segment (all data)", or "Inherit dashboard default".
3. Use the Dashboard default segment control above the widgets to set a default for the whole dashboard.
4. Switch sites to manage each site's selection independently.

Known limitations / roadmap

• Reactive / live widgets are not supported. Some widgets fetch and refresh their data client‑side (Vue) and read the segment/period directly from the dashboard's global state — e.g. the Live! widget and any widget with sparklines (such as "Visits Overview (with graph)"). An additive plugin cannot override global state for a single widget, so the per‑widget pickers are hidden on those widgets to avoid a false expectation. Standard server‑rendered report widgets (the majority) are fully supported.
• Matomo fires no event when a dashboard is deleted, so override rows for a deleted dashboard are not actively cleaned up. They are inert (their instance keys never match a live widget) and are removed when the user is deleted.
• Planned: bulk segment assignment, dashboard sharing (copy‑as‑template and share‑to‑users).

Development

• PHP logic (precedence, persistence, permissions) is covered by PHPUnit tests under tests/.
• tests/jsSmoke.js runs the client bootstrap with stubbed globals to catch runtime errors that a syntax check misses: node tests/jsSmoke.js.

License

GPL v3 or later.