Kanban Board Component - Part 2 - Configuration reference

MGOPW · ‎09-27-2024

Kanban Board Component - Part 2

Article Directory

Introduction

This series of articles will walk you through an example configuration of the Kanban component. They will provide you with hard coded example configurations, explanations of properties, and a general overview of how to set up the component. It's important to keep in mind that the Kanban Board Component is highly customizable and uses other components for its configuration.

In this article we will provide some configuration information and example configurations for cards, lanes, and swimlanes. In the previous article, linked at the top and bottom of this article, we

covered prerequisites, go over the base configuration of the component, and showcase how to configure two example features (drag and drop & swimlanes).

This article assumes that you have some experience with UI Builder, we suggest that you first leverage one of these resources to learn more about configuring workspaces and experiences in UI Builder:

Configuration reference

Here is some more information that can help you configure the Kanban Board component. This mostly applies to how to format the data object to feed information to the components and sub-components called in the configuration we created above.

sn-vtb-card

Attributes in the data property object (not limited to):

Attribute	Description	Type	Default value
id	Card ID	String	undefined
board_id, lane_id, swim_lane_id	Reference IDs to the card's parent elements	String	undefined
labels	Card labels, only rendered if `options.show_labels` is `true`	Array of `{active, label, color}` objects	`[]`
record * Mandatory	The target record that the card is showing/representing	GlideRecord
attachment	Only rendered if `options.card_type` is `"classic"` and `options.show_cover_image` is `true`	Array of `{state}` objects	`[]`
thumbnail	Source URL to attachment thumbnail image. Only rendered if `attachment` is available.	String	undefined
isFocus	Element focus	boolean	`false`
orderPerLaneInSwimlane, countPerLaneInSwimlane	For aria-label purpose, rendering position description for each card	int	`0`

options Object

Attribute	Description	Type	Default value
board_type * Mandatory		String values: `"FREEFORM" \| "FLEXIBLE" \| "GUIDED"`
card_type * Mandatory		String values: `"compact"` `"classic"`: Rendering `record.description` as card's description, extra record information
due_date_field	A field name in `record` indicating due date.	String
show_sla		boolean	`false`
show_labels		boolean	`false`
show_card_info		boolean	`false`
show_cover_image		boolean	`false`
menu_actions	Custom action	Array of `now-dropdown.items` objects	`[]`

sn-vtb-lane-header

Attributes in the data property object (not limited to):

Attribute	Description	Type
id, sys_id	Lane ID
name	Lane name
board_id	Board ID to which the lane belongs
lanes_reference_table_records	Records to exclude in "Add new reference lane query"	Array of `sys_id`s

options Object

Attribute Description Type Default value

reference_lane_search_field, field_reference_table Attribute values for sn-vtb-reference-picker when options.board_type is "GUIDED"

menu_actions Custom action Array of now-dropdown.items objects []

board_type

String

values: "FREEFORM" | "FLEXIBLE" | "GUIDED"

options Object

Attribute	Description	Type	Default value
can_add_task	Allow adding task	boolean	false
add_card_footer_button_name	Custom text for the "Add card" button in footer section	String	"Add card"

sn-vtb-swimlane-header

Attributes in the data property object (not limited to):

Attribute	Description	Type	Default value
id	Swimlane ID	String
name	Swimlane header	String
addLaneButton	Allow adding lane	Boolean	`false`

options Object

Attribute Description Type Default value

menu_actions Custom action Array of now-dropdown.items objects []

board_type

String

values: "FREEFORM" | "FLEXIBLE" | "GUIDED"

swimlanes_reference_table_records Records to exclude in "Add new reference swimlane query" Array of sys_ids

sn-vtb-cell-header

Attributes in the data property object (not limited to):

Attribute	Description	Type	Default value
color	Sets the cell header background color.	String Options: `("critical" \| "high" \| "warning" \| "moderate" \| "positive" \| "info" \| "low" \| "magenta" \| "pink" \| "orange" \| "yellow" \| "brown" \| "green" \| "green-yellow" \| "blue" \| "gray" \| "teal" \| "purple")`	"info"
variant	Sets the shade of the cell header background and the color of the text.	String
header	Cell header title	String
headerRight	Cell header title on the right side	String
showTooltip	Flag to show tooltip for headers.	boolean
headerTooltipContent	Tooltip content for header	String
headerRightTooltipContent	Right side header tooltip content	String
laneId	Row ID	String
swimlaneId	Swimlane ID	String

sn-vtb-row-header

Attributes in the data property object (not limited to):

