Add a Segment Management Page #23885

tzi · 2025-12-09T14:38:49Z

Description

UX-326

We propose the introduction of a new page in Matomo, titled "Segments."
This page will serve as a combined reporting and management tool to make it easy to view (and edit) all segments for a website, and also provide a clean dashboard to view All segment data at once.

Features

The search input allow us to filter the segments
We can star and unstar segments according to the current user right.
If needed, a tooltip explain why we cannot do an action. If it is a global segment, the tooltip precise that starring/unstarring it will affect all websites.
We can see Visits / Actions / Evolution Visits for each segment according to the selected period.
We can go back to the dashboard with a specific segment selected
We can edit a segment, according to the current user right.
If we choose to edit a segment, it opens the segmentEditorPanel
We can delete a segment, according to the current user right.
If we choose to delete a segment, it opens the segmentEditorPanel and trigger a new modal that ask confirmation before deleting it.
We can create a new segment according to the user right AND segment configuration.

Data Synchronization with the Panel

Starring/Unstarring will reorder segments without reload. The Page and the Panel are always synchronized.

Editing from Page	Editing from Panel

Menus

in the Dashboard menu	in the Administration Menu
Visitors > Segments	Websites > Segments

We added an outlink icon to the administration because this link goes back to the Dashboard. We choose this behaviour because the website / date / segment selector are needed and not available in the administration layout.

Plugins

This PR will have impact on plugins UI screenshots:

TagManager: https://github.com/matomo-org/tag-manager/pull/1077/changes

Checklist

[NA] I have understood, reviewed, and tested all AI outputs before use
[NA] All AI instructions respect security, IP, and privacy rules

Review

tzi · 2026-01-12T15:46:14Z

plugins/CoreHome/stylesheets/dataTable/_dataTable.less

+tr:nth-last-child(1 of .dataTable_row-group) td {
+  border-bottom: 3px solid @theme-color-background-tinyContrast !important;
+}


ℹ️ This create a large border after the last item in a row with the class dataTable_row-group.

Only "All Visits" has this class "All Visits" and "zefzef" are brothers and have this class

tzi · 2026-01-12T15:48:37Z

