Skip to content

sc-card-table

This document is a user guide for the sc-card-table component.

Written: JGalland 2025-09-04 Updated: CIradukunda 2025-09-08

1. Purpose

The sc-card-table component provides a configurable, Kanban-style tabular display for documents. It allows users to visualize data as "cards" in columns and rows and use drag-and-drop functionality to change their position, which in turn can update values on the underlying documents.

The component is highly customizable and allows for dynamic grouping, sorting, and ranking of documents loaded via a filter query.

sc-card-table-01

2. Definition

sc-card-table is defined by a set of name/value pair fields consisting of:

  • Required system fields
  • Required customizable fields
  • Optional customizable fields

Note:

  1. Default values for fields described in the tables below are shown in bold text.

2.1. Required System Fields

Field Valid Values Description
componentName sc-card-table The component name.

Example:
"componentName": "sc-card-table"

2.2. Required Customisable Fields

Field Valid Values Description
name Any value written in camel case Defines the name of the sc-card-table field in the document and database.

Example: "name": "testScCardTable"
filter A valid Formbird Handlebars query The data source query used to load documents into the component as cards.

Example: "filter": "{'query':{'bool':{'filter':[{'term':{'appTags':'waterPipe'}},{'term':{'systemHeader.systemType':'document'}}]}}}"

2.3. Optional Customisable Fields

Field Valid Values Description
disableSave true No changes made by moving cards are saved to either the main document or the card documents. The main document's save icon will not be triggered.
false Default Value. Changes are saved normally (auto-saved if autoSave is true; otherwise saved when the form is saved).
cardTableSave true Saves a representation of the card table's structure (columns, groups, and card references) into the current document under the component's name.
false Default Value. No representation of the card table is saved in the current document.
cardDisplay A Formbird Handlebars string Overrides the default card display (which uses the systemHeader.summaryName field). Provides full access to the query data for a custom display.
cardTemplate A valid templateId string A Formbird Handlebars field that returns a templateId to render a more complex, multi-line view for each card, overriding summaryName and cardDisplay.
columnField String Defines the document field used to group cards into columns. A column is created for each unique value found in this field, sorted alphabetically.
delayedDragging Number (milliseconds) The time in milliseconds a user must hold a card before it can be dragged. A visual indicator appears when the card is ready to move.

Defaults to 0 (no delay).
fullWidth true The component display spans the full width of the form. Horizontal scrolling is enabled if the content exceeds the viewport.
false Default value. The component adheres to standard column widths.
gridColumns An array of column definition objects An array of column definitions, each defining the properties of a card table column. Each column is defined by a set of name/value pair fields, some being required, some being optional.

Section 2.3.1 gridColumns Field lists and describes the name/value pair fields for defining the properties of a card table column.
gridGrouping An array of group definition objects An array of group definitions, each defining the properties of a card table group. Each group is defined by a set of name/value pair fields, some being required, some being optional.

Section 2.3.2 gridGrouping Field lists and describes the name/value pair fields for defining the properties of a card table group.
groupingField String A secondary field used to group documents into distinct horizontal rows within the table.
height Number (pixels) Sets a fixed height for the component. A vertical scrollbar will appear if the content exceeds this height.

Defaults to dynamic height based on content.
label Any value Defines the field label displayed on the form.

Defaults to no label.
minCardWidth Number (pixels) Sets the minimum width for each card, allowing for responsive adjustments to the available display space.

Defaults to 100.
rankingField String A document field used to enable ranking functionality in columns. When set, cards can be ranked from 1 to n, with rank 1 appearing at the top of the column, rank 2 below it, and so on. Unranked cards (no value or value of 0) appear at the bottom in their normal sort order. The ranking number is displayed in the card footer for visual confirmation. You can click on the ranking number to set or clear it, and cards will automatically reposition. When you drag and drop a card, the ranking system automatically adjusts - cards above the drop position get ranked, and existing rankings below are updated accordingly.
visible false The sc-card-table component is not visible on the form.
true Default Value. The component is visible.

2.3.1. gridColumns Field

The gridColumns field is an array of column definition objects. Each column definition object is defined by a set of name/value pair fields consisting of:

  • Required customizable fields
  • Optional customizable fields

