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

# Customize Card Content

> Configure what information appears on each card using the Item Script in the Nextedy PLANNINGBOARD widget's Advanced Properties.

Cards in Planningboard display work item data by default, but you can tailor the visible fields, layout, and colors to match your team's planning workflow. Customization is done through a JavaScript-based **Item Script** that runs for each card as the board renders.

## Prerequisites

* The Planningboard widget is embedded in a Polarion LiveDoc or Wiki page
* You have editor access to the widget's Advanced Properties

***

<Steps>
  <Step title="Open the Item Script editor">
    1. Open the Polarion page containing your Planningboard widget.
    2. Switch to **Edit** mode on the page.
    3. Click the widget to select it, then open its properties.
    4. Navigate to **Advanced Properties** and locate the **Item Script** field.

    This script runs once per card and has access to three objects:

    | Object     | Description                                                                                                  |
    | ---------- | ------------------------------------------------------------------------------------------------------------ |
    | `wi`       | The current work item via the classic Polarion API (`IWorkItem`). Use for reading field values and links.    |
    | `workitem` | The same item through the rendering API. Use for building rendered HTML output (`workitem.fields()`, etc.).  |
    | `cli`      | The card's client-side configuration. Set properties on this object to control display, color, and behavior. |

    ***
  </Step>

  <Step title="Set the fields displayed on the card">
    Assign an HTML string to `cli.fieldsLine` to control what appears under the card title. You can render multiple fields and separate them with commas, spaces, or `<br>` line breaks.

    ```javascript theme={null}
    cli.fieldsLine =
      workitem.fields().get("initialStoryPoints").render().htmlFor().forFrame() +
      " sp, " +
      workitem.fields().priority().render().withText(true).withIcon(false).htmlFor().forFrame() +
      ", " +
      workitem.fields().status().render().withText(false).htmlFor().forFrame() +
      "<br>" +
      workitem.fields().assignee().render().htmlFor().forFrame();
    ```

    The `workitem.fields().get("fieldId")` pattern accesses any standard or custom field by its Polarion field ID. Chain `.render().htmlFor().forFrame()` to produce the formatted HTML fragment.

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/FFzowwCxsFbWFK4y/planningboard/assets/images/article-customize-the-content-of-the-car-158252e6.png?fit=max&auto=format&n=FFzowwCxsFbWFK4y&q=85&s=3d5fe7d505b199b0f9ea83ce517cc58e" alt="Two Planningboard cards showing two lines of item details: story points, priority, status on the first line and assignee with team in brackets on the second line" width="886" height="750" data-path="planningboard/assets/images/article-customize-the-content-of-the-car-158252e6.png" />
    </Frame>

    ***
  </Step>

  <Step title="Apply conditional logic by work item type">
    You can branch on any field value to render different content for different item types. The following example reads a custom enumeration field (`crType`) and applies a distinct fields line and card color for a specific value:

    ```javascript theme={null}
    var crType = wi.getValue("crType");
    if (crType != null && crType.getId() === "parentCR") {
      cli.fieldsLine =
        workitem.fields().get("swagEstimate").render().htmlFor().forFrame() +
        ", " +
        workitem.fields().priority().render().withText(true).withIcon(false).htmlFor().forFrame() +
        ", " +
        workitem.fields().status().render().withText(false).htmlFor().forFrame() +
        "<br>" +
        workitem.fields().assignee().render().htmlFor().forFrame() +
        " [" +
        workitem.fields().get("vendorTeam").render().htmlFor().forFrame() +
        "]";
      cli.cardColor = "#e3edff";
    } else {
      cli.fieldsLine =
        workitem.fields().get("initialStoryPoints").render().htmlFor().forFrame() +
        " sp, " +
        workitem.fields().priority().render().withText(true).withIcon(false).htmlFor().forFrame() +
        ", " +
        workitem.fields().status().render().withText(false).htmlFor().forFrame() +
        "<br>" +
        workitem.fields().assignee().render().htmlFor().forFrame() +
        " [" +
        workitem.fields().get("solutionTeam").render().htmlFor().forFrame() +
        "]";
    }
    ```

    ***
  </Step>

  <Step title="Inherit card color from a parent item">
    A common pattern is to color child cards based on a color value stored on their parent. This makes it easy to visually group items that belong to the same parent work item.

    **Set up the custom field on the parent type:**

    1. In Polarion Administration, add a custom field of type `String` to the parent work item type. Name it `pbColor` (or any ID you choose).
    2. For each parent item, enter a color value in this field: `blue`, `red`, `green`, `yellow`, or any valid CSS hex code.

    **Add the following to the Item Script:**

    ```javascript theme={null}
    // Allow the script to modify card attributes
    cli.readonly = false;

    // Traverse direct links to find the parent
    var i = wi.getLinkedWorkItemsStructsDirect().iterator();
    var systemrequirement = null;

    while (i.hasNext()) {
      var link = i.next();
      if (link.getLinkRole() && link.getLinkRole().getId() === "implements") {
        systemrequirement = link.getLinkedItem();
      }
    }

    // Apply parent color if set
    if (systemrequirement != null) {
      var pbColor = systemrequirement.getValue("pbColor");
      if (pbColor && pbColor.trim() !== "") {
        pbColor = pbColor.toLowerCase().trim();
        if (pbColor === "blue")   cli.cardColor = "#00c3ff";
        else if (pbColor === "red")    cli.cardColor = "#ff4d4d";
        else if (pbColor === "green")  cli.cardColor = "#00f57f";
        else if (pbColor === "yellow") cli.cardColor = "#ffd700";
      }
    }
    ```

    <Warning title="Replace the link role if needed">
      The script uses the `implements` link role to traverse to the parent. Replace `"implements"` with whichever link role your project uses to represent the parent-child relationship. Using the wrong role means no parent is found and no color is applied — with no error shown on the card.
    </Warning>

    <Tip title="Extend the color palette">
      You can add additional `else if` branches for any named colors, or skip the name-mapping entirely and write hex codes directly into the `pbColor` field (e.g. `#e3edff`). Apply the value directly: `cli.cardColor = pbColor;`
    </Tip>

    ***
  </Step>

  <Step title="Adjust card title height using the Config Script">
    If your work item titles are long, they may be clipped at the default card height. You can increase the title area by injecting a CSS rule through the **Config Script** (a separate field in the same Advanced Properties section).

    ```javascript theme={null}
    var style = document.createElement('style');
    style.innerHTML = ".eventitem .title { height: 87px; }";
    document.head.appendChild(style);
    ```

    <Warning title="Keep title height smaller than card height">
      Set the title height to a value slightly smaller than the overall card height you have configured. If the title height equals or exceeds the card height, content below the title will be hidden or overflow. Use your browser's **Inspect** tool (right-click a card → **Inspect**) to preview height values in real time before finalizing.
    </Warning>

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/FFzowwCxsFbWFK4y/planningboard/assets/images/article-customize-the-content-of-the-car-78d8c195.png?fit=max&auto=format&n=FFzowwCxsFbWFK4y&q=85&s=c00a1d001cbb7326afbed8f1634c5a40" alt="Browser DevTools Styles panel showing the injected .eventitem .title CSS rule with height: 87px overriding the default 37px value" width="1108" height="1184" data-path="planningboard/assets/images/article-customize-the-content-of-the-car-78d8c195.png" />
    </Frame>

    ***
  </Step>
