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

# Rich Text Fields

> Nextedy RISKSHEET provides limited support for Polarion rich text fields. Rich text content (HTML formatting, embedded images, clickable links) can be displayed read-only using server render columns.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/yWl5nA2D0IzEnZC1/risksheet/diagrams/reference/columns/rich-text-fields/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=f55988b4f3deafdc814de02ec3592b38" alt="diagram" style={{ maxWidth: "520px", width: "100%" }} width="520" height="300" data-path="risksheet/diagrams/reference/columns/rich-text-fields/diagram-1.svg" />
</Frame>

## Display Modes

Rich text fields can be displayed in two modes within the Risksheet grid. The choice depends on whether you need to preserve formatting or enable editing.

### Standard Text Display

When a rich text field is bound to a standard column (without the `serverRender` property), the content is converted to plain text by the type conversion system:

| Behavior            | Description                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Formatting stripped | All HTML tags are removed. Bold, italic, colors, lists, and tables are lost.                                                             |
| Links processed     | Links embedded in the content are automatically processed for rendering, though they appear as plain text.                               |
| Text type           | The column uses the `text` type, which supports multi-line plain text editing.                                                           |
| Editable            | Plain text can be edited and saved back to Polarion. However, the original HTML formatting is permanently lost once saved from the grid. |

Configuration example:

```yaml theme={null}
{
  "id": "description",
  "header": "Description",
  "bindings": "description",
  "type": "text",
  "width": 300,
  "level": 1
}
```

<Warning title="Editing Rich Text Removes Formatting">
  Risksheet does not fully support editing rich text fields. Editing a rich text field through the grid may strip line breaks and HTML formatting from the work item XML, causing all text to appear concatenated. Use column type `text` (multi-line plain text) as the recommended alternative when editing capability is needed. For preserving formatting, use `serverRender` instead (read-only).
</Warning>

### Server Render Display

Use the `serverRender` property to display rich text with full HTML formatting. Server render columns execute a Velocity expression on the server to produce the HTML output:

```yaml theme={null}
id: description
header: Description
serverRender: $item.fields().get('description').render().htmlFor().forFrame()
width: 300
level: 1
```

| Behavior            | Description                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Full HTML rendering | Colors, bold, italic, underline, lists, tables, and other HTML formatting are preserved and rendered in the grid cell. |
| Clickable links     | Hyperlinks within the rich text remain functional and can be clicked to navigate.                                      |
| Embedded images     | Images stored in rich text fields (diagrams, symbols, annotations) are displayed inline in the cell.                   |
| Read-only           | Server render columns are always read-only. Content cannot be edited through the grid.                                 |

<Warning title="Server Render Columns Are Always Read-Only">
  The `serverRender` property produces a read-only display. There is no way to edit rich text formatting from within the Risksheet grid. Users must edit rich text content in Polarion's native work item editor, then refresh the Risksheet to see the updated content.
</Warning>

## Velocity Snippets for Rich Text

The `serverRender` property accepts Velocity expressions that are evaluated server-side. The following snippets are the standard patterns for rendering rich text fields.

### Basic Rich Text Field Rendering

Use `$item.fields().get('fieldID')` with the `.render().htmlFor().forFrame()` chain:

```
$item.fields().get('description').render().htmlFor().forFrame()
```

Replace `description` with the actual Polarion field ID of your rich text field.

### Common Field Aliases

Some standard Polarion fields have shortcut methods:

```
$item.fields().description().render().htmlFor().forFrame()
```

### Custom Rich Text Fields

For custom rich text fields defined on your work item type:

```
$item.fields().get('customRichTextField').render().htmlFor().forFrame()
```

<Tip title="Finding Field IDs">
  The field ID used in `$item.fields().get('...')` must match the Polarion custom field ID exactly. Check your project's custom field definitions in the Polarion administration panel, or see [Field Mapping](/risksheet/reference/fields/field-mapping) for details on how Polarion fields map to Risksheet columns.
</Tip>

### Rich Text with Images

For fields containing embedded images (such as symbol libraries, annotated diagrams, or visual risk descriptions):

```yaml theme={null}
id: symbols
header: Symbols
serverRender: $item.fields().get('testRichTextFieldID').render().htmlFor().forFrame()
width: 200
level: 1
```

<Tip title="Image Rendering in Grid Cells">
  Rich text fields with images are a commonly requested feature. The `serverRender` approach is the recommended method for displaying images in the grid. The images render at their original size within the cell, which may cause layout issues if images are large. See the section on controlling image display below for CSS-based sizing.
</Tip>

## Column Properties for Rich Text

### Standard Text Column Properties

| Name          | Type      | Default         | Description                                                                              |
| ------------- | --------- | --------------- | ---------------------------------------------------------------------------------------- |
| `id`          | `string`  | Auto-generated  | Unique column identifier                                                                 |
| `header`      | `string`  | Required        | Display text in column header                                                            |
| `bindings`    | `string`  | Same as `id`    | Polarion field binding for the rich text field                                           |
| `type`        | `string`  | `text`          | Set to `text` for multi-line editing. Auto-detected from Polarion field type if omitted. |
| `width`       | `number`  | See application | Column width in pixels                                                                   |
| `level`       | `number`  | `1`             | Hierarchical level                                                                       |
| `readOnly`    | `boolean` | `false`         | Set to `true` to prevent editing (recommended for rich text fields)                      |
| `headerGroup` | `string`  | None            | Header group for multi-level column grouping                                             |

### Server Render Column Properties

| Name           | Type     | Default         | Description                                                                          |
| -------------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
| `id`           | `string` | Auto-generated  | Unique column identifier                                                             |
| `header`       | `string` | Required        | Display text in column header                                                        |
| `serverRender` | `string` | None            | Velocity expression to execute server-side. The result HTML is rendered in the cell. |
| `width`        | `number` | See application | Column width in pixels                                                               |
| `level`        | `number` | `1`             | Hierarchical level                                                                   |
| `headerGroup`  | `string` | None            | Header group for multi-level column grouping                                         |