plugins/CoreVue/types/index.d.ts

  interface PiwikHelperGlobal {
    escape(text: string): string;
    redirect(params?: any);
+    getCurrentQueryStringWithParametersModified(newparams: string);


ℹ️ This function already exists (and is useful!) but it is now available outside of the piwikHelper.

tzi · 2026-01-12T15:49:16Z

core/Menu/MenuAdmin.php

+    public function addMeasurableItem($menuName, $url, $order = 50, $tooltip = false, $icon = false)
    {
-        $this->addItem('CoreAdminHome_MenuMeasurables', $menuName, $url, $order, $tooltip);
+        $this->addItem('CoreAdminHome_MenuMeasurables', $menuName, $url, $order, $tooltip, $icon);


ℹ️ This argument already exists and it is false by default. I only made it available in a higher level.

tzi · 2026-01-12T15:50:15Z

plugins/CoreHome/vue/src/Sparkline/Sparkline.less

+.sparklineEvolution {
+  color: black;
+  font-size: 12px;
+  white-space: nowrap;
+}
+
+.sparklineEvolution-positive {
+  color: green;
+}
+
+.sparklineEvolution-negative {
+  color: red;
+}
+
+.sparklineEvolution_icon {
+  margin-right: 1em;
+  vertical-align: middle;
+}


ℹ️ Inspired from the "All Websites" design, but now available everywhere.

tzi · 2026-01-12T15:51:35Z

plugins/Goals/Menu.php


        if (Piwik::isUserHasWriteAccess($idSite)) {
-            $menu->addMeasurableItem('Goals_Goals', $this->urlForAction('manage', array('idSite' => $idSite)), 40);
+            $menu->addMeasurableItem('Goals_Goals', $this->urlForAction('manage', array('idSite' => $idSite)), 15);


ℹ️ Goals item should be higher in the Administration Menu. It is more obvious now that we add a "Segments" item.

You better should not change that. If you want to add something after Goals, just use a higher number.
Decreasing the number here has the potential to break the order how our plugins are listed there.

Yes. The PO asked for Goals to be higher, because he wasn’t happy with the current plugin order.

tzi · 2026-01-12T15:56:09Z

plugins/SegmentEditor/javascripts/Segmentation.js

        }

        function addTooltip(element, title) {
+          $('.ui-tooltip').remove();


ℹ️ Avoid bug, when several tooltips are stack. It happens when DOM that trigger the tooltip is destroyed, for example when clicking on a star, the star is rebuild.

tzi · 2026-01-12T15:57:16Z

plugins/SegmentEditor/javascripts/Segmentation.js

-          updateStarSegmentTooltip($segment, segment);
+        function updateStarredSegment(segment, isError = false) {
+          starCallbackList.forEach(function(callback) {
+            callback(segment, isError);


ℹ️ When the state of a segment change, it changes automatically for the segmentEditor and the segmentPage in the same time.

tzi · 2026-01-12T15:58:04Z

plugins/SegmentEditor/javascripts/Segmentation.js

+        window.SegmentEditorPanel = {
+          addTooltip,
+          askToDeleteSegment,
+          closePanel,
+          getDeleteSegmentTitle,
+          getEditSegmentTitle,
+          getIsUserCanEditSegment,
+          getSegmentFromId,
+          normalizeSearchString,
+          onSegmentsStarChange,
+          openPanel,
+          openEditFormGivenIdSegment,
+          togglePanel,
+          toggleStarredSegment,
+          triggerStarAnimation,
+          updateStarSegmentTooltip,
+        };


ℹ️ Theses functions are also useful for the SegmentPage and the SegmentPanel, so we make it public to avoid duplication and inconsistency.

tzi · 2026-01-12T15:59:02Z

plugins/SegmentEditor/lang/en.json

        "AddANDorORCondition": "Add %s condition",
-        "AddNewSegment": "Add new segment",
-        "AreYouSureDeleteSegment": "Are you sure you want to delete this segment?",
+        "AddNewSegment": "Create new segment",


ℹ️ For consistency with Form / Funnels / Reports, we changed the label from "Add" to "Create" and displayed a "+" icon.

tzi · 2026-01-12T16:00:49Z

plugins/SegmentEditor/stylesheets/segmentation.less

-        display: flex;
-        width: 16px;
-        height: 16px;
+.segmentAction {


ℹ️ Reduce selector complexity to improve reusability

tzi · 2026-01-12T16:02:24Z

plugins/SegmentEditor/templates/_segmentSelector.twig

            </ul>

            {% if authorizedToCreateSegments %}
-                <a tabindex="4" class="add_new_segment btn">{{ 'SegmentEditor_AddNewSegment'|translate }}</a>


ℹ️ <a> tag without href attribute is an anchor and is not accessible.

tzi · 2026-01-12T16:03:20Z

plugins/SegmentEditor/templates/manageSegments.twig

+                                        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24">
+                                            <path stroke="black" stroke-width="3" fill="none" d="M9.153 5.408C10.42 3.136 11.053 2 12 2c.947 0 1.58 1.136 2.847 3.408l.328.588c.36.646.54.969.82 1.182.28.213.63.292 1.33.45l.636.144c2.46.557 3.689.835 3.982 1.776.292.94-.546 1.921-2.223 3.882l-.434.507c-.476.557-.715.836-.822 1.18-.107.345-.071.717.001 1.46l.066.677c.253 2.617.38 3.925-.386 4.506-.766.582-1.918.051-4.22-1.009l-.597-.274c-.654-.302-.981-.452-1.328-.452-.347 0-.674.15-1.329.452l-.595.274c-2.303 1.06-3.455 1.59-4.22 1.01-.767-.582-.64-1.89-.387-4.507l.066-.676c.072-.744.108-1.116 0-1.46-.106-.345-.345-.624-.821-1.18l-.434-.508c-1.677-1.96-2.515-2.941-2.223-3.882.293-.941 1.523-1.22 3.983-1.776l.636-.144c.699-.158 1.048-.237 1.329-.45.28-.213.46-.536.82-1.182l.328-.588Z"/>
+                                        </svg>


ℹ️ Star, in a future PR, will be handled with a background image to reduce the page weight and improve reusability

tzi · 2026-01-14T10:12:30Z

plugins/SegmentEditor/javascripts/manageSegmentsPage.js

+    var tooltip = $(root).parents('.matomo-widget').tooltip('instance');
+    if (tooltip) {
+      tooltip.disable();
+    }
+    window.SegmentEditorPanel.updateStarSegmentTitle($starButton, segment);
+    if (tooltip) {
+      tooltip.enable();
+    }


ℹ️ Without this trick, I had broken state at the first hovering: the old tooltip wasn’t closed and the new one wasn’t in the jqueryUI style. With the second hovering, everything goes to normal again.

That does not fully seem to work as expected. If I hover an unstared segment it displays Add to Starred segments for this website.. Clicking on the icon then stars the segment. But hovering the icon afterwards again still shows the same tooltip. Instead the tooltip content should change.

caddoo

Done a review over everything biggest thing missing are tests testing the interactions.

Also you don't need to have the TagManager change as part of this.

caddoo · 2026-01-19T00:49:35Z

plugins/SegmentEditor/javascripts/manageSegmentsPage.js

+      }
+      const $segment = $button.closest('tr');
+      const idSegment = $button.attr('data-star');
+      window.SegmentEditorPanel.toggleStarredSegment($segment, idSegment);


I noticed when this API call fails the item still gets starred and the UI shows the user it's starred, however there is a read error message at the top.

Is it easy to only update the UI if the call is successful?

We chosed optimistic UI so the interface seems reactive.
But, it the star should go back to its place with a red/error animation if there is an error.
So there is definitely something to check here on my side.
Thanks for the catch!

✅ Done !
The ajaxHelper.setErrorCallback() didn’t seem to work the way I expected, so I used another implementation.
Here is how it feels for the users:

caddoo · 2026-01-19T00:59:31Z

plugins/SegmentEditor/Menu.php

+        $idSite = Request::fromRequest()->getIntegerParameter('idSite', 0);
+        if (Piwik::isUserHasWriteAccess($idSite)) {


This feels weird, it's a general link to the segment editor, not site specific.

Also from the implementation of the segment editor it doesn't seem like write access is required to view it.

You’re right. There is 2 options here:

Display the link to everyone, because all users have access to this page. But, all users cannot use it to "manage" segment so it could be weird to have a "view" page in an administration plugin

Display the link to all users that can create segment. So it will depends on the segment configuration and the user level.

✅ Done!
I removed the access control because it is linked to the idSite, and the idSite is not mandatory in the administration part. Since all users have access to the segment management page, it should be the right behaviour.

caddoo · 2026-01-19T05:42:39Z

plugins/SegmentEditor/Controller.php

+        Piwik::checkUserHasViewAccess($this->idSite);
+    }
+
+    public function manageSegments(): string


@sgiehl Just a question for you this controller being open is generally fine right? (permission wise).

When anon user has no access then all controllers aren't accesible.

Yes, if anonymous user are authorized this page is accessible., but they can’t see all segments.
The same way they can apply some segments on the Dashboard.

caddoo · 2026-01-19T05:46:28Z

plugins/SegmentEditor/tests/UI/SegmentManagementPage_spec.js

+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+describe("SegmentManagementPageTest", function () {


Can you expand this test suite with some interaction tests as well to make sure everything always works and doesn't regress.

Yes. I wanted to have feedback and reviews before taking this task.

sgiehl · 2026-01-20T13:53:54Z

@tzi Is there a reason why you have built this using controller / view / template / plain javascript, instead of implementing the whole thing in a (more dynamic) vue component.? That would allow a lot more flexible handling.
Note: Long term target is more a transition to a SPA, where everything is handled in the UI and only data/information is fetched through API, rather then rendering anything in the backend.

tzi · 2026-01-20T15:15:58Z

@sgiehl: Is there a reason why you have built this using controller / view / template / plain javascript, instead of implementing the whole thing in a (more dynamic) vue component.? That would allow a lot more flexible handling.
Note: Long term target is more a transition to a SPA, where everything is handled in the UI and only data/information is fetched through API, rather then rendering anything in the backend.

I do agree that Vue should be the long term target for this kind of page.
Here, we know we will share a lot of code with the SegmentEditorPanel that is not in Vue.
We tried to be faster by reusing what we already have and also not break what already works.

Add 'All Visits at the top' Reorder segments: fixed > selected > starred > others Add highlighted styles to fixed and selected segments Allow star/unstar segments Reorder data Add view, edit, and delete actions Synchronize UI between the editor panel and the management page Align number to the right Add right management Use translation for the page description Implement the search segment Add tooltip on view action Add a create segment button Add sparkline UX Meeting feedback Add a menu entry into the Administration menu + colored evolution Fix range selection Update evolution tooltip Add manage segment button Remove tooltip on sparkline when using a custom range Reorder administration menu and add an outlink icon Use generic table tooltip instead of custom ones Fix PHPCS Fix PHP errors Update the Scheduled Reports help box about segment Move JavaScript in a separate file and fix a bug when we unstar selected segment Bugfix: not all users are allowed to create segments

… page

sgiehl

I looked through most parts of the code (not really at the css parts, though) and left a couple of comments with suggestions, questions and concerns that came to my mind when looking through it.
I only performed some happy tests in the UI yet, but might be good to also do some edge case tests.

And another word on the vue component topic. I still believe it would have been more beneficial to directly do it. While trying to have things reusable and to also reuse existing this is a good manner, I think that should only be done for things that are expected to remain.
Now we will end up in having two things (Segment Editor & Management Page), that both rely on old code. If we want to migrate that to vue js, we will have to migrate both at the same time, or keep a lot legacy code until both parts are migrated.
If the management page would have been implemented as a new component with according stores and things like that directly, we might not have been able to reuse existing things, but the new code would have been cleaner and reusable as well. Then it might have been easier to migrate the old stuff step by step by switching it to new code where already possible.
So would be awesome to at least consider that for other stuff we start working on.

sgiehl · 2026-01-14T07:29:34Z

plugins/SitesManager/tests/UI/expected-screenshots/SitesManager_search_no_result.png

This change seems unexpected

sgiehl · 2026-01-26T09:56:37Z

plugins/Goals/Menu.php


        if (Piwik::isUserHasWriteAccess($idSite)) {
-            $menu->addMeasurableItem('Goals_Goals', $this->urlForAction('manage', array('idSite' => $idSite)), 40);
+            $menu->addMeasurableItem('Goals_Goals', $this->urlForAction('manage', array('idSite' => $idSite)), 15);


You better should not change that. If you want to add something after Goals, just use a higher number.
Decreasing the number here has the potential to break the order how our plugins are listed there.

sgiehl · 2026-01-26T10:00:54Z

plugins/SegmentEditor/Menu.php

+{
+    public function configureAdminMenu(MenuAdmin $menu)
+    {
+        $idSite = Request::fromRequest()->getIntegerParameter('idSite', 1);


You should not use a static default value here. A site with id 1, might not exist on an instance if it has been removed.

Good catch.
How can I create a link to the Dashboard that works for an environment where there is possibly no site selected?
The default idSite value in the code is always 0, but this doesn’t work.
Should I retrieve the idSite visible for the current user and take the first one?

Yes, something like that. Not sure if we already have something similar in place somewhere 🤔

sgiehl · 2026-01-26T15:02:10Z

plugins/SegmentEditor/Controller.php

+        foreach ($view->segmentList as $index => &$segment) {
+            $segment['fixed'] = $segment['fixed'] ?? false;
+            $segment['selected'] = $segment['definition'] === $this->currentSegmentDefinition;
+            $segment['dashboardUrl'] = '?module=CoreHome&action=index&idSite=' . $this->idSite . '&period=' . $this->period . '&date=' . $this->strDate . '&segment=' . urlencode($segment['definition']);


It might cause problems when attaching the segment to the main url query parameters. The UI might not be able to handle it correctly if it then differs between that and the parameters in hash part.
If you follow such a link, it e.g. is not really possible anymore to switch back to the All Visits segment, as the segment part remains in the query parameters.

Interesting! How can we create this kind of link in this case?

You can't do that properly in the backend, and that might not be needed all. A dynamic link with javascript should be quite easy to add. braodcast.buildReportingUrl() might be something that can be used.

plugins/SegmentEditor/Controller.php

sgiehl · 2026-01-26T16:45:55Z

plugins/SegmentEditor/javascripts/manageSegmentsPage.js

+        $deleteButton.attr('data-state', 'disabled');
+      }
+      window.SegmentEditorPanel.updateStarSegmentTitle($starButton, segment);
+      $editButton.attr('title', window.SegmentEditorPanel.getEditSegmentTitle(segment, canEdit));


That actually does not work properly. The fetched segment contains enable_only_idsite, but as a string value. As the method getEditSegmentTitle checks that in a boolean compare it results to be true all the time, causing the site specific message to be shown for global segments as well.

sgiehl · 2026-01-26T16:46:26Z

plugins/SegmentEditor/javascripts/manageSegmentsPage.js

+      }
+      window.SegmentEditorPanel.updateStarSegmentTitle($starButton, segment);
+      $editButton.attr('title', window.SegmentEditorPanel.getEditSegmentTitle(segment, canEdit));
+      $deleteButton.attr('title', window.SegmentEditorPanel.getDeleteSegmentTitle(segment, canEdit));


Same for getDeleteSegmentTitle

sgiehl · 2026-01-26T16:50:03Z

plugins/SegmentEditor/Controller.php

+        $allVisitsSegment = [
+            'definition' => '',
+            'name' => Piwik::translate('SegmentEditor_DefaultAllVisits'),
+            'fixed' => true,


This currently causes the all visits segment to always be highlighted, even if another segment is currently chosen. It looks a bit weird if two segments are highlighted at the same time.
Is there any specific reason why the All Visits row is always highlighted?

Because it's what the PO asked for

sgiehl · 2026-01-26T17:50:31Z

plugins/SegmentEditor/templates/manageSegments.twig

+                                        <a href="{{ segment.dashboardUrl }}" class="table-action icon-show" title="{{ 'SegmentEditor_SeeDashboardForThisSegment'|translate }}"></a>
+                                    {% endif %}
+                                    {% if segment.idsegment is defined %}
+                                        <button class="table-action icon-edit" data-edit-segment="{{ segment.idsegment }}"></button>


The way how segments are edited might not be perfect from a usability perspective. When you click edit it opens that segment editor. That might be fine, but if you change it, you will always have to click "Save & Apply", which will trigger the segment to be selected and the page to be reloaded.
In case there are a lot segments the page might take long to reload, which actually only the data of that one segment might require a reload.
But guess that's a trade of we might need to live with atm.

Yes, that’s what the PO asked for. It's a pragmatic solution to have a smaller PR and a shorter development time.

sgiehl · 2026-01-26T17:53:23Z

plugins/SegmentEditor/templates/manageSegments.twig

+                                        </svg>
+                                    </button>
+                                {% endif %}
+                            </td>


I think it would be awesome to also have some icons that show directly if a segment is a shared one and if it's shared across users and / or sites.
But that could be added in a later version as well.

Good idea, because it's hard to know for now.
Where should we trace this kind of idea?

tzi force-pushed the ux-326-2 branch from c419fe2 to f1b587f Compare December 12, 2025 11:37

tzi force-pushed the ux-326-2 branch 9 times, most recently from 13932db to 597f770 Compare December 23, 2025 08:26

tzi force-pushed the ux-326-2 branch 2 times, most recently from adcf8af to 6fb66bd Compare December 30, 2025 14:02

tzi force-pushed the ux-326-2 branch 2 times, most recently from fc0cb9b to e353f4f Compare January 12, 2026 10:49

tzi commented Jan 12, 2026

View reviewed changes

tzi removed the Pull Request WIP Indicates the current pull request is still work in progress and not ready yet for a review. label Jan 12, 2026

tzi added the Needs Review PRs that need a code review label Jan 12, 2026

tzi force-pushed the ux-326-2 branch 3 times, most recently from 58c8392 to ff37dbc Compare January 13, 2026 08:52

tzi mentioned this pull request Jan 13, 2026

Update UI screenshots after Administration menu change matomo-org/tag-manager#1077

Draft

tzi added this to the 5.7.0 milestone Jan 13, 2026

tzi force-pushed the ux-326-2 branch 5 times, most recently from 9b0745b to 6939639 Compare January 13, 2026 14:02

tzi mentioned this pull request Jan 13, 2026

Simplify tooltip handling in segment selector #23962

Merged

10 tasks

tzi force-pushed the ux-326-2 branch from 6939639 to 1fd639a Compare January 14, 2026 10:09

tzi commented Jan 14, 2026

View reviewed changes

tzi force-pushed the ux-326-2 branch from 1fd639a to 09dc053 Compare January 16, 2026 09:15

caddoo requested changes Jan 19, 2026

View reviewed changes

sgiehl modified the milestones: 5.7.0, 5.8.0 Jan 22, 2026

tzi added 5 commits January 26, 2026 11:19

Update UI screenshots and fix tests

a3514e5

Change translation key since the parameters changed

d4e4afe

No need to have write access to be able to see the segment management…

212bd61

… page

Fix UI feedback on failing star/unstar api calls

22bbd91

tzi force-pushed the ux-326-2 branch from 0d589fe to 22bbd91 Compare January 26, 2026 10:20

sgiehl requested changes Jan 26, 2026

View reviewed changes

First round of Stefan’s feedback

7230575

tzi force-pushed the ux-326-2 branch from a1a0815 to 7230575 Compare January 27, 2026 15:17

Update UI screenshots

65a268b

		$idSite = Request::fromRequest()->getIntegerParameter('idSite', 0);
		if (Piwik::isUserHasWriteAccess($idSite)) {

Uh oh!

Add a Segment Management Page #23885

Are you sure you want to change the base?

Add a Segment Management Page #23885

Uh oh!

Conversation

tzi commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Features

Data Synchronization with the Panel

Menus

Plugins

Checklist

Review

Uh oh!

tzi Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzi Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzi Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzi Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzi Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tzi Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caddoo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

tzi commented Dec 9, 2025 •

edited

Loading

tzi Jan 12, 2026 •

edited

Loading

tzi Jan 12, 2026 •

edited

Loading

tzi Jan 12, 2026 •

edited

Loading

tzi Jan 12, 2026 •

edited

Loading

tzi Jan 12, 2026 •

edited

Loading

tzi Jan 12, 2026 •

edited

Loading