Note:

  1. Default values for fields described in the tables below are shown in bold text.

Required Customisable Fields

Field Valid Values Description
displayName Any value The name displayed as the column header.

Example: "displayName": "CI"
expression A valid Formbird Handlebars expression A Formbird Handlebars expression that evaluates to true or false to determine which documents belong in this column.

Example: "expression": "{{doc.pipe_matrl}}' == 'CI'"

Optional Customisable Fields

Field Valid Values Description
valueOnDrop Any value The value written to the document field when a card is dropped into this column.

Example: "valueOnDrop": "CI"
sort A sort definition object Defines sorting behavior for cards within this column. See Section 2.3.1.1 Sort Definition for details.
dragRestrictions A drag restrictions object Defines which columns can drop cards into this column. See Section 2.3.1.2 Drag Restrictions Definition for details.

2.3.1.1. Sort Definition

Field Valid Values Description
type "numeric", "date", "string" The data type for sorting.

Defaults to "string".
direction "Ascending", "Descending" The sort direction.

Defaults to "Ascending".
enforced true Sorting is automatically applied when cards are moved.
false Default Value. Sorting is not automatically enforced.
expression A valid Formbird Handlebars expression The field or expression to sort by.

Defaults to "{{doc.pipe_dia}}".
collapsible true The column can be collapsed to hide its cards.
false Default Value. The column cannot be collapsed.

2.3.1.2. Drag Restrictions Definition

Field Valid Values Description
allowed Array of column indices Array of column indices (0-based) that can drop cards into this column. If specified, only cards from these columns can be dropped here.
notAllowed Array of column indices Array of column indices (0-based) that cannot drop cards into this column. If specified, cards from these columns cannot be dropped here.

2.3.2. gridGrouping Field

The gridGrouping field is an array of group definition objects. Each group definition object is defined by a set of name/value pair fields consisting of:

  • Required customizable fields
  • Optional customizable fields

Note:

  1. Default values for fields described in the tables below are shown in bold text.

Required Customisable Fields

Field Valid Values Description
displayName Any value The name displayed as the group header.

Example: "displayName": "CICL"
expression A valid Formbird Handlebars expression A Formbird Handlebars expression that evaluates to true or false to determine which documents belong in this group.

Example: "expression": "'{{doc.pipe_matrl}}' == 'CICL'"

Optional Customisable Fields

Field Valid Values Description
valueOnDrop Any value The value written to the document field when a card is dropped into this group.

Example: "valueOnDrop": "CICL"
sort A sort definition object Defines sorting behavior for cards within this group. See Section 2.3.1.1 Sort Definition for details.
dragRestrictions A drag restrictions object Defines which groups can drop cards into this group. See Section 2.3.1.2 Drag Restrictions Definition for details.

3. Typical Definition

Below is a typical sc-card-table definition, configured with the required fields plus essential optional fields for basic functionality.

{
    "componentName": "sc-card-table",       
    "filter": "{'query':{'bool':{'filter':[{'term':{'appTags':'waterPipe'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
    "label": "Water Pipes Basic",
    "name": "waterPipeBasic",
    "fullWidth": true
},

This configuration will load all documents with the 'waterPipe' app tag, create a single column, and display them as cards using the default systemHeader.summaryName field.

4. Examples

Example 1: Basic setup with a Custom Card Display

This example uses cardTemplate to create a custom, multi-line display for each card, showing the asset number, diameter, material, and water category with appropriate icons.

{
    "componentName": "sc-card-table",
    "filter": "{'query':{'bool':{'filter':[{'term':{'appTags':'waterPipe'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
    "label": "Water Pipes cardTemplate",
    "name": "waterPipescardTemplate",
    "fullWidth": true,
    "cardTemplate": "<div style='font-weight:bold; font-size:1.4em; color:#2c3e50; margin-bottom:8px;'>{{doc.assetNumber}}</div><div style='margin-bottom:4px;'><span style='font-weight:500; color:#34495e;'>Diameter: </span><span style='font-weight:normal; color:#2c3e50;'>{{doc.pipe_dia}}</span></div><div style='display:flex; align-items:center; justify-content:space-between;'><span style='font-weight:500; color:#e74c3c;'>{{doc.pipe_matrl}}</span><i class='material-icons' style='font-size:1.2em; color:#3498db;'>{{#switch doc.wat_category}}{{#case 'POTABLE'}}hot_tub{{/case}}{{#default}}play_circle{{/default}}{{/switch}}</i></div>"
}

