Column Configuration Guide

Modified on Sun, 21 Sep at 12:33 PM

PowerSheets utilize YAML for their configuration, offering a flexible way to define how data is displayed and interacted with in a sheet tool. The columns array is where you define each column's behavior and appearance.

TABLE OF CONTENTS

Basic Structure
Common Column Properties
Using YAML Snippets/Anchors
Key Considerations

Basic Structure

Each column is an item in a list (array) under the columns section. A column is defined by a set of key-value pairs.


    columns:
     propertyName1:  # Essential: links to data
        title: "Column Title 1"   # Optional: Header text
        width: 150                # Optional: Column width
        # ... other column-specific properties ...

      navigation.propertyName2:
        title: "Linked Item Property"
        # ... other column-specific properties ...

Common Column Properties

Here's a breakdown of commonly used column properties:

Link to the data/binding (required)
- Description: Specifies the data field to which the column is bound. It uses a dot-separated path to navigate through related entities and their properties.
- Example:
  id: document.project: # Accesses 'project' property of 'document' riskControls.riskControl.title: # Nested navigation
title (string, optional)
- Description: The human-readable text displayed in the column header.
- Example:
  description: title: "Foreseeable Sequence of Events"
width (number | string, optional)
- Description: Sets the column width.
  - A number represents pixels (e.g., 120).
  - A string with * (e.g., '*', '2*') defines proportional width relative to other *-sized columns.
- Default: '*'
- Example:
  id: width: 80 title: width: "*" # Takes remaining available space proportionally
minWidth (number | string, optional)
- Description: Sets the minimum width for the column in pixels.
- Default: 150
- Example:
  validationTestCases.validationTestCase: minWidth: 200

display (string | JS function string, optional)

Description:
- When binding to a scalar navigation property (a linked item, n-1 relationship), display specifies which property of the linked item to show (e.g., title, id).
- Can also be a JavaScript arrow function string () => ... to return custom HTML for rendering the cell content. The function has access to a context object (context.value, context.item, context.polarionModel.polarionBaseUrl, etc.).

Example (property name):

hazard:
  title: Hazard
  display: title # Shows the 'title' property of the 'hazard' object

Example (JS function string):

riskControls.riskControl:
  title: Risk Control
  display: > # The '>' indicates a multi-line string in YAML
    () =>  `<img
    src='${context.polarionModel.polarionBaseUrl}/polarion/icons/default/enums/type_purple_feature.png'>
    <a
      target="_blank"
      href="${context.polarionModel.polarionBaseUrl}/polarion/nx_databridge/redirect/WorkItem/${context.item.projectId}/${context.item.id}">
      ${context.value.objectId}
    </a>`

Note the use of > for multi-line strings in YAML. The JavaScript is evaluated in the browser.

render (string | JS function string, optional)

Description: Similar to display when using a JS function string, but render is typically used when you want more control or if display is already used for property selection. It allows you to define custom HTML rendering for a cell using a JavaScript arrow function. Can also reference a predefined renderer name from settings.renderers.

Example

# In this specific example, a YAML alias is used
render: *displayItemAsIconIDTitleLink
# Which refers to a snippet like:
# snippets:
#   displayItemAsIconIDTitleLink: &displayItemAsIconIDTitleLink >
#     () =>
#        `<img src='${context.item.entityType.custom.iconPath}'><a
#         target="_blank"
#         href="/polarion/nx_databridge/redirect/WorkItem/${context.item.projectId}/${context.item.id}">${context.value}</a>`

Example


#   renderers:
#     myCustomRenderer: "() => `<strong>${context.value}</strong>`"
# columns:
#  status:
#     render: myCustomRenderer

list (object, optional)
- Description: Configures dropdown behavior for the column, typically for enums or linked items.
- Sub-properties:
  - search (array of strings): For linked items, specifies which properties of the linked item to search in when typing in the dropdown.
    Example: search: [title, id]
  - display (JS function string): For linked items, custom HTML for how each item appears in the dropdown list.
    Example:
    display: > () => `<img src='${context.polarionModel.polarionBaseUrl}/polarion/icons/default/enums/type_purple_feature.png'> ${context.value.objectId} ${context.value.title ? '– ' + context.value.title : ''}`
  - createNew (boolean): Whether to allow creating new linked items directly from the dropdown (default: false).
  - options (string): For enum types, references a query ID from sources that provides the enum values.
  - value (string): For enums, the property name from the options source to use as the actual value.
  - order (string): For enums, the property name from the options source to sort the list by.