Attribute	Description	Type	Default value
id	Row header ID	String
name	Row header title	String
details		String array	`[ ]`
avatar		`{ username, imgSrc }` object

options Object

Attribute Description Type Default value

menu_actions Custom action Array of now-dropdown.items objects []

board_type

String

values: "FREEFORM" | "FLEXIBLE" | "GUIDED"

Example configurations

These are a few of the components that make up the Kanban Board component and their individual configurations.

Cards object configuration

Below is sample code and more information on how to configure the card component:

cards = [
                  {
                     id: 'f12ca184735123002728660c4cf6a7ef', //unique id for the card
                     title: 'INC0007001', //used as part of the aria label for the card
                     order: 0, //order the card should be displayed in within the lane
                     lane_id: 'critical', //the unique id of the lane the card is in
                     swimlane_id: 'new', //the unique id of the swimlane the card is in
                     options: {
                         board_type: "FREEFORM",
                         card_type: "classic",
                         menu_actions: [], //This supplies the dropdown items used in the card header,
                         show_labels: true, //displays the labels (dots) between header and description
                         show_card_info: true, //displays record fields as label value tabbed
                         show_cover_image : true, //displays attachments
                         due_date_field : "due_date", //record field that is used for the due date in sn-vtb-card-info-inline
                         show_sla: true //displays the SLA in sn-vtb-card-info-inline
                     },
                     attachments: [], //list of attachments, displays total on card
                     thumbnail: '', //displays this image with attachment total
                     labels: [ //shown as dots under the header
                       {
                         active: true, //only displays label if true
                         color: "#FF0000", //color of the label, must be hex value
                         value: "Test Label" //tooltip on the label
                       }
                     ],
                     checklist: { //displays checklist status in sn-vtb-card-info-inline
                       items: [
                         {
                           complete: true //marks item done in checklist display
                         }
                       ]
                     },
                     sla: {
                       percentage: 23 //displays SLA percentage in sn-vtb-card-info-inline
                     },
                     due_date_display_value: "12/31/2023", //Label for due date in sn-vtb-card-info-inline
                     record: {
                       short_description: {
                         display_value: "Employee payroll application service is down" //card header text
                       },
                       description: { 
                         display_value: "" //description under header, 2 lines max
                       },
                       number: {
                         value: 'INC0007001'  //displayed in sn-vtb-card-footer
                       },
                       sys_updated_on: { 
                         value: "2023-10-01 20:50:11", //used for timeAgo text in sn-vtb-card-footer
                         displayValue: "2023-10-01 20:50:11",
                       },
                       due_date: { 
                         value: "2023-10-01 20:50:11", //used for timeAgo text in sn-vtb-card-footer
                       },
                       test_field: { //when show_card_info is true, shows record fields that are not black listed
                         name: 'test_field', //required to show field
                         label: 'Test Field',
                         value: 'Its a test'
                       },
                       footer_text: "" //show this text in sn-vtb-card-footer if sys_updated_on does not exist
                     },
                     users: { //displays avatars of users (default 2, rest shown as tooltip) in sn-vtb-card-footer
                       primary_assignees: [
                         {
                           avatar: "", // image to show in avatar
                           name: "" // name to show in avatar
                         }
                       ],
                       additional_assignees: [
                         {
                           avatar: "", // image to show in avatar
                           name: "" // name to show in avatar
                         }
                       ]
                     }
                  }
                ];
                
                //NOTE: The object for each card is passed into the sn-vtb-card component as the "data" property
                //Also, no styling can be applied to the card wrapper unlike lanes and swimlanes

This is what the above card would look like fully rendered:

Card component properties

Card template

This is the component used for the card's appearance. The corresponding component is sn-vtb-card.

Card drag-and-drop option

This property enables drag and drop for the cards.

Card-drag source display template

This is the component used to display the original position of the moving card on the board. The corresponding component is sn-vtb-card-src-placeholder.

Card-drop destination display template

This is the component used to display the position where card will be moved to on the board. The corresponding component is sn-vtb-card-dest-placeholder.

Cards

This is an array of card configuration objects. This will determine what is displayed in the above components.

Override card configurations

This is an object containing the card ids as a property. This can override the above global configurations for a specific card.

An example of how to configure the Override card configurations property:

<card-id>: {  //This is the id of the card that should be overridden
                    tag: 'sn-vtb-freeform-card-editable' //different component to render the card
                    dragPlaceholderTag: 'sn-empty-card-area', //different component to 
                    dropPlaceholderTag: 'sn-dotted-card-area'
                    draggable: false, //overrides the cardDraggable property
                  }

Lanes object configuration

Below is sample code and more information on how to configure the lanes component:

