> ## 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.
# Advanced Parameters
> Advanced parameters give you low-level control over Nextedy PLANNINGBOARD widget behaviour: the scripting hook, instance identity, rendering mode, and item-load ceiling.
For the full parameter surface, see the [Widget Parameters](/planningboard/reference/widget-parameters/index) reference index.
***
## Parameters
### Instance and Rendering
| Name | Type | Default | Description |
| --------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pbId` | `string` | `""` | Unique identifier for this Planningboard instance. Required when two or more board widgets appear on the same Polarion page — each board must have a distinct `pbId` so the client can distinguish them. |
| `inView` | `boolean` | `false` | When `true`, renders the board in *view mode*: a modal parameter-editor overlay is shown instead of rendering the board inline as a standalone page. Use `false` (the default) for a standard embedded board widget. |
| `version` | `string` | `""` | Version string appended to the board's iframe `src` URL for cache-busting. Ensures users receive the latest board code after a plugin upgrade. Set automatically by the widget renderer; you do not normally need to set this manually. |
***
### Scripting Hook
| Name | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `advScript` | `string` | `""` | Advanced JavaScript code to execute in the Planningboard context. The script is exposed as `window.__pbAdvScript` and runs after the board initialises. Use this for custom board-level logic that cannot be achieved through widget parameters alone. See [Scripting API](/planningboard/reference/api/scripting-api) for the API surface available to scripts. |
`advScript` executes arbitrary JavaScript in the Polarion page context. Incorrect scripts can break board rendering or interfere with Polarion navigation. Test in a non-production environment before deploying.
***
### Item Loading
| Name | Type | Default | Description |
| ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxItems` | `number` | `1000` | Maximum number of work items loaded into the board. If your query matches more items than this ceiling, the board silently truncates the result set. Increase only when necessary — very large item sets affect initial load time. |
The default `maxItems` value of `1000` is a balance between completeness and rendering performance. Boards with hundreds of cards across many swimlanes may feel sluggish; narrow your work-item query rather than raising `maxItems`.
***
### Sidebar Fields
| Name | Type | Default | Description |
| --------------- | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sidebarFields` | `string[]` | `[]` | Array of Polarion field IDs to display in the Work Item Properties sidebar when a card is clicked. If empty, the board falls back to a default field set (title, status, plannedIn). Individual users can further personalise visible fields using the gear icon in the sidebar — those per-user additions apply to all work items of the same type for that user only. |
**Example — configuring sidebar fields:**
```json theme={null}
["title", "status", "plannedIn", "assignee", "priority", "description"]
```
Field IDs must match the exact Polarion field identifiers for your project. Custom fields are referenced by their custom field ID.
`sidebarFields` sets the *default* fields presented to all users of this board instance. Per-user customisation (via the gear icon) layered on top is user-scoped and does not affect the widget parameter.
***
### Unplanned Sidebar Hierarchy
| Name | Type | Default | Description |
| ----------------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PARAMETER_US_DEPTH` | `number` | See application | Controls how many levels of parent work items are loaded when building the hierarchy in the unplanned sidebar. Higher values show deeper parent chains but increase load time and memory usage. |
| `PARAMETER_PARENTS_LINK_ROLE` | `string` | See application | Specifies which Polarion link role defines parent-child relationships for the unplanned sidebar hierarchy. Only link roles registered in the Polarion project configuration are valid. Incorrect or missing values result in a flat (non-hierarchical) unplanned sidebar. |
**Depth trade-offs:**
| Depth Value | Effect |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `1` | Loads only direct parents — fast, minimal memory |
| `2` | Loads grandparents — supports two-level feature/story hierarchies |
| `3+` | Deep hierarchies — use only when the project structure requires it; performance degrades with each additional level |
Each additional depth level multiplies the number of parent work items fetched. On large projects with thousands of items, `PARAMETER_US_DEPTH` values above `2` can significantly increase board load time.
***
## Parameter Visibility and Page Parameters
By default, Planningboard widget parameters are accessible through the gear icon on the embedded widget. There is no built-in option to permanently display the parameter controls above the board without user interaction.
Whether Polarion page parameters (`$pageParameters.xxx`) can be used to drive Planningboard widget values dynamically is not confirmed in the current source context. Based on ticket evidence, Planningboard swimlane configuration does **not** support Polarion page parameters for dynamic team filtering — a static workaround (separate Planningboard page per team configured with hardcoded swimlane values) is the supported approach. See [Swimlanes (Rows) Parameters](/planningboard/reference/widget-parameters/swimlanes-parameters) for swimlane configuration options.
***
## Configuration Example
The following example shows a widget instance with a unique `pbId`, a 500-item cap, custom sidebar fields, and an `advScript` that logs initialisation to the browser console.
```properties theme={null}
pbId = sprint-board-q3
inView = false
maxItems = 500
sidebarFields = ["title","status","plannedIn","assignee","storyPoints"]
advScript = console.log('Planningboard sprint-board-q3 initialised');
```
**Scenario:** A sprint Planningboard embedded on a LiveDoc page alongside a Gantt widget. Setting `pbId = sprint-board-q3` prevents the two widgets from sharing client state. `maxItems = 500` keeps load time acceptable for a project with a large backlog. The sidebar exposes story points alongside the standard fields so planners do not need to open the work item form.
***
## Parameter Interaction Diagram
***
## Related References
* [Widget Parameters](/planningboard/reference/widget-parameters/index) — full parameter index
* [Work Items Parameters](/planningboard/reference/widget-parameters/work-items-parameters) — query, sort, and dependency configuration
* [Plans (Columns) Parameters](/planningboard/reference/widget-parameters/plans-parameters) — plan type, count, and column link
* [Swimlanes (Rows) Parameters](/planningboard/reference/widget-parameters/swimlanes-parameters) — assignment types and row configuration
* [Scripting API](/planningboard/reference/api/scripting-api) — JavaScript API available to `advScript`
* [Config Script API](/planningboard/reference/api/config-script-api) — configuration scripting reference
**KB Articles**
* Planningboard Widget Parameters
* Planningboard: Customizable Statistics and Capacity Indicators
* Planningboard interface & basic interactions
**Support Tickets**
* [#6607](https://support.nextedy.com/helpdesk/tickets/6607)
* [#6546](https://support.nextedy.com/helpdesk/tickets/6546)
* [#5879](https://support.nextedy.com/helpdesk/tickets/5879)
**Source Code**
* `widget.vm`
* `PlanningBoardWidgetRenderer.java`
* `PlanningBoardWidget.java`
* `Config.java`
* `planningboard.js`