Advanced Parameters

For the full parameter surface, see the Widget Parameters 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 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.

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:

["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.

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

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

Diagram mapping each widget parameter (pbId, inView, version, maxItems, sidebarFields, advScript) to its effect on the Planningboard instance

Widget Parameters — full parameter index
Work Items Parameters — query, sort, and dependency configuration
Plans (Columns) Parameters — plan type, count, and column link
Swimlanes (Rows) Parameters — assignment types and row configuration
Scripting API — JavaScript API available to advScript
Config Script API — configuration scripting reference

Sources

KB Articles

Planningboard Widget Parameters
Planningboard: Customizable Statistics and Capacity Indicators
Planningboard interface & basic interactions

Support Tickets

Source Code

widget.vm
PlanningBoardWidgetRenderer.java
PlanningBoardWidget.java
Config.java
planningboard.js

Parameters

Instance and Rendering

Scripting Hook

Item Loading

Sidebar Fields

Unplanned Sidebar Hierarchy

Parameter Visibility and Page Parameters

Configuration Example

Parameter Interaction Diagram

​Parameters

​Instance and Rendering

​Scripting Hook

​Item Loading

​Sidebar Fields

​Unplanned Sidebar Hierarchy

​Parameter Visibility and Page Parameters

​Configuration Example

​Parameter Interaction Diagram

​Related References

Parameters

Instance and Rendering

Scripting Hook

Item Loading

Sidebar Fields

Unplanned Sidebar Hierarchy

Parameter Visibility and Page Parameters

Configuration Example

Parameter Interaction Diagram

Related References