- Example
  hazard: list: search: - title - id # display: ... (if custom dropdown item rendering is needed)

header (object, optional)

Description: Defines column header appearance.
Sub-properties:
- style (string): References a style name defined in styles to apply to the header (e.g., background color, text color).

Example:


#     styles:
#       lightpurple: { backgroundColor: "lightpurple", color: "white" } # Simplified
#     columns:
         hazard:
           header:
             style: lightpurple

formatter (string | array of strings, optional)

Description: Applies conditional formatting. References one or more formatter names defined in tool.settings.formatters.

Example:


#     formatters:
#       boldTitle:
#         - expression: 'true' # Always apply
#           style: boldTitleStyle
#     styles:
#       boldTitleStyle: { fontWeight: "bold" }
#     columns:
        title:
          formatter: boldTitle

isReadOnly (boolean | JS function string, optional)
- Description: If true, the column cells cannot be edited. Can also be a JS function string () => boolean_expression for dynamic read-only status based on item data.
- Default: false
- Example:
  outlineNumber: isReadOnly: true
visible (boolean, optional)
- Description: If false, the column is hidden by default. Can be overridden by Views.
- Default: true
- Example:
  chapter.title: visible: false # Hidden by default, might be shown by a view or groupBy
groupBy (boolean | object, optional)
- Description: If true, rows in the sheet will be grouped by the unique values in this column.
  Can be an object: { hideCounter: boolean } to control visibility of the item counter per group.
- Example:
  chapter.title: groupBy: true
multiItem (boolean, optional)
- Description: If true, allows selecting multiple items for a cell (e.g., for a to-many relationship without creating a new level/sub-grid). The cell editor becomes a multi-select dropdown.
- Default: false
- Example
  useSteps.useStep: title: "Use Step" multiItem: true

type (string, optional)

Description: Manually sets a custom column type. Most relevant for "enum" when not inferred.

Example

status:
   type: enum
   list:
     options: "statusEnumSource" # Reference to a source providing enum values
     value: "statusCode"
     display: "statusLabel"

format (string, optional)
- Description: Specifies number/date formatting (e.g., c0$ for currency, d for short date). Refers to Wijmo formatting strings.
- Example:
  price: format: "c2" # Currency with 2 decimal places
formula (string, optional)
- Description: A JavaScript arrow function string () => ... that calculates the cell's value based on other properties of the current item (context.item). This calculated value affects the data.
- Example:
  Generated yaml
  totalRisk: formula: "() => context.item.probability * context.item.severity"

Using YAML Snippets/Anchors

The following examples effectively use YAML anchors (&) and aliases (*) to define reusable snippets, especially for display and list.display functions. This is excellent for keeping the configuration DRY (Don't Repeat Yourself).

      snippets:
  displayAsIconIDLink: &displayAsIconIDLink | # Anchor defined with '|' for literal block
    () =>
    `<a
      target="_blank"
      href="${context.polarionModel.polarionBaseUrl}/polarion/nx_databridge/redirect/WorkItem/${context.value.projectId}/${context.value.id}"
      style="white-space:wrap; "
      >
      <img src='${context.value.entityType.custom.iconPath}'>
      <span>${context.value.objectId}</span>
     </a>`

# ... later in columns:
columns:
  systemRequirements.systemRequirement:
    title: Design Input ID
    display: *displayAsIconIDLink # Alias used
    width: 100
    # ...

Key Considerations

YAML Syntax: Pay close attention to indentation (typically 2 spaces) as it defines the structure. Hyphens (-) denote list items.
JS Function Strings: For display, render, formula, and list.display, JavaScript arrow functions are provided as strings.
- Use single quotes for the outer JS string if your HTML attributes use double quotes, and vice-versa, or escape quotes.
- The > or | YAML block scalars are useful for multi-line strings. > folds newlines into spaces (unless there's a blank line), while | preserves newlines.
Context Object: Inside JS function strings, you have access to context:
- context.value: The current cell's raw value.
- context.item: The entire data item for the current row.
- context.polarionModel.polarionBaseUrl: Useful for constructing links to Polarion (if applicable).
- Other context properties might be available depending on the specific PowerSheet version and configuration.
Paths in binding: Ensure these paths accurately reflect your data model.
Referencing Styles/Formatters/Renderers: When using header.style, formatter, or named renderers, make sure these are defined in the corresponding styles, formatters, or renderers sections.

This guide should provide a solid foundation for configuring columns in PowerSheet YAML files.