From 8f397eb25e3ddf26e6f12dea67d9aa3947e12b1e Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Thu, 5 Mar 2026 11:11:05 -0500 Subject: [PATCH 01/19] Simple link tracking --- app/views/layouts/_site_header.html.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/views/layouts/_site_header.html.erb b/app/views/layouts/_site_header.html.erb index bd152ea4..559a9e0e 100644 --- a/app/views/layouts/_site_header.html.erb +++ b/app/views/layouts/_site_header.html.erb @@ -9,7 +9,7 @@

- + MIT Libraries Homepage MIT Libraries logo From 1de21a694cc017350ea6e86e40b8ad6ad172966b Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:28:08 -0500 Subject: [PATCH 02/19] Matomo click helper function --- app/javascript/application.js | 1 + app/javascript/matomo_tracking.js | 27 +++++++++++++++++++++++++++ config/importmap.rb | 1 + 3 files changed, 29 insertions(+) create mode 100644 app/javascript/matomo_tracking.js diff --git a/app/javascript/application.js b/app/javascript/application.js index b3e67a5a..5eef2669 100644 --- a/app/javascript/application.js +++ b/app/javascript/application.js @@ -2,6 +2,7 @@ import "@hotwired/turbo-rails" import "controllers" import "loading_spinner" +import "matomo_tracking" // Show the progress bar after 200 milliseconds, not the default 500 Turbo.config.drive.progressBarDelay = 200; \ No newline at end of file diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js new file mode 100644 index 00000000..6dff39d1 --- /dev/null +++ b/app/javascript/matomo_tracking.js @@ -0,0 +1,27 @@ +// Matomo click event tracking via data attributes. +// +// Add `data-matomo-click="Category, Action, Name"` to any element to track +// clicks as Matomo events. The Name segment is optional. +// +// Examples: +// Download +// +// +// Event delegation on `document` means this works for elements loaded +// asynchronously (Turbo frames, content-loader, etc.) without re-binding. + +document.addEventListener("click", (event) => { + const el = event.target.closest("[data-matomo-click]"); + if (!el) return; + + const raw = el.dataset.matomoClick || ""; + const parts = raw.split(",").map((s) => s.trim()).filter(Boolean); + if (parts.length < 2) return; + + const [category, action, name] = parts; + + window._paq = window._paq || []; + const payload = ["trackEvent", category, action]; + if (name) payload.push(name); + window._paq.push(payload); +}); diff --git a/config/importmap.rb b/config/importmap.rb index 672f444c..ed7572b7 100644 --- a/config/importmap.rb +++ b/config/importmap.rb @@ -2,6 +2,7 @@ pin "application", preload: true pin "loading_spinner", preload: true +pin "matomo_tracking", preload: true pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true From b330074c4731050ae7220ccb6d4a7608b7e67bb6 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:28:31 -0500 Subject: [PATCH 03/19] Removed manual tracking test --- app/views/layouts/_site_header.html.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/views/layouts/_site_header.html.erb b/app/views/layouts/_site_header.html.erb index 559a9e0e..bd152ea4 100644 --- a/app/views/layouts/_site_header.html.erb +++ b/app/views/layouts/_site_header.html.erb @@ -9,7 +9,7 @@