lanes = [
                  {
                     id: 'critical', //unique id for the lane
                     title: 'Critical', //used as part of the aria label for the lane
                     name: 'Critical', //displays this text in the sn-vtb-lane-header
                     cardsCount: 5, //displays the number of cards in the lane in the sn-vtb-lane-header
                     options: { //more properties to be used
                        boardType: "FREEFORM", //if boardType is GUIDED, you cannot edit the name in-line in sn-vtb-lane-header
                        menu_actions: [], //This supplies the dropdown items used in the sn-vtb-lane-header
                        can_add_task: true, //displays button in sn-vtb-lane-footer
                        add_card_footer_button_name: "Add Card" //Label for button in sn-vtb-lane-footer
                     },
                     _style_: { //adds additional styling to the following classes
                       "sn-lane-header": {
                         "margin-top": "-4px"
                       }
                       "sn-vtb-lane-header": {
                         "background": "--now-color_surface--brand-1"
                       },
                       "sn-lane": {
                         "width": "287px",
                         "padding": "3px",
                         "overflow-y": "auto",
                         "height": "100%"
                       },
                       "lane-footer-container": {
                         "position": "sticky",
                         "bottom": "30px"
                       },
                       
                     }
                  }
                ];
                
                //NOTE: The object for each lane is passed into the sn-vtb-lane-header and sn-vtb-lane-footer components as the "data" property

Lane component properties

Vertical lane header template

This is the component used for the lane heading. The corresponding component is sn-vtb-lane-header.

Lane footer template

This is the component used for the lane footer. The corresponding VTB component is sn-vtb-lane-footer.

Vertical lane drag-and-drop option

This property enables drag and drop for the lanes.

Vertical lane-drag source display template

This is the component used to display the original position of the moving lane on the board. The corresponding component is sn-vtb-lane-src-placeholder.

Vertical lane-drop destination display template

This is the component used to display the position where lane will be moved to on the board. The corresponding component is sn-vtb-lane-dest-placeholder.

Vertical lanes

This is an array of lane configuration objects. This will determine what is displayed in the above components.

Override vertical lane configurations

This is an object containing the lane ids as a property. This can override the above global configurations for a specific lane.

An example of how to configure the Override lane configurations property:

  critical: {  //This is the lane id, same as the one used above
                    draggable: false, //overrides the laneDraggable property, cannot drag lane if false
                    droppable: false, //overrides the laneDroppable property, cannot drop into lane if false
                    hide_in_reorder: true, //does not show lane in lane sorting modal
                    tag_lane_header: "your-example-lane-header", //different component to show in the lane header
                    tag_lane_footer: "your-example-lane-footer", //different component to show in the lane footer
                    tag_drag_placeholder: "your-example-drag-placeholder", //different component to show as the drag placeholder
                    tag_drop_placeholder: "your-example-drop-placeholder", //different component to show as the drop placeholder
                    sort_enabled: true, //if sort enabled is true, will use the sorting order of the lane instead of where it is dropped
                    sort_tag_drop_placeholder: "sn-sort-card-dest-placeholder", //placeholder component from VTB library
                    sort_placeholder_text: "Card will be ordered in the lane according to fields on which the board is sorted" //Message displayed in the sn-sort-card-dest-placeholder
                  }

If sort_enabled is true, when a card from that lane is dropped into another lane, the sort_tag_drop_placeholder component will appear instead of the card destination placeholder component (configured as the Vertical lane-drop destination display template property in the Kanban component)

NOTE: A card being dropped into the above lane will still show the Card-drop destination display template unless the lane the card is from also has been overridden with sort_enabled set to true.

Swimlanes object configuration

Below is sample code and more information on how to configure the swimlanes component:

swimlanes = [
                  {
                     id: 'new', //unique id for the swimlane
                     title: 'New', //used as part of the aria label for the swimlane
                     name: 'New', //displays this text in the sn-vtb-swimlane-header
                     cardsCount: 5, //displays the number of cards in the swimlane in the sn-vtb-swimlane-header
                     options: { //more properties to be used
                        boardType: "FREEFORM", //if boardType is GUIDED, you cannot edit the name in-line in sn-vtb-swimlane-header
                        menu_actions: [], //This supplies the dropdown items used in the sn-vtb-swimlane-header,
                        addLaneButton: true //property to show the add lane button if using sn-vtb-add-swimlane (more info below)
                     },
                     collapsed: false, //shows the swimlane as expanded or collapsed
                     _style_: { //adds additional styling to the following classes
                       "sn-swimlane": {
                         "height": "100%"
                       },
                       "sn-swimlane-header": {
                         "width": "200px",
                         "height": "100%"
                       },
                       "swimlane-body": {
                         "padding": "3px 3px"
                       }
                     }
                  }
                ];
                
                //NOTE: The object for each swimlane is passed into the sn-vtb-swimlane-header component as the "data" property

