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

# UI and Display Parameters

> This page is a complete reference for the Nextedy PLANNINGBOARD widget parameters that control the board's visual presentation, sidebar behavior, toolbar availability, and card display.

## Parameter overview

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/vfRg9jxXRntLqZFW/planningboard/diagrams/reference/widget-parameters/ui-parameters/diagram-1.svg?fit=max&auto=format&n=vfRg9jxXRntLqZFW&q=85&s=5068a5e59046356da5db473da3e4e384" alt="Widget Parameters grouped into Sidebar Fields, Board Rendering, Dependency Visualization, Unplanned Sidebar, and Advanced, each listing its parameters and what they control" width="760" height="560" data-path="planningboard/diagrams/reference/widget-parameters/ui-parameters/diagram-1.svg" />
</Frame>

***

## Sidebar fields

When a user clicks a card, the **Work Item Properties** sidebar opens on the right. The fields shown there are controlled by the `sidebarFields` parameter.

| Name            | Type    | Default | Description                                                                                      |
| --------------- | ------- | ------- | ------------------------------------------------------------------------------------------------ |
| `sidebarFields` | `array` | `[]`    | Array of Polarion field IDs displayed in the Work Item Properties sidebar when a card is opened. |

### Behavior

* The default value is an empty array (`[]`). When no fields are configured, the sidebar falls back to application-level defaults (confirmed as `title`, `status`, and `plannedIn` from the source).
* Users can additionally personalize their own sidebar view via the **Select Fields** button (gear icon) inside the sidebar — this is per-user, per-work-item-type, and does not override the widget parameter.
* Saving changes in the sidebar preserves the user's swimlane position and scroll location; the board does not jump back to the top.

### Configuration example

```properties theme={null}
sidebarFields = title, description, assignee, status, plannedIn, severity
```

<Note title="Field ID casing">
  Use the exact Polarion field ID as it appears in project configuration. Wrong casing fails silently — the field is omitted from the sidebar without an error message.
</Note>

***

## Board rendering mode

| Name     | Type      | Default | Description                                                                                                                                                                                                                                |
| -------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inView` | `boolean` | `false` | When `true`, renders the board in **view mode**: widget parameters are editable via a modal overlay instead of the standard inline parameter editor. When `false`, the board renders as a standalone widget with its own parameter editor. |
| `pbId`   | `string`  | `""`    | Unique identifier for this board instance. Required when embedding multiple Planningboard widgets on the same Polarion page to prevent ID collisions.                                                                                      |

### Notes on `inView`

* In view mode the board is rendered inside an iframe with a modal editor overlay for parameters.
* If a page hosts only one Planningboard widget, `inView` can remain `false`.

### Notes on `pbId`

* When two or more Planningboard widgets appear on the same LiveDoc or Wiki page, each must have a distinct `pbId` value.
* The value is appended to the iframe `src` URL and used in DOM element IDs.

<Warning title="Multiple boards on one page">
  If you place more than one Planningboard widget on the same page without setting a unique `pbId` for each, the boards may interfere with each other's state. Always set distinct `pbId` values in multi-board layouts.
</Warning>

### Configuration example

```properties theme={null}
pbId = sprint-board-2
inView = false
```

***

## Dependency visualization

The **Show Dependencies** toolbar button reveals dependency arrows between cards. The arrows are drawn only for the link roles configured here.

| Name                  | Type     | Default | Description                                                                        |
| --------------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
| `dependencyLinkRoles` | `string` | —       | Polarion link role ID whose links are displayed as dependency arrows on the board. |

### Behavior

* If `dependencyLinkRoles` is not set, the **Show Dependencies** toolbar button has no effect — no arrows are drawn.
* The card-level **Show Links** quick action (hover over a card) uses the same link role to highlight related cards and hide unrelated ones.
* Setting this parameter also enables the **Add Link** quick action on cards.

<Tip title="Enable Show Dependencies in the toolbar">
  The **Show Dependencies** toolbar button is only functional when `dependencyLinkRoles` is configured. Document the intended link role ID from your Polarion project (for example, `depends_on`) and set it here.
</Tip>

### Configuration example

```properties theme={null}
dependencyLinkRoles = depends_on
```

***

## Unplanned sidebar hierarchy

The **Unplanned section** on the right of the board shows cards not yet assigned to a Plan. For team leads and project managers working with feature hierarchies, the sidebar can load parent items to provide context.

| Name              | Type     | Default | Description                                                                                                                                       |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `usDepth`         | `number` | —       | Number of parent levels to load above unplanned work items in the sidebar hierarchy. Controls how many ancestor levels are fetched and displayed. |
| `parentsLinkRole` | `string` | —       | Polarion link role ID used to traverse the parent-child relationship when building the unplanned sidebar hierarchy.                               |

### Behavior of `usDepth`

* A value of `0` or leaving the parameter unset shows only the work items themselves, with no parent context.
* A value of `1` loads the immediate parent of each unplanned item.
* Higher values load deeper ancestors but increase the number of API calls. On large boards with many unplanned items, deep hierarchies may noticeably increase load time.

### Behavior of `parentsLinkRole`

* Set this to the link role that defines the parent relationship in your Polarion project (for example, `parent` or `is_parent_of`).
* If left unset, no parent hierarchy is loaded regardless of the `usDepth` value.

<Tip title="Performance guidance">
  Start with `usDepth = 1` for most planning boards. Only increase the depth if your planning workflow requires visibility into grandparent items. Each additional level multiplies the number of items fetched for hierarchy rendering.
</Tip>

### Configuration example

```properties theme={null}
usDepth = 1
parentsLinkRole = parent
```

***

## Version and cache busting

| Name      | Type     | Default | Description                                                                                                                                                                                                                                    |
| --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | `string` | `""`    | Version string appended to the iframe `src` URL for cache busting. Ensures that users load the latest board code after a plugin update. This value is injected automatically by the Planningboard plugin and does not need to be set manually. |

<Info title="Verify in application">
  The `version` parameter is managed automatically by the Planningboard plugin. It is listed here for completeness. Do not set it manually in widget parameters.
</Info>

***

## Advanced script execution

| Name        | Type     | Default | Description                                                                                                                                 |
| ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `advScript` | `string` | `""`    | JavaScript code executed in the Planningboard context. The script is exposed as `window.__pbAdvScript` and runs after board initialization. |

### Usage notes

* Intended for advanced customization scenarios only. Consult the [Scripting API](/planningboard/reference/api/scripting-api) and [Config Script API](/planningboard/reference/api/config-script-api) for the available scripting surface.
* Incorrect scripts may break board initialization. Test in a non-production environment before deploying.
* Do not expose sensitive data in script content — the value is embedded in the page HTML.

<Warning title="Advanced use only">
  The `advScript` parameter exposes raw JavaScript execution inside the board context. Use it only when the standard widget parameters do not cover your customization requirement. Always refer to the [Scripting API](/planningboard/reference/api/scripting-api) for supported methods and properties.
</Warning>

### Configuration example

```javascript theme={null}
// advScript value — applied as a Polarion widget parameter
// Example: log the board configuration on load
console.log("Board config loaded", window.__pbConfig);
```

***

## Configuration example — complete UI parameters block

The following example shows a representative configuration for a sprint Planningboard used by a single Scrum team. Iterations are columns, assignees are swimlanes. The sidebar shows key fields, dependencies use the `depends_on` link role, and parent context is one level deep in the unplanned sidebar.

```properties theme={null}
# Sidebar: fields visible when a card is clicked
sidebarFields = title, description, assignee, status, plannedIn, storyPoints