- + MIT Libraries Homepage MIT Libraries logo From afe58f3098df1f42d4bf0ba6c17f28c350775cd2 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:35:32 -0500 Subject: [PATCH 04/19] Commenting click listener code --- app/javascript/matomo_tracking.js | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index 6dff39d1..c9dfdf8c 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -11,17 +11,25 @@ // asynchronously (Turbo frames, content-loader, etc.) without re-binding. document.addEventListener("click", (event) => { + + // Find the closest ancestor (or self) with the data-matomo-click attribute. const el = event.target.closest("[data-matomo-click]"); if (!el) return; + // Read the attribute value and break it apart into segments. Trim whitespace and ignore empty segments. const raw = el.dataset.matomoClick || ""; const parts = raw.split(",").map((s) => s.trim()).filter(Boolean); + + // Matomo requires at least a Category and an Action — bail out if we don't have both. if (parts.length < 2) return; + // Destructure into named variables; `name` will be undefined if not provided. const [category, action, name] = parts; + // Build the payload for trackEvent and push to Matomo. window._paq = window._paq || []; const payload = ["trackEvent", category, action]; if (name) payload.push(name); window._paq.push(payload); + }); From 42a85f2947d9e4a09d77747d3f2b476d8be66f2d Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:44:00 -0500 Subject: [PATCH 05/19] Visibility tracking helper refactor plus initial test attribute --- app/javascript/matomo_tracking.js | 102 ++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 12 deletions(-) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index c9dfdf8c..4b9cdda6 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -1,5 +1,6 @@ -// Matomo click event tracking via data attributes. +// Matomo event tracking via data attributes. // +// CLICK TRACKING // Add `data-matomo-click="Category, Action, Name"` to any element to track // clicks as Matomo events. The Name segment is optional. // @@ -9,27 +10,104 @@ // // Event delegation on `document` means this works for elements loaded // asynchronously (Turbo frames, content-loader, etc.) without re-binding. +// +// SEEN TRACKING +// Add `data-matomo-seen="Category, Action, Name"` to any element to fire a +// Matomo event as soon as that element is added to the DOM. The Name segment +// is optional. Works for elements present on initial page load and for elements +// injected later by Turbo frames or async content loaders. +// +// Examples: +//
...
+// ... -document.addEventListener("click", (event) => { - - // Find the closest ancestor (or self) with the data-matomo-click attribute. - const el = event.target.closest("[data-matomo-click]"); - if (!el) return; +// --------------------------------------------------------------------------- +// Shared helper +// --------------------------------------------------------------------------- - // Read the attribute value and break it apart into segments. Trim whitespace and ignore empty segments. - const raw = el.dataset.matomoClick || ""; - const parts = raw.split(",").map((s) => s.trim()).filter(Boolean); +// Parse a "Category, Action, Name" attribute string and push a trackEvent call +// to the Matomo queue. Name is optional; returns early if fewer than 2 parts. +function pushMatomoEvent(raw) { - // Matomo requires at least a Category and an Action — bail out if we don't have both. + // Split on commas, trim whitespace from each part, drop any empty strings. + const parts = (raw || "").split(",").map((s) => s.trim()).filter(Boolean); + // Matomo requires at least a Category and an Action. if (parts.length < 2) return; // Destructure into named variables; `name` will be undefined if not provided. const [category, action, name] = parts; - // Build the payload for trackEvent and push to Matomo. + // Ensure _paq exists even if the Matomo snippet hasn't loaded yet + // (e.g. in development). Matomo will replay queued calls once it initialises. window._paq = window._paq || []; const payload = ["trackEvent", category, action]; if (name) payload.push(name); window._paq.push(payload); - +} + +// --------------------------------------------------------------------------- +// Click tracking +// --------------------------------------------------------------------------- + +// Attach a single click listener to the entire document (event delegation). +// This catches clicks on any element, including those added to the DOM later +// by Turbo frames or async content loaders, without needing to re-bind. +document.addEventListener("click", (event) => { + // Walk up the DOM from the clicked element to find the nearest ancestor + // (or the element itself) that has a data-matomo-click attribute. + const el = event.target.closest("[data-matomo-click]"); + // If no such element exists in the ancestor chain, ignore this click. + if (!el) return; + + pushMatomoEvent(el.dataset.matomoClick); }); + +// --------------------------------------------------------------------------- +// Seen tracking +// --------------------------------------------------------------------------- + +// Track elements that have already been processed to avoid double-firing +// if the same node is observed more than once (e.g. re-attached to the DOM). +const seenTracked = new WeakSet(); + +// Fire a Matomo event for a single element if it carries data-matomo-seen +// and hasn't been tracked yet. +function trackIfSeen(el) { + // Only process element nodes (not text nodes, comments, etc.). + if (el.nodeType !== Node.ELEMENT_NODE) return; + // Skip if this element has already fired its seen event. + if (seenTracked.has(el)) return; + + // Check the element itself for the attribute. + if (el.dataset.matomoSeen) { + seenTracked.add(el); + pushMatomoEvent(el.dataset.matomoSeen); + } + + // Also check any descendants — content loaders often inject a whole subtree + // at once, so walking deep ensures every marked element is captured. + el.querySelectorAll("[data-matomo-seen]").forEach((child) => { + if (seenTracked.has(child)) return; + seenTracked.add(child); + pushMatomoEvent(child.dataset.matomoSeen); + }); +} + +// Process all elements already present in the DOM on initial page load. +document.querySelectorAll("[data-matomo-seen]").forEach((el) => { + seenTracked.add(el); + pushMatomoEvent(el.dataset.matomoSeen); +}); + +// Watch for any new nodes added to the DOM after initial load. +// MutationObserver fires synchronously after each DOM mutation, so it catches +// both Turbo frame renders and content-loader replacements immediately. +const observer = new MutationObserver((mutations) => { + mutations.forEach((mutation) => { + // Each mutation record lists the nodes that were added in this batch. + mutation.addedNodes.forEach(trackIfSeen); + }); +}); + +// Observe the entire document subtree so no async insertion is missed. +observer.observe(document.body, { childList: true, subtree: true }); From 7c9495f79b59fe24f54a3e76d02fb2c48dd767c1 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:47:42 -0500 Subject: [PATCH 06/19] Updated to make seen tracking work for Turbo:load --- app/javascript/matomo_tracking.js | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index 4b9cdda6..c8ad5b9b 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -111,3 +111,20 @@ const observer = new MutationObserver((mutations) => { // Observe the entire document subtree so no async insertion is missed. observer.observe(document.body, { childList: true, subtree: true }); + +// Turbo Drive navigation replaces document.body with a brand new element, +// which detaches the observer from the old body. Re-scan and re-observe on +// every turbo:load so full-page navigations are handled correctly. +// (Turbo frame and content-loader updates are covered by the observer above +// because they mutate within the existing body rather than replacing it.) +document.addEventListener("turbo:load", () => { + // Re-scan the new body for any seen elements that arrived with the navigation. + document.querySelectorAll("[data-matomo-seen]").forEach((el) => { + if (seenTracked.has(el)) return; + seenTracked.add(el); + pushMatomoEvent(el.dataset.matomoSeen); + }); + + // Re-attach the observer to the new document.body instance. + observer.observe(document.body, { childList: true, subtree: true }); +}); From 769c5d0cfc483d6495e5b14d2e1f8e30599b076d Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:51:14 -0500 Subject: [PATCH 07/19] Testing results found tracking --- app/views/search/results.html.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/views/search/results.html.erb b/app/views/search/results.html.erb index 15001a07..2985ef91 100644 --- a/app/views/search/results.html.erb +++ b/app/views/search/results.html.erb @@ -18,7 +18,7 @@ <% elsif @results.present? && @errors.blank? %> -