Swimlane component properties

Swimlane header template

This is the component used for the swimlane heading. The corresponding component is sn-vtb-swimlane-header.

Swimlane header template as vertical lane is dragged

This is the component used to show a swimlane when dragging a lane. The corresponding component is sn-vtb-swimlane-header-clone.

Swimlane drag-and-drop option

This property enables drag and drop for the swimlanes.

Swimlane-drag source display template

This is the component used to display the original position of the moving swimlane on the board. The corresponding component is sn-vtb-swimlane-src-placeholder.

Swimlane-drop destination display template

This is the component used to display the position where the swimlane will be moved to on the board. The corresponding component is sn-vtb-swimlane-dest-placeholder.

Swimlanes

This is an array of swimlane configuration objects. This will determine what is displayed in the above components.

Override swimlane configurations

This is an object containing the swimlane ids as a property. This can override the above global configurations for a specific swimlane.

An example of how to configure the Override swimlane configurations property:

 new: {  //This is the lane id, same as the one used above
                    draggable: false, //overrides the swimlaneDraggable property, cannot drag swimlane if false
                    droppable: false, //overrides the swimlaneDroppable property, cannot drop into swimlane if false
                    hide_in_reorder: true, //does not show swimlane in swimlane sorting modal
                    tag_swimlane_header: "your-example-swimlane-header", //different component to show in the swimlane header
                    tag_drag_placeholder: "your-example-drag-placeholder", //different component to show as the drag placeholder
                    tag_drop_placeholder: "your-example-drop-placeholder", //different component to show as the drop placeholder
                    laneConfigOverride: {
                      <lane-id> : {
                        droppable: true //can override if a card can be dropped into a cell if the lane or swimlane does the opposite
                    }
                  }
                }

If the "Show swimlane header in the row" option is enabled, it reveals several more configuration options. This will show the swimlane headers on the same rows as the cards, instead of being above. The Swimlane header template should be updated to use the sn-vtb-row-header component if you wish to use this configuration.

Show swimlane header in the row

This is a boolean property that turns this configuration on.

Lane header template for row column

This is the component used for the lane heading above the column of row headers. The corresponding component is sn-vtb-lane-header.

Configuration for row lane

This is a JSON object that has the configuration used for lane configuration.

Below is sample object code with updated properties when using sn-vtb-row-header instead of sn-vtb-swimlane-header:

swimlanes = [
                  {
                     id: 'new', //unique id for the swimlane
                     title: 'New', //used as part of the aria label for the swimlane
                     name: 'New', //displays this text in the sn-vtb-row-header
                     cardsCount: 5, //displays the number of cards in the swimlane in the sn-vtb-row-header
                     details: [], //Array of label-value items used by the now-label-value-stacked component
                     avatar: { //if configured, displays an avatar in the row header
                       userName: "Fred Luddy",
                       imageSrc: "https://exampleimage.com",
                       presence: "available"
                     },
                     options: { //more properties to be used
                        boardType: "FREEFORM", //Not used with sn-vtb-row-header
                        menu_actions: [], //This supplies the dropdown items used in the sn-vtb-row-header,
                     },
                     collapsed: false, //shows the row as expanded or collapsed
                     _style_: { //adds additional styling to the following classes
                       "sn-swimlane": {
                         "height": "100%"
                       },
                       "sn-swimlane-header": {
                         "width": "200px",
                         "height": "100%"
                       },
                       "swimlane-body": {
                         "padding": "3px 3px"
                       }
                     }
                  }
                ];
                
                //NOTE: The object for each swimlane is passed into the sn-vtb-row-header component as the "data" property

Conclusion

This article contained configuration reference information for the Kanban Board component. Feel free to post any questions you may have in the comments below.

Check out Part 1 of this article series for the initial configuration steps for this component.

You can also check out the You and I Builder Live! livestream where we covered this component.

Check out the Next Experience Center of Excellence for more resources

WORKFLOW-COWBOY · ‎09-30-2024

The formatting on this article is awesome!!!

KarthikeyanR · ‎12-25-2024

HI @MGOPW / @Brad Tilton

How to enable Quick Panel (User Names, Labels) on Top in Kanban Board. I don't find the details in document as well.

Regards,
Karthikeyan R

Kanban Board Component - Part 2 - Configuration reference