Palette Customization¶

The Palette’s appearance and behaviour can be customized using configuration options and various canvas controller methods.

Populating the palette¶

The palette definition is a JavaScript object consisting of an array of category objects with each category containing an array of node templates (node_types).

This object can be specified to Common Canvas by calling the canvas-controller method:

   canvasController.setPipelineFlowPalette(palette);

The palette object is often read from a JSON document stored in the host application’s repository or it can be automatically generated.

JSON Schema¶

The palette object must conform to the palette schema.

The host application can ensure that the palette conforms to the schema by switching schema validation to true in the canvas configuration. If the palette is not valid, errors will be displayed in the debugger console.

Palette configuration¶

The following canvas config options can be specified to control aspects of the palette:

enablePaletteLayout - show or hide the palette
enableNarrowPalette - display a narrow palette or nothing when the palette is closed
enableSingleClickAddFromPalette - allow a single-click on a palette node to automatically add it to the canvas
enableAutoLinkOnlyFromSelNodes - controls the nodes to which automatically-added nodes are linked.
enablePaletteHeader - allows the application to add additional content to the palette

Palette methods¶

The Canvas Controller provides numerous customization methods that can be used to customize the palette contents. There are also some operational methods that can be used to open, close and query the state of the palette.

Example¶

The “Flows” sample app in the test harness as its own palette. The files for that sample app here: https://github.com/elyra-ai/canvas/tree/main/canvas_modules/harness/src/client/components/custom-canvases/flows This folder contains all the files that make up the Flows sample app. The flows-palette.json file in the folder can be studied to see how it results in the palette displayed.

Search¶

The user can enter a search string into the Search field at the top of the palette. The behavior is as follows:

When the search field is empty, the palette shows categories which can be expanded to show the node templates within the expanded category.
As the user enters characters into the search field, Common Canvas immediately searches through the node template labels, node template descriptions and category labels for the characters entered and finds a subset of the node templates that match the search string. Common Canvas then replaces the category-based view of the palette with a list of node templates that match the search criteria. In this view the node templates also include the node description under the node label.
The search is case insensitive.
The search text is highlighted wherever it appears in the labels, descriptions or category labels.
Common Canvas uses a ranking algorithm to order the display of node templates so those most relevant to the search text are positioned at the top of the list. The ranking algorithm puts more weight on those node templates where the search text appears in the label than if the text appears in the description or the category label.
If the user enters words into the search field (separated by spaces), Common Canvas searches for each word separately. Therefore, if say the user entered “data import” into the search field, Common Canvas would find a node with “Import Data” as the label or even a node with a description that said “This node does lots of things and also data can be imported.”
Nodes that have text which have hits on multiple words are ranked more highly than node templates whose text only contains one search word.
Common Canvas uses a debounce function so that, if the user types the search string very quickly, Common Canvas does not perform multiple searches for each key press but only runs a full search when rapid typing has ended.

Recommendation¶

According to the schema, node template descriptions are not mandatory in the palette object. However, it is recommended you provide descriptions for each of your node templates. The reason for this is that, the search function searches through node template descriptions, as well as node template labels and category labels. This means you can write your node template descriptions to contain appropriate keywords that a user might search for when looking for a node.

For example, if there is a node template called ‘Import Data’ and that node could import comma-separated files you could add ‘comma-separated’ and ‘csv’ into your description for that node template. If the user entered comma in the search field the ‘Import Data’ node template would be shown in the search results even though comma does not appear in the node template label.

Node template `palette_*` attributes¶

Node templates in the palette can be customized using three special attributes that are set inside app_data.ui_data of each node type entry in the palette JSON. These attributes control how the node appears and behaves in the palette without affecting the node once it has been added to the canvas.

`palette_disabled`¶

Type: boolean

When set to true, the node template is displayed in the palette in a visually dimmed state and cannot be dragged onto the canvas or added via single-click or double-click. The node icon is rendered at reduced opacity using the disabled fill color. This is useful for indicating that a node is not available under current conditions — for example, when a required license is inactive or a dependent service is not configured.

"app_data": {
  "ui_data": {
    "label": "My Node",
    "image": "/images/my-node.svg",
    "palette_disabled": true
  }
}

`palette_image`¶

Type: string (URL or data URI)

Specifies an alternative image to display for the node when it is shown in the palette. When this attribute is present it overrides the node’s image field only within the palette. Once the user drags or adds the node to the canvas, the standard image value is used instead.

This is useful when you want a distinct icon in the palette — for example a generic placeholder image — while preserving the intended node icon on the canvas.

"app_data": {
  "ui_data": {
    "label": "My Node",
    "image": "/images/canvas-icon.svg",
    "palette_image": "/images/palette-icon.svg"
  }
}

`palette_class_name`¶

Type: string

Adds one or more extra CSS class names to the node’s outermost <div> element in the palette. This allows the host application to apply custom styles to specific node templates, independently of all other nodes.

Multiple classes can be provided as a single space-separated string.

"app_data": {
  "ui_data": {
    "label": "My Node",
    "image": "/images/my-node.svg",
    "palette_class_name": "my-custom-node highlighted-node"
  }
}