# Dependency arrows in the board
dependencyLinkRoles = depends_on

# Unplanned sidebar: load one level of parent items
usDepth = 1
parentsLinkRole = parent

# Board instance identity (only needed if multiple boards on one page)
pbId = sprint-board

# Rendering mode
inView = false
```

***

## Toolbar controls reference

The following toolbar controls are affected by the UI parameters described on this page. See [Toolbar Controls](/planningboard/reference/ui-elements/toolbar) for the full toolbar reference.

| Toolbar Button           | Requires Parameter                                                                                                      |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Show Dependencies**    | `dependencyLinkRoles` must be set                                                                                       |
| **Show Unplanned**       | Unplanned sidebar always available; `usDepth` and `parentsLinkRole` affect its hierarchy                                |
| **Prioritize**           | No UI parameter — enabled via [Work Items Parameters](/planningboard/reference/widget-parameters/work-items-parameters) |
| **Toggle Resource Load** | Controlled via [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters)                    |

***

## Known limitations

* **Parameter visibility**: There is no built-in option to display widget parameters permanently above the board without clicking the gear icon. Parameters are only accessible through the standard Polarion widget parameter editor. There is no confirmed workaround for permanently exposing parameters above the widget.
* **Sidebar fields per work-item type**: The `sidebarFields` parameter applies globally to all work item types shown on the board. Per-type sidebar field sets are not supported at the widget parameter level; individual users can add type-specific fields using the gear icon inside the sidebar, but these additions are user-local.

***

## Related pages

* [Widget Parameters](/planningboard/reference/widget-parameters/index) — overview of all parameter groups
* [Work Items Parameters](/planningboard/reference/widget-parameters/work-items-parameters) — query, sort, and type filters
* [Capacity Parameters](/planningboard/reference/widget-parameters/capacity-parameters) — capacity bar configuration
* [Swimlanes (Rows) Parameters](/planningboard/reference/widget-parameters/swimlanes-parameters) — swimlane assignment types
* [Toolbar Controls](/planningboard/reference/ui-elements/toolbar) — toolbar button reference
* [Unplanned Sidebar](/planningboard/reference/ui-elements/sidebar) — unplanned section reference
* [Card Quick Actions](/planningboard/reference/ui-elements/card-quick-actions) — hover actions on cards
* [Scripting API](/planningboard/reference/api/scripting-api) — advanced scripting surface

<Accordion title="Sources">
  **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)
  * [#4714](https://support.nextedy.com/helpdesk/tickets/4714)

  **Source Code**

  * `widget.vm`
  * `PlanningBoardWidgetRenderer.java`
  * `PlanningBoardWidget.java`
  * `Config.java`
  * `viewSetup.vm`
</Accordion>