sc-card-table-03

Example 2: Advanced Columns with gridColumns

This example uses gridColumns to define a specific set of columns in a fixed order. When a card is dropped into a column, the valueOnDrop is written to the pipe_matrl field of that card's document.

{
    "componentName": "sc-card-table",
    "name": "waterPipesGridColumns",
    "label": "Water Pipes (Grid Columns)",
    "filter": "{'query':{'bool':{'filter':[{'term':{'appTags':'waterPipe'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
    "fullWidth": true,
    "columnField": "pipe_matrl",
    "gridColumns": [
        {
            "displayName": "Cast Iron (CI)",
            "expression": "'{{doc.pipe_matrl}}' == 'CI'",
            "valueOnDrop": "CI"
        },
        {
            "displayName": "Cement Lined (CICL)",
            "expression": "'{{doc.pipe_matrl}}' == 'CICL'",
            "valueOnDrop": "CICL"
        },
        {
            "displayName": "Ductile Lined (DICL)",
            "expression": "'{{doc.pipe_matrl}}' == 'DICL'",
            "valueOnDrop": "DICL"
        }
    ]
}

sc-card-table-02

Example 3: Adding Sorting and Collapsible Columns

This builds on the previous example by adding sorting and the ability to collapse columns. Cards in each column will be sorted in ascending order based on their pipe_dia (pipe diameter).

{
    "componentName": "sc-card-table",
    "name": "sortedWaterPipes",
    "label": "Water Pipes (Sorted & Collapsible)",
    "filter": "{'query':{'bool':{'filter':[{'term':{'appTags':'waterPipe'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
    "fullWidth": true,
    "columnField": "pipe_matrl",
    "gridColumns": [
        {
            "displayName": "Cast Iron (CI)",
            "expression": "'{{doc.pipe_matrl}}' == 'CI'",
            "valueOnDrop": "CI",
            "sort": {
                "type": "numeric",
                "direction": "Ascending",
                "enforced": true,
                "expression": "{{doc.pipe_dia}}",
                "collapsible": true
            }
        },
        {
            "displayName": "Ductile Lined (DICL)",
            "expression": "'{{doc.pipe_matrl}}' == 'DICL'",
            "valueOnDrop": "DICL",
            "sort": {
                "type": "numeric",
                "direction": "Ascending",
                "enforced": true,
                "expression": "{{doc.pipe_dia}}",
                "collapsible": true
            }
        }
    ]
}

Example 4: Implementing Drag Restrictions

This example prevents cards from the "CICL" column (index 1) from being dropped into the "DICL" column (index 2), while explicitly allowing cards from the "CI" column (index 0) to be dropped into the "DICL" column.

{
    "componentName": "sc-card-table",
    "name": "restrictedDragPipes",
    "label": "Water Pipes (Drag Restrictions)",
    "filter": "{'query':{'bool':{'filter':[{'term':{'appTags':'waterPipe'}},{'term':{'systemHeader.systemType':'document'}}]}}}",
    "fullWidth": true,
    "columnField": "pipe_matrl",
    "gridColumns": [
        {
            "displayName": "CI",
            "expression": "'{{doc.pipe_matrl}}' == 'CI'",
            "valueOnDrop": "CI"
        },
        {
            "displayName": "CICL",
            "expression": "'{{doc.pipe_matrl}}' == 'CICL'",
            "valueOnDrop": "CICL"
        },
        {
            "displayName": "DICL",
            "expression": "'{{doc.pipe_matrl}}' == 'DICL'",
            "valueOnDrop": "DICL",
            "dragRestrictions": {
                "allowed": [0],
                "notAllowed": [1]
            }
        }
    ]
}

5. Additional Information

The sc-card-table component leverages the Angular Component Development Kit (CDK) for its drag-and-drop capabilities.

More information:

For more information on the underlying drag-and-drop technology, see the Angular Material Drag & Drop documentation.