Prerequisites
Before configuring a formatter, ensure you have:
- A working sheet configuration with at least one column defined
- Access to edit the YAML configuration (see Download Configuration as YAML)
- Familiarity with the properties available on your entity types
Formatters live in the formatters section at the root level of your sheet configuration. Each formatter is a named key containing an array of rules. Each rule pairs an expression (a condition) with a style (the visual treatment to apply when the condition is true).
Step 1. Open your sheet configuration YAML and add a formatters section:
formatters:
boldTitle:
- expression: 'true'
style: boldTitleStyle
styles section:
styles:
boldTitleStyle:
fontWeight: "bold"
expression property accepts a JavaScript expression string. When it evaluates to true, the referenced style is applied to the cell. Using the literal 'true' means the style applies unconditionally to every cell in that column.
Reference the formatter by name in the column’s formatter property:
columns:
title:
title: Title
width: 200
formatter: boldTitle
formatter value must match a key defined in the formatters section exactly. If the name does not match any defined formatter, no styling is applied and no error is raised.
If you reference a formatter name that does not exist in the formatters section, Powersheet will not display an error. The column simply renders without conditional styling. Double-check that the formatter value on your column exactly matches a key under formatters.
formatter assigned. If so, it evaluates each rule’s expression in the order they appear. The first matching rule determines the style applied.
Use the Expression Context
Inside a formatter expression, you have access to a context object that provides data about the current cell:
| Context Property | Description |
|---|
context.item | The current entity (work item) for the row |
context.value | The value of the current cell |
context.document | The document data object |
context.item.Probability reads the Probability field of the current row’s entity.
formatters:
highProbability:
- expression: "context.item.Probability > 80"
style: criticalStyle
Use Multiple Rules
A formatter can contain multiple expression-style pairs. Rules are evaluated top-to-bottom, and the first matching rule determines the applied style. Place the most specific conditions first and use a catch-all 'true' rule last for a default style:
formatters:
severityHighlight:
- expression: "context.value === 'Critical'"
style: criticalStyle
- expression: "context.value === 'Major'"
style: majorStyle
- expression: 'true'
style: defaultStyle
styles:
criticalStyle:
backgroundColor: 'red100'
color: 'red700'
majorStyle:
backgroundColor: 'orange100'
color: 'orange700'
defaultStyle:
backgroundColor: 'grey100'
End your formatter with expression: 'true' to ensure every cell receives a baseline style, even when no specific condition matches. This prevents visual inconsistency between styled and unstyled cells.
isReadOnly column property to both visually indicate and enforce that a column cannot be edited:
formatters:
readonly:
- expression: 'true'
style: readOnlyStyle
styles:
readOnlyStyle:
backgroundColor: 'grey100'
columns:
outlineNumber:
title: "#"
width: 80
formatter: readonly
isReadOnly: true
isReadOnly: true property prevents editing at the column level, while the formatter applies a grey background to visually communicate the read-only state. Note that isReadOnly can also be overridden by document-level permissions or user access control settings.
Begin with a single formatter rule and verify it works before adding conditional expressions. Jumping straight to complex multi-rule formatters leads to hard-to-diagnose styling issues.
Define Custom Styles
Styles use CSS-like property names in camelCase. Common properties include:
| Property | Example Value | Effect |
|---|
backgroundColor | 'red100', '#ffcdd2' | Cell background color |
color | 'red700', '#d32f2f' | Text color |
fontWeight | "bold" | Bold text |
textDecoration | "line-through" | Strikethrough text |
red100, red700, grey100, orange100, blue100, green100, purple100, teal100, and their dark/light variants) that you can use alongside standard CSS color values.
Every style value in a formatter rule must match either a key you defined in the styles section or one of the built-in style names (none, boldTitle, readOnly, grey, red, green, blue, purple, teal, orange, and their dark/light variants). A typo in the style name causes the rule to silently produce no visual effect.
Complete YAML Example
This example shows a full configuration with two formatters applied to columns in a requirements traceability sheet:
formatters:
readonly:
- expression: 'true'
style: readOnlyStyle
priorityFormat:
- expression: "context.value === 'Critical'"
style: criticalStyle
- expression: "context.value === 'High'"
style: highStyle
- expression: 'true'
style: normalStyle
styles:
readOnlyStyle:
backgroundColor: 'grey100'
criticalStyle:
backgroundColor: 'red100'
color: 'red700'
fontWeight: "bold"
highStyle:
backgroundColor: 'orange100'
color: 'orange700'
normalStyle:
backgroundColor: 'green100'
columns:
outlineNumber:
title: "#"
width: 80
formatter: readonly
isReadOnly: true
title:
title: Title
width: 300
hasFocus: true
severity:
title: Severity
width: 120
formatter: priorityFormat
systemRequirements.systemRequirement.title:
title: System Requirement
width: 250
columnGroup: reqs
Useful Keyboard Shortcuts
When working with formatted columns in the sheet, these shortcuts help navigate and organize your data:
| Shortcut | Action |
|---|
| Ctrl+G (Cmd+G on Mac) | Group rows by selected column |
| Ctrl+Shift+G | Clear all row grouping |
| Ctrl+F | Freeze columns up to selection |
| Ctrl+Shift+F | Unfreeze all columns |
Use Expression Variables
The expression string is evaluated as JavaScript. The variable value represents the current cell value, enabling numeric comparisons and pattern matching:
formatters:
numberRange:
- expression: "value > 100"
style: red
- expression: "value > 50"
style: orange
- expression: 'true'
style: green
End your formatter rules with expression: 'true' as a catch-all. Without a fallback, cells that match no rule receive no formatting.
Predefined Styles
Powersheet includes 20 built-in styles you can reference directly without defining them in the styles section:
| Style Name | Description |
|---|
none | No styling |
boldTitle | Bold font weight |
readOnly | Read-only visual indicator |
unsupported | Strikethrough text |
grey / darkgrey | Grey background variants |
red / darkred | Red background variants |
orange / darkorange | Orange background variants |
green / darkgreen / lightgreen | Green background variants |
blue / darkblue / lightblue | Blue background variants |
teal / darkteal | Teal background variants |
purple / darkpurple / lightpurple | Purple background variants |
formatters:
statusColor:
- expression: "value === 'Approved'"
style: green
- expression: "value === 'Rejected'"
style: red
- expression: 'true'
style: grey
If you define a style in the styles section with the same name as a predefined style, your custom definition takes priority. The 20 predefined styles serve as defaults that are merged with your custom styles.
Verification
After saving your configuration changes:
- Reload the sheet in Polarion
- You should now see cells in the formatted columns displaying the conditional styles you defined
- Verify that cells matching your expression conditions show the correct background color and text styling
- For read-only formatters, confirm that clicking the cell does not enter edit mode and the grey background is visible
If no styling appears, check that the formatter value on the column matches a key in the formatters section, and that each style value within the formatter matches a key in the styles section.
See Also
