> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scripting Properties

> Reference for configuration properties that control scripting and custom rendering behaviour in Nextedy PLANNINGBOARD.

See [Configuration Properties](/planningboard/reference/configuration-properties/index) for an overview of the configuration property system. For the scripting API surface that these properties interact with, see [Scripting API](/planningboard/reference/api/scripting-api) and [Config Script API](/planningboard/reference/api/config-script-api).

***

## Overview

Scripting properties let administrators supply custom JavaScript templates and data objects that the board evaluates at render time. The primary use case is customising how capacity tooltips, column labels, and per-plan data appear on the board.

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/vfRg9jxXRntLqZFW/planningboard/diagrams/reference/configuration-properties/scripting-properties/diagram-1.svg?fit=max&auto=format&n=vfRg9jxXRntLqZFW&q=85&s=93aff8d30f739cbf7dc036e1b27cbaf3" alt="Board configuration hierarchy showing columnTooltipTemplate, scriptData, and setCurrentView() as the three scripting properties" width="700" height="240" data-path="planningboard/diagrams/reference/configuration-properties/scripting-properties/diagram-1.svg" />
</Frame>

***

## Property Reference

### `columnTooltipTemplate`

| Property                | Type                   | Default                         | Scope                    |
| ----------------------- | ---------------------- | ------------------------------- | ------------------------ |
| `columnTooltipTemplate` | `string` or `function` | *(default tooltip — see below)* | Board / scheduler config |

Controls the HTML rendered inside capacity tooltips on Plan columns. Accepts either a static string template or a JavaScript function that receives the column and row objects and returns an HTML string.

When `columnTooltipTemplate` is **not configured**, the board falls back to the default tooltip format, which shows aggregate capacity metrics:

| Field shown in default tooltip | Description                          |
| ------------------------------ | ------------------------------------ |
| Capacity                       | Total capacity for the column period |
| Done                           | Completed work within the column     |
| Todo                           | Remaining work within the column     |
| Available                      | Remaining capacity after allocation  |

When `columnTooltipTemplate` **is configured**, the template receives `column` and `row` objects and can render per-user allocation breakdowns. The rendered HTML is stored on the `.capacityLoad` element's `data-html` attribute and displayed by the tooltip engine.

**Per-user allocation format (custom template)**

A custom template can expose the following data per team member:

| Field          | Description                                                                  |
| -------------- | ---------------------------------------------------------------------------- |
| Available      | `totalCapacity - allocatedCapacity`; negative values indicate overallocation |
| Allocated      | Sum of remaining estimates for tasks assigned to this user within the plan   |
| Total Capacity | User's total capacity from the team calendar for the plan period             |

<Warning title="Overallocation indicator">
  When `availableCapacity` is negative for a user, the tooltip renders the value in red text. This is a visual-only signal — the board does not prevent further assignment when a user is overallocated.
</Warning>

**Configuration example — function form**

```javascript theme={null}
columnTooltipTemplate: function(column, row) {
    var html = '<div class="capacity-tooltip">';
    // column.scriptData contains per-plan custom data (see scriptData property)
    if (column.scriptData && column.scriptData.userCapacities) {
        column.scriptData.userCapacities.forEach(function(u) {
            var avail = u.availableCapacity;
            var color = avail < 0 ? 'red' : 'inherit';
            html += '<div><strong>' + u.userId + '</strong>: '
                  + '<span style="color:' + color + '">' + avail + '</span>'
                  + ' / ' + u.allocatedCapacity
                  + ' / ' + u.totalCapacity + '</div>';
        });
    }
    html += '</div>';
    return html;
}
```

<Note title="Re-render required">
  After programmatically changing `columnTooltipTemplate`, call `setCurrentView()` to trigger a re-render. Without this call, the board continues showing the previous tooltip template.
</Note>

***

### `scriptData`