<Note title="No `bindings` Needed for Server Render">
  When using `serverRender`, the `bindings` property is not required for the display itself -- the Velocity expression retrieves the data directly. However, if the column needs to participate in sorting or filtering, a `bindings` may still be useful.
</Note>

## Controlling Image Display

Images rendered through `serverRender` may appear at their original dimensions, which can disrupt the grid layout. Control image sizing using CSS in the top panel template or via custom styles:

| Approach                  | Description                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| CSS in Top Panel          | Add CSS rules targeting `img` elements within server-rendered cells to limit `max-width` and `max-height` |
| Cell height configuration | Adjust row heights in the `headers` configuration to accommodate image dimensions                         |
| Custom renderer           | Use a custom Velocity renderer that wraps images in a sized container                                     |

See the [Top Panel Template](/risksheet/reference/templates/top-panel-template) reference for details on injecting custom CSS.

## Autocomplete Behavior

Text columns (non-server-render) support autocomplete suggestions when editing:

| Property                            | Default | Description                                                      |
| ----------------------------------- | ------- | ---------------------------------------------------------------- |
| `settings.global.suggestTextFields` | `true`  | Enables autocomplete for text fields based on existing values    |
| `queryFactory`                      | None    | Custom JavaScript function to customize autocomplete suggestions |

When `suggestTextFields` is enabled, the text editor shows suggestions based on existing values in the same column across all rows. This is useful for maintaining consistency in plain text descriptions but does not apply to server-rendered columns.

## Export Behavior

### Excel Export

Rich text columns export differently based on their configuration:

| Configuration        | Export Behavior                                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Standard text column | Plain text (HTML already stripped during display). Editable values export as-is.                                                      |
| Server render column | HTML is stripped to plain text. Line breaks from `<li>` elements are preserved by inserting newlines before each closing `</li>` tag. |

### PDF Export

| Configuration        | Export Behavior                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Standard text column | Plain text value included in PDF cell                                                                             |
| Server render column | HTML is stripped to produce plain text content. The `emptyPlaceholder` property controls display for empty cells. |

<Info title="Verify in application">
  The exact rendering of rich text in PDF exports depends on your custom PDF export script configuration. Complex HTML content (tables within tables, deeply nested lists) may not render as expected in the plain text conversion.
</Info>

## Known Limitations

| Limitation                   | Description                                                              | Workaround                                                                           |
| ---------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| No rich text editing in grid | Editing rich text through standard columns strips all HTML formatting    | Use `serverRender` for display; edit in Polarion's work item editor                  |
| Line breaks lost on edit     | Editing rich text fields may strip line breaks from the work item XML    | Use `type: "text"` (multi-line text) instead of binding directly to rich text fields |
| Server render is read-only   | No way to edit server-rendered content from the grid                     | Edit in Polarion, then refresh Risksheet                                             |
| Image sizing                 | Images render at original size in cells                                  | Apply CSS rules in the top panel template to constrain dimensions                    |
| Custom Excel templates       | Custom Excel export templates for rich text formatting are not available | Use PDF export with custom scripts for formatted output                              |

## Complete Example

An FMEA configuration with a mix of editable plain text and read-only rich text columns:

```yaml theme={null}
{
  "columns": [
    {
      "id": "title",
      "header": "Failure Mode",
      "bindings": "title",
      "type": "text",
      "width": 200,
      "level": 1
    },
    {
      "id": "descriptionFormatted",
      "header": "Description (Formatted)",
      "serverRender": "$item.fields().get('description').render().htmlFor().forFrame()",
      "width": 350,
      "level": 1,
      "headerGroup": "Details"
    },
    {
      "id": "descriptionPlain",
      "header": "Description (Editable)",
      "bindings": "description",
      "type": "text",
      "width": 250,
      "level": 1,
      "readOnly": false,
      "headerGroup": "Details"
    },
    {
      "id": "sev",
      "header": "Severity",
      "bindings": "sev",
      "type": "rating:severity",
      "width": 70,
      "level": 1,
      "headerGroup": "Assessment"
    },
    {
      "id": "taskNotes",
      "header": "Mitigation Notes",
      "serverRender": "$item.fields().get('notes').render().htmlFor().forFrame()",
      "width": 300,
      "headerGroup": "Mitigation"
    },
    {
      "id": "taskDescription",
      "header": "Task Details (Editable)",
      "bindings": "task.description",
      "type": "text",
      "width": 250,
      "headerGroup": "Mitigation"
    }
  ]
}
```

This configuration provides:

* A formatted, read-only view of the description field with full HTML rendering
* A parallel editable plain text version for quick edits (loses formatting)
* Server-rendered mitigation notes with preserved formatting
* An editable task description for downstream items

## Related Pages

* [Server Render Columns](/risksheet/reference/columns/server-render-columns) -- full reference for server-rendered columns and Velocity expressions
* [Velocity Template Context](/risksheet/reference/api/velocity-context) -- available Velocity context variables and methods
* [Column Type Reference](/risksheet/reference/columns/column-types) -- overview of all available column types
* [Data Types](/risksheet/reference/columns/data-types) -- field type reference and type conversion behavior
* [Supported Field Types](/risksheet/reference/fields/supported-field-types) -- complete list of Polarion field types
* [Field Mapping](/risksheet/reference/fields/field-mapping) -- how Polarion fields map to Risksheet columns
* [Top Panel Template](/risksheet/reference/templates/top-panel-template) -- inject custom CSS for image sizing

<LastReviewed date="2026-06-24" />