</Steps>

## Available `cli` properties reference

The table below lists all `cli` properties available in the Item Script.

| Property         | Type    | Description                                                                                            |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `cli.fieldsLine` | String  | HTML displayed under the card title. Supports multi-line via `<br>`.                                   |
| `cli.cardColor`  | String  | Card background color. Accepts HEX (`#e3edff`) or CSS named colors.                                    |
| `cli.color`      | String  | Card frame (border) color.                                                                             |
| `cli.label`      | String  | Short text label displayed on the card.                                                                |
| `cli.tooltip`    | String  | Text shown on card hover. Supports HTML.                                                               |
| `cli.text`       | String  | General additional text content on the card.                                                           |
| `cli.effort`     | Float   | Numeric effort value; can be used in calculations or display.                                          |
| `cli.resolved`   | Boolean | Whether the item is resolved. Can drive visual cues.                                                   |
| `cli.readonly`   | Boolean | When `true`, prevents script-driven card modifications. Set to `false` to allow changes in the script. |

***

## Card content flow

```text theme={null}
  Polarion work item (wi / workitem)
           |
           v
  +---------------------------+
  |     Item Script           |
  |  reads fields via wi /    |
  |  workitem rendering API   |
  +---------------------------+
           |
           v
  cli object properties set
  (fieldsLine, cardColor, label…)
           |
           v
  +---------------------------+
  |   Card rendered on board  |
  |  title + fieldsLine HTML  |
  |  background = cardColor   |
  +---------------------------+
```

***

## Limitations

<Warning title="Card coloring is status-based by default">
  Out of the box, Planningboard colors cards by workflow status. Custom enumeration-based coloring (as available in Nextedy SCRUMBOARD) is not natively supported — it requires an Item Script like the ones above. If you need coloring based on an arbitrary custom enum field, you must implement the mapping manually in the script.
</Warning>

***

## Verification

Save the widget, exit Edit mode, and reload the board. You should now see:

* The fields you specified in `cli.fieldsLine` appearing under each card's title
* Any conditional background colors applied to matching cards
* Parent-color inheritance visible across child cards that have a populated `pbColor` field on the parent

If cards look unchanged, confirm the Item Script was saved (re-open Advanced Properties and check the field is not empty) and that any custom fields referenced in the script exist and are populated in Polarion.

***

## See also

* [Customize Card Appearance](/planningboard/guides/customization/card-appearance)
* [Customize Card Colors](/planningboard/guides/customization/card-colors)
* [Highlight Work Items by Rules](/planningboard/guides/customization/highlighting-rules)
* [Item Scripts](/planningboard/guides/advanced/item-scripts)
* [Config Scripts](/planningboard/guides/advanced/config-scripts)
* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters)

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

  * Customize the content of the card
  * Planningboard interface & basic interactions
  * Planningboard: Customizable Statistics and Capacity Indicators

  **Support Tickets**

  * [#6612](https://support.nextedy.com/helpdesk/tickets/6612)
  * [#6679](https://support.nextedy.com/helpdesk/tickets/6679)
  * [#6523](https://support.nextedy.com/helpdesk/tickets/6523)

  **Source Code**

  * `PlanningBoardWidget.java`
  * `licenseReadonly.cy.ts`
  * `viewLicense.vm`
  * `Config.java`
  * `PlanningBoardWidgetRenderer.java`
</Accordion>