<%= results_summary(@pagination[:hits]) %>

+

<%= results_summary(@pagination[:hits]) %>

<%= tab_description %>

@@ -41,7 +41,7 @@ <% elsif @errors.blank? %>
-
+
<%= render partial: "no_results" %> <%# Note `results_callouts` is also displayed in results and no errors condition above %> From d7d5880258820aabd0900bfa3b2f5a064d6f649c Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:57:32 -0500 Subject: [PATCH 08/19] Add helper function to get tab names and apply to no results tracking --- app/javascript/matomo_tracking.js | 23 +++++++++++++++++++++++ app/views/search/results.html.erb | 4 ++-- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index c8ad5b9b..ed5e3788 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -128,3 +128,26 @@ document.addEventListener("turbo:load", () => { // Re-attach the observer to the new document.body instance. observer.observe(document.body, { childList: true, subtree: true }); }); + + +// =========================================================================== +// HELPER FUNCTIONS +// Custom JS to enhance the payload information we provide to Matomo. +// =========================================================================== + +// --------------------------------------------------------------------------- +// Get the name of the active search results tab, if any. +// --------------------------------------------------------------------------- +function getActiveTabName() { + var tabs = document.querySelector('#tabs'); + if (!tabs) { + return "None"; // #tabs not found + } + + var activeAnchor = tabs.querySelector('a.active'); + if (!activeAnchor) { + return "None"; // no active tab + } + + return activeAnchor.textContent.trim(); +} \ No newline at end of file diff --git a/app/views/search/results.html.erb b/app/views/search/results.html.erb index 2985ef91..b3a7df62 100644 --- a/app/views/search/results.html.erb +++ b/app/views/search/results.html.erb @@ -18,7 +18,7 @@ <% elsif @results.present? && @errors.blank? %> -

<%= results_summary(@pagination[:hits]) %>

+

<%= results_summary(@pagination[:hits]) %>

<%= tab_description %>

