Column Configuration Guide

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 within tool.settings is where you define each column's behavior and appearance.

Basic Structure

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

Generated yaml

tool:
  type: sheet
  settings:
    # ... other settings like formatters, styles, views ...

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

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

Common Column Properties

Here's a breakdown of commonly used column properties, based on the Confluence documentation and your examples:

1. binding (string, 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:

     - binding: id
     - binding: document.project # Accesses 'project' property of 'document'
     - binding: riskControls.riskControl.title # Nested navigation
         

2. title (string, optional)

   • Description: The human-readable text displayed in the column header.

   • Example:

     - binding: description
       title: "Foreseeable Sequence of Events"
         

3. 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:

     - binding: id
       width: 80
     - binding: title
       width: "*" # Takes remaining available space proportionally
         

4. minWidth (number | string, optional)

   • Description: Sets the minimum width for the column in pixels.

   • Default: 150 (as per Confluence, though practical default might vary)

   • Example:

     - binding: validationTestCases.validationTestCase
       minWidth: 200
         

5. 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):

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

   • Example (JS function string):

     - binding: 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.

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

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

7. 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 (from powersheet (6).yaml.txt):

       Generated yaml

       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 

      - binding: hazard
       list:
         search:
           - title
           - id
         # display: ... (if custom dropdown item rendering is needed)
         

8. header (object, optional)

   • Description: Defines column header appearance.

   • Sub-properties:

     • style (string): References a style name defined in tool.settings.styles to apply to the header (e.g., background color, text color).

   • Example:

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

9. formatter (string | array of strings, optional)

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

   • Example:

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

10. 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:

      - binding: outlineNumber
        isReadOnly: true
          

11. visible (boolean, optional)

    • Description: If false, the column is hidden by default. Can be overridden by Views.

    • Default: true

    • Example:

      - binding: chapter.title
        visible: false # Hidden by default, might be shown by a view or groupBy
          

12. 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:

      - binding: chapter.title
        groupBy: true
          

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

      - binding: useSteps.useStep
        title: "Use Step"
        multiItem: true
          

14. type (string, optional)

    • Description: Manually sets a custom column type. Most relevant for "enum" when not inferred.
      The Confluence doc mentions "ref" was removed in favor of automatic configuration.

    • Example 

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

15. format (string, optional)

    • Description: Specifies number/date formatting (e.g., c0$ for currency, d for short date). Refers to Wijmo formatting strings.

    • Example:

       - binding: price
         format: "c2" # Currency with 2 decimal places
          

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

       - binding: totalRisk
         formula: "() => context.item.probability * context.item.severity"
          

Using YAML Snippets/Anchors

Your 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).

Generated yaml

      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:
  - binding: 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 tool.settings.styles, tool.settings.formatters, or tool.settings.rendererssections.

This guide should provide a solid foundation for configuring columns in your PowerSheet YAML files. Refer to the specific Confluence documentation for the most up-to-date and exhaustive list of properties.