> ## 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.

# Document Tree and Link Renderer

> Reference for the document tree and the link renderer that Nextedy RISKSHEET hands to server-render scripts: reading the linked work items of a document and rendering work item and document links.

`serverRender` scripts receive two objects that make columns showing linked work items much faster on large sheets:

| Variable | Purpose |
| - | - |
| `$tree` | Reads the work items linked to the sheet's document — by link role, direction and work item type — and answers which items hang under which. |
| `$render` | Renders a work item or a document as a link. |

Both are available since Risksheet 26.11.0, in every `serverRender` script next to the [other context variables](https://learn.nextedy.com/risksheet/reference/columns/server-render-columns.md#velocity-context-variables). For a worked example, see [Speed Up Server-Render Columns with the Document Tree](https://learn.nextedy.com/risksheet/guides/advanced/speed-up-server-render-columns-with-the-document-tree.md).

![The Mitigations columns of a sheet with a server-rendered column of risk item links next to each task](https://mintcdn.com/none-17b4493f/7K9VJz-M40Ht1WZc/risksheet/images/speed-up-server-render-columns-with-the-document-tree/also-mitigates-column.png?fit=max\&auto=format\&n=7K9VJz-M40Ht1WZc\&q=85\&s=e8aabe5bd35a4cbd858a96d2b77442bf)

A task column built with the document tree and the link renderer, listing the risk items each control mitigates.

## `$tree` — Describe the Tree

A tree starts at a document and adds one level per hop. Every call returns a new description, so a partly built one can be kept in a variable and reused.

| Method | Description |
| - | - |
| `$tree.from(document)` | Starts a tree at the work items of a document. In a `serverRender` script, pass `$module`, the document the sheet shows. |
| `types([...])`, `type('id')` | Before the first hop: the work item types of the root level. |
| `expandLink()` | Adds a level: the items the current level's items link to (links the current items own). |
| `expandBacklink()` | Adds a level: the items that link to the current level's items. |
| `expandAnyLink()` | Adds a level: links in either direction. |
| `byRoles([...])`, `byRole('id')` | Only links of these link roles on the last hop. |
| `byTypes([...])`, `byType('id')` | Only items of these work item types on the last hop; before the first hop, the same as `types`. |
| `load()` | Reads the tree and returns the loaded tree described below. |

Type and role IDs are trimmed, so `['risk', ' task']` matches `task`.

```velocity theme={null}
#set($q = $tree.from($module).types(['risk']))
#set($q = $q.expandBacklink().byRole('mitigates').byType('task'))
#set($q = $q.expandLink().byRole('mitigates').byType('risk'))
#set($t = $q.load())
```

> [!WARNING]
>
> **Do not break a call chain across lines**
>
> Velocity does not continue `$tree.from(...).types(...)` on the next line: a chain split over several lines leaves the cell empty. Keep each chain on one line, or build the description one hop per `#set`, as above.

Items are read with the permissions of the user who opened the sheet.

## The Loaded Tree

| Method | Returns |
| - | - |
| `roots()` | The items of the root level, ordered by work item ID. |
| `children(item)` | The items on the next level under `item`, ordered by work item ID. `item` can be `$item`, an item from another `children(...)` call, or a work item from the older Polarion API. |
| `hasChildren(item)` | Whether `item` has any child on the next level. |
| `isRoot(item)` | Whether `item` is on the root level. |
| `depth()` | The number of levels below the root. |

Items the user may not read, and items that no longer exist, are left out of every list. Field values of the returned items are read with the user's permissions, as with `$item`.

IDs are ordered by their prefix and then by their number, so `RSK-99` comes before `RSK-100`.

### After a Save

After a save, `roots()` of a tree that starts at the sheet's risk items returns only the saved risk items until the sheet is reloaded. A script that lists all risk items of the document through `roots()` shows the full list again after the next reload.

### Revisions and Baselines

On a document opened in a revision or a baseline, `load()` reads the links as they were in that revision. Where the links of that revision cannot be read, the tree is empty rather than showing today's links, and the Polarion server log says so.

### Size Limit

A tree holds at most 500,000 rows, counting every item of the root level and every link it reaches, across all levels. A tree beyond the limit is empty, and the Polarion server log names the limit. Administrators can change it by adding `nextedy.risksheet.tree.maxRows=<rows>` to `polarion.properties` and restarting Polarion. A higher limit lets a larger tree use more server memory.

## `$render` — Render a Link

| Call | Renders |
| - | - |
| `$render.link(workItem)` | The type icon, the ID, then `-` and the title. The link opens the item in the Polarion window. |
| `$render.link(document)` | The document's title, linking to the document. Pass `$module` for the sheet's document. |
| `$render.withTitle(false).link(...)` | The icon and ID only; the title becomes the tooltip. |
| `$render.withIcon(false).link(...)` | Leaves out the type icon. |
| `$render.target('_blank').link(...)` | Opens the link in a new browser tab. |

The options can be chained, for example `$render.target('_blank').withTitle(false).link($r)`. `link(...)` accepts `$item`, the items `$tree` returns and work items or documents from the older Polarion API, and renders nothing for an empty value or an item that cannot be resolved.

The links look the same as the sheet's own link cells with [`global.simpleLinks`](https://learn.nextedy.com/risksheet/reference/configuration/properties-index#global-settings-global) turned on.

## See Also

* [Speed Up Server-Render Columns with the Document Tree](https://learn.nextedy.com/risksheet/guides/advanced/speed-up-server-render-columns-with-the-document-tree.md) — rewrite a column step by step
* [Server Render Columns](https://learn.nextedy.com/risksheet/reference/columns/server-render-columns.md) — column properties and the other context variables
* [Velocity Template Context](https://learn.nextedy.com/risksheet/reference/api/velocity-context.md) — Velocity context across Risksheet templates
* [Large Sheets](https://learn.nextedy.com/risksheet/concepts/large-sheets.md) — where the load time of a large sheet goes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.