@@ -41,7 +41,7 @@ <% elsif @errors.blank? %>
-
+
<%= render partial: "no_results" %> <%# Note `results_callouts` is also displayed in results and no errors condition above %> From f169c56f07a4adbc5952a2e61e635df6084b1588 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 17:07:15 -0500 Subject: [PATCH 09/19] Attempt to interpolate function names in attributes for helper functions --- app/javascript/matomo_tracking.js | 34 +++++++++++++++++++++++++++++-- app/views/search/results.html.erb | 4 ++-- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index ed5e3788..852613ae 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -20,6 +20,16 @@ // Examples: //
...
// ... +// +// DYNAMIC VALUES ({{...}} interpolation) +// Wrap a helper name in double curly braces anywhere inside a segment to have +// it replaced with the return value of that function at tracking time. Helpers +// must be registered on `window.MatomoHelpers` (see bottom of this file). +// Multiple tokens in one segment are supported. +// +// Examples: +//

...

+// ... // --------------------------------------------------------------------------- // Shared helper @@ -34,8 +44,19 @@ function pushMatomoEvent(raw) { // Matomo requires at least a Category and an Action. if (parts.length < 2) return; + // Resolve any {{functionName}} tokens by calling the matching helper. + // Each token is replaced in-place, so it can appear anywhere in a segment. + const helpers = window.MatomoHelpers || {}; + const resolved = parts.map((part) => + part.replace(/\{\{(\w+)\}\}/g, (_, fnName) => { + const fn = helpers[fnName]; + // Call the function if it exists; otherwise leave the token as-is. + return (typeof fn === "function") ? fn() : `{{${fnName}}}`; + }) + ); + // Destructure into named variables; `name` will be undefined if not provided. - const [category, action, name] = parts; + const [category, action, name] = resolved; // Ensure _paq exists even if the Matomo snippet hasn't loaded yet // (e.g. in development). Matomo will replay queued calls once it initialises. @@ -150,4 +171,13 @@ function getActiveTabName() { } return activeAnchor.textContent.trim(); -} \ No newline at end of file +} + +// --------------------------------------------------------------------------- +// Register helpers on window.MatomoHelpers so they can be referenced with the +// {{functionName}} syntax in data-matomo-seen and data-matomo-click attributes. +// Add new helpers here as needed. +// --------------------------------------------------------------------------- +window.MatomoHelpers = { + getActiveTabName, +}; \ No newline at end of file diff --git a/app/views/search/results.html.erb b/app/views/search/results.html.erb index b3a7df62..5326bc92 100644 --- a/app/views/search/results.html.erb +++ b/app/views/search/results.html.erb @@ -18,7 +18,7 @@ <% elsif @results.present? && @errors.blank? %> -

<%= results_summary(@pagination[:hits]) %>

+

<%= results_summary(@pagination[:hits]) %>

<%= tab_description %>

@@ -41,7 +41,7 @@ <% elsif @errors.blank? %>
-
+
<%= render partial: "no_results" %> <%# Note `results_callouts` is also displayed in results and no errors condition above %> From 1601c54dab875951654d87a1adb8f8745c9d8d8f Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Thu, 12 Mar 2026 11:35:47 -0400 Subject: [PATCH 10/19] added child link tracking to -click attribute --- app/javascript/matomo_tracking.js | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index 852613ae..301012ed 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -80,6 +80,17 @@ document.addEventListener("click", (event) => { // If no such element exists in the ancestor chain, ignore this click. if (!el) return; + // Only fire when the click originated from an interactive element (link, + // button, or form control). This allows data-matomo-click to be placed on + // a container and track only meaningful interactions within it, ignoring + // clicks on surrounding text, padding, or decorative children. + const interactive = event.target.closest("a, button, input, select, textarea"); + if (!interactive) return; + + // Confirm the interactive element is actually inside the tracked container + // (guards against the unlikely case where closest() finds an ancestor of el). + if (!el.contains(interactive) && el !== interactive) return; + pushMatomoEvent(el.dataset.matomoClick); }); From 42550386861a38847d955f4e77387abaec791cce Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Thu, 12 Mar 2026 11:38:23 -0400 Subject: [PATCH 11/19] Experimenting with adding parent element click tracking to tabs --- app/views/search/_source_tabs.html.erb | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/app/views/search/_source_tabs.html.erb b/app/views/search/_source_tabs.html.erb index 1724a102..d7e4d7b0 100644 --- a/app/views/search/_source_tabs.html.erb +++ b/app/views/search/_source_tabs.html.erb @@ -1,5 +1,5 @@ -