Skip to content

Tasks ID And Hover Card Developer Guide

Ed Mozley edited this page Nov 21, 2026 · 1 revision

Task ID, Company column and the hover card - Developer Guide

(5.8.0, #405, contributed by @cloudcogsio)

How the task ID, the Table's Company column and the details card that appears over a task in the Calendar and the Timeline are built. The user-facing description is Tasks; the merge review, with the script-running bug it fixed, is Task ID and hover card - review.


Files

File What it holds
assets/js/tasks-hover-card.js The card: one file, no dependencies, exposes window.TasksHoverCard
assets/js/tasks-calendar.js TasksHoverCard.init({ selector: '.cal-bar[data-hc]' }); each bar carries data-hc
assets/js/tasks-timeline.js init for .tl-bar[data-hc], .tl-row-label[data-hc]; suspend() while a bar is dragged
assets/js/tasks.js #ID on every board card (.task-card-id), the List view's ID column (.task-list-id) and its numeric sort
assets/js/tasks-table.js The Table's id and company_name columns, companyName(), loadCompanies()
assets/css/tasks.css .task-hover-card and its .thc-* parts; @media (hover: none) hides it
lang/*/tasks.php list.col_id, hover.subtask_of, hover.repeating, help lines

No schema, API or permission changed: everything the card shows is already in the task objects the pages load.


1. The ID

The board card and the List view print #${t.id} - an integer from the database, so it needs no escaping, but the title beside it still goes through esc():

// assets/js/tasks.js - the board card
<div class="task-card-title"><span class="task-card-id">#${t.id}</span>${esc(t.title)}</div>

The List view sorts by it as a number. Compared as text, #10 would come before #9:

if (sortField === 'id') { va = Number(a.id); vb = Number(b.id); }

In the Table it is an ordinary data-table column of type: 'number', hidden by default, so the engine sorts and filters it numerically.

2. The Company column

// assets/js/tasks-table.js
{ key: 'company_name', label: 'Company', type: 'string', defaultVisible: false, defaultOrder: 10,
  display: t => companyName(t.tenant_id) },

// A task with no tenant_id belongs to the Default company (the same rule as api/tasks/list.php).
function companyName(tenantId) {
    if (tenantId === null || tenantId === undefined || tenantId === '') {
        const def = companies.find(c => c.is_default);
        return def ? def.name : '';
    }
    const c = companies.find(x => String(x.id) === String(tenantId));
    return c ? c.name : '';
}
async function loadCompanies() {
    try {
        const d = await fetch('../../api/system/get_tenants.php?accessible=1').then(r => r.json());
        companies = (d && d.success && d.companies) ? d.companies : [];
    } catch (e) { companies = []; }
}

The names come from get_tenants.php?accessible=1 - the companies this analyst can reach, the same list the right-click Move to company offers - so the column can never name a company the reader could not otherwise see. A task whose company is not in that list shows blank rather than a raw id.

3. The hover card

The page side

A page tells the card which elements it covers, and puts a key on each - never task data:

// assets/js/tasks-calendar.js
TasksHoverCard.init({ selector: '.cal-bar[data-hc]' });
// ...when drawing a bar:
`<div class="cal-bar ..." data-hc="${TasksHoverCard.ref(t)}" onclick="openTask(${isProj ? t.source_task_id : t.id})">`

ref(task) stores the task object in a registry and hands back h1, h2... It works for any object - a real task or a projected repeat (t.projected, whose ID is source_task_id) - so a page needs no lookup of its own:

ref(task) {
    if (!task) return '';
    if (!task.__hc) {
        Object.defineProperty(task, '__hc', { value: 'h' + (nextKey++), enumerable: false });
    }
    if (registry.size > 20000) registry.clear();
    registry.set(task.__hc, task);
    return task.__hc;
},

The key is a non-enumerable property, so it never ends up in a JSON.stringify() of the task. init() may take its own resolve(el) instead of the registry, and a root to limit it to one part of the page.

Showing and hiding

One set of document-level listeners (mouseover, mousemove, mouseout) serves every page that calls init(). The card appears after 250 ms of resting on an element (60 ms when moving from one task straight to the next), and goes 120 ms after the pointer leaves - unless it moved onto the card, which can be scrolled. It hides on any mousedown outside it, on scroll, resize and Escape.

  • Not while dragging. onOver ignores events with a button held (e.buttons), and the Timeline calls TasksHoverCard.suspend(true) while it moves a bar.
  • Not on touch screens. @media (hover: none) { .task-hover-card { display: none; } } - a tap opens the task, as before.
  • Always inside the window. position() places it below the bar (or the pointer, for a tall element), else above, else on the larger side with max-height capped to the room there; then clamps it 8 px inside every edge.

What it shows, and how it stays safe

build(t) writes the head (ID, status, Upcoming repeat or Repeats), the title (struck through when the status is closed), Subtask of, then rows for priority, assignee, team, project and stage, contractor, start and due date (with Overdue), subtask progress, tags and a 220-character excerpt of the description.

  • Every value goes through esc(), which escapes all five HTML characters, quotes included.
  • Colours go into style only if they are hex: colour(c, fb) tests /^#[0-9a-f]{3,8}$/i and otherwise uses a grey. A colour is the one value that is not escaped (it is inside a CSS value), so it is the one that is checked.
  • The excerpt is parsed in an inert document:
/**
 * TRAP: parse with DOMParser, never innerHTML on an element of this page. An
 * element made by document.createElement belongs to the live document, so
 * even detached it loads <img src> and fires onerror - a description holding
 * one would run script on hover. DOMParser's document is inert: nothing loads
 * or runs. (Descriptions are sanitised on save; this must not depend on it.)
 */
function excerpt(html, max) {
    if (!html) return '';
    const doc = new DOMParser().parseFromString(String(html).replace(/<(br|\/p|\/div|\/li)[^>]*>/gi, ' '), 'text/html');
    const txt = ((doc.body && doc.body.textContent) || '').replace(/\s+/g, ' ').trim();
    return txt.length > max ? txt.slice(0, max).replace(/\s+\S*$/, '') + '…' : txt;
}

The branch first used the familiar div.innerHTML = html; div.textContent and it ran a planted <img onerror> the moment someone hovered; the same pattern was fixed in assets/js/mobile.js. See the review for how it was proved, and Code traps.


Traps

  • TRAP: createElement('div').innerHTML = untrusted is not safe "because the div is never attached". Use DOMParser (or <template>) to turn HTML into text.
  • A new page that shows tasks gets the card by calling TasksHoverCard.init({ selector }) and putting data-hc="${TasksHoverCard.ref(task)}" on its elements - not by building its own tooltip, and not by writing task data into attributes.
  • A new field on the card must be escaped with esc(); a new colour must go through colour().

Testing

By hand in the Calendar (month and week) and the Timeline (bars and row names): the card appears, never leaves the window near any edge, does not appear while a bar is dragged, and shows nothing script-like for a description holding <img src=x onerror=alert(1)> stored directly in the database.

Related: Tasks · Task board and subtasks - Developer Guide · Saved table views - Developer Guide

FreeITSM

Getting Started

Modules

Multi-tenancy (planned)

Responses to feedback

Blue sky thinking

Bugs resolved

Pull requests

Links

Clone this wiki locally