| Property     | Type     | Default     | Scope                            |
| ------------ | -------- | ----------- | -------------------------------- |
| `scriptData` | `object` | `undefined` | Per-plan (`userData.scriptData`) |

Stores arbitrary custom data per plan in the scheduler configuration. This data is attached to each plan's `userData` object and is available inside `columnTooltipTemplate` functions and other custom rendering logic via `column.scriptData`.

The server-side capacity helper (`ColumnDataScriptHelper`) populates `scriptData` with capacity metrics for each plan. The board configuration is embedded server-side — not delivered via XHR — so `scriptData` values are available immediately when the board initialises.

**Fields populated by the capacity helper**

| Field                    | Type     | Description                                                           |
| ------------------------ | -------- | --------------------------------------------------------------------- |
| `userCapacities`         | `array`  | Per-user capacity breakdown for the plan period (see below)           |
| `childRemainingEstimate` | `number` | Aggregate sum of remaining estimates from all child tasks in the plan |
| `allChildTasksCount`     | `number` | Total count of child task work items in the plan                      |
| `assigneeCount`          | `number` | Number of unique assignees; always equals `userCapacities.length`     |

**`userCapacities` entry structure**

| Field               | Type     | Description                                                                                                |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `userId`            | `string` | Polarion user ID of the assignee                                                                           |
| `allocatedCapacity` | `number` | Sum of remaining estimates for tasks assigned to this user; rounded to 1 decimal place                     |
| `totalCapacity`     | `number` | Total capacity from the team calendar for the plan period; defaults to `0.0` when no calendar entry exists |
| `availableCapacity` | `number` | `totalCapacity - allocatedCapacity`; negative indicates overallocation; rounded to 1 decimal place         |

<Info title="Zero fallback for missing calendar data">
  Users without a team calendar entry for a plan's date range receive `totalCapacity: 0.0`. This means `availableCapacity` will equal `-allocatedCapacity` (always negative) for those users, which may trigger the overallocation indicator even when total capacity is simply unknown. Verify team calendar coverage when unexpected overallocation warnings appear.
</Info>

**Configuration example — accessing scriptData in a tooltip template**

```javascript theme={null}
// Accessing scriptData from a column object inside columnTooltipTemplate
columnTooltipTemplate: function(column, row) {
    var data = column.scriptData; // populated server-side per plan
    if (!data) return ''; // guard: scriptData may be absent if capacity helper is not configured

    var lines = ['<strong>Team capacity summary</strong>'];
    lines.push('Tasks: ' + data.allChildTasksCount);
    lines.push('Remaining: ' + data.childRemainingEstimate + 'h');
    lines.push('Assignees: ' + data.assigneeCount);
    return lines.join('<br>');
}
```

***

### `setCurrentView()`

| Method             | Returns | When to call                                                                            |
| ------------------ | ------- | --------------------------------------------------------------------------------------- |
| `setCurrentView()` | `void`  | After any programmatic change to scheduler configuration (e.g. `columnTooltipTemplate`) |

A method on the scheduler/board instance that refreshes the current view. Must be called after programmatically updating `columnTooltipTemplate` or other view configuration properties to trigger a re-render. Without calling `setCurrentView()`, the board continues to display stale rendered output.

<Warning title="Not a configuration property">
  `setCurrentView()` is a method on the board/scheduler instance, not a configuration property you set in a config object. It is documented here because it is the required companion to any programmatic change to scripting configuration properties such as `columnTooltipTemplate`.
</Warning>

***

## Related Configuration Properties

Scripting properties interact closely with capacity configuration. See the following references for the capacity properties that drive the data available in `scriptData`:

* [Capacity Properties](/planningboard/reference/configuration-properties/capacity-properties) — `nextedy.gantt.calendarHolder`, `nextedy.gantt.useTeamCapacityModifiers`, `nextedy.gantt.capacityModifierAField`, and related settings
* [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — widget-level capacity parameters (`capacityLoad`, `userCapacityLoad`, `multiCapacityLoad`, `hoursPerDay`)

For the scripting API objects and functions available within templates:

* [Scripting API](/planningboard/reference/api/scripting-api) — overview of the scripting API
* [Config Script API](/planningboard/reference/api/config-script-api) — configuration script API reference
* [Data Script API](/planningboard/reference/api/data-script-api) — data script API reference

***

## Configuration Example

The following example shows a board configuration that uses `scriptData` and a custom `columnTooltipTemplate` together to render a per-user capacity tooltip with overallocation highlighting.

```javascript theme={null}
// Board / scheduler config object (embedded server-side)
{
    // ... other board configuration properties ...

    columnTooltipTemplate: function(column, row) {
        var data = column.scriptData;
        if (!data || !data.userCapacities || data.userCapacities.length === 0) {
            // Fall back to default rendering when no user capacity data is available
            return null;
        }

        var rows = data.userCapacities.map(function(u) {
            var avail  = u.availableCapacity;
            var color  = avail < 0 ? '#e53935' : '#43a047';
            var label  = avail < 0 ? '(overallocated)' : '';
            return '<tr>'
                + '<td>' + u.userId + '</td>'
                + '<td>' + u.allocatedCapacity + 'h</td>'
                + '<td>' + u.totalCapacity + 'h</td>'
                + '<td style="color:' + color + '">' + avail + 'h ' + label + '</td>'
                + '</tr>';
        });

        return '<table style="font-size:11px">'
            + '<thead><tr><th>User</th><th>Allocated</th><th>Total</th><th>Available</th></tr></thead>'
            + '<tbody>' + rows.join('') + '</tbody>'
            + '</table>'
            + '<div style="margin-top:4px;font-size:10px">Tasks: '
            + data.allChildTasksCount + ' | Remaining: ' + data.childRemainingEstimate + 'h</div>';
    }
}
```

After applying this configuration, call `setCurrentView()` on the board instance to trigger a re-render.

***

## Limitations

<Info title="Verify in application">
  The scripting properties documented here (`columnTooltipTemplate`, `scriptData`) are confirmed by test evidence (`capacityTooltipRendering.cy.ts`, `capacityHelperData.cy.ts`). The full set of scriptable configuration hooks beyond tooltip rendering is not confirmed by the available source context — do not assume that other rendering phases (card content, swimlane labels, etc.) expose equivalent template hooks unless confirmed in the product.
</Info>

* **`columnTooltipTemplate` only** — custom scripting is confirmed for column capacity tooltips. Card-level, swimlane-level, and other rendering phases do not have confirmed equivalent scripting hooks in the available source context.
* **Server-side embedding** — `scriptData` is populated server-side and embedded into the board configuration at render time. It is not refreshed via live XHR after initial load.
* **No multi-assignee capacity distribution** — capacity calculations assign effort to the named assignee only; there is no distribution across multiple assignees per work item. See [Capacity Properties](/planningboard/reference/configuration-properties/capacity-properties) for the full list of known capacity limitations.
* **PARENT assignment mode incompatibility** — the `PARENT` swimlane assignment mode does not support plan normalization (`planCellsMode`). Scripting properties that rely on normalization data are unaffected when `planCellsMode` is disabled, but custom templates must account for the absence of normalization-derived fields when this mode is in use.

<Accordion title="Sources">
  **KB Articles**

  * Planningboard: Customizable Statistics and Capacity Indicators
  * Planningboard Widget Parameters
  * Troubleshooting Script Errors in Planningboard

  **Support Tickets**

  * [#6174](https://support.nextedy.com/helpdesk/tickets/6174)

  **Source Code**

  * `capacityTooltipRendering.cy.ts`
  * `PlanningBoardWidgetRenderer.java`
  * `viewSetup.vm`
  * `capacityHelperData.cy.ts`
  * `unplanned_sidebar.js`
</Accordion>