Skip to main contentElyra

Properties documentation

The Elyra test harness (http://ibm.biz/elyra-canvas) allows consumers to explore a number of configurations of both the canvas as well as properties. All current documentation of Common properties components may be found here.

The examples below show off consumers who have adopted the Elyra canvas technology.

Introduction

Common properties displays controls to view and set property values.

You can look at the harness/src/client/App.js file of this repo to see examples of code that uses the common properties component. Getting started with Common Properties programming

This takes 3 easy steps:

Step 1 : Import

To use Common Properties in your React application you need to do the following. First import the CommonProperties React component from the common-canvas library. It’s recommended to use All Components if common-canvas is also being imported, otherwise use Properties only option.

All Components

import { CommonProperties } from "@elyra/canvas";

Properties Only

import { CommonProperties } from "@elyra/canvas/dist/lib/properties";

Step 2 : Set the data

Next you’ll need to populate propertiesInfo with:

propertiesInfo: {
  parameterDef: this.parameterDef,          // Parameter definitions/hints/conditions
  appData: "{user-defined}",                // User data returned in applyPropertyChanges [optional]
  additionalComponents: "{components}",     // Additional component(s) to display [optional]
  messages: "[node_messages]",              // Node messages array [optional]
  expressionInfo: this.expressionInfo,      // Information for expression builder [optional],
  initialEditorSize: "{size}"               // This value will override the value of editor_size in uiHints. This can have a value of "small", "medium", "large", or null [optional]
}

or…

(Deprecated)

propertiesInfo: {
  formData: this.formData,
  appData: "{user data returned back in applyPropertyChanges}", //optional
  additionalComponents: "{additional control(s) to display}",   //optional
  messages: "[node_messages]",                                  // Node messages array [optional]
  expressionInfo: this.expressionInfo,                          // Information for expression builder [optional]
  initialEditorSize: "{size}"                                   // This value will override the value of editor_size in uiHints. This can have a value of "small", "medium", "large", or null [optional]
}

Step 3 : Display the properties editor

Finally you’ll need to display the editor. Inside your render code, add the following:

import { IntlProvider } from "react-intl";
var i18nData = require("../intl/en.js");


var locale = "en";
var messages = i18nData.messages;
  <IntlProvider key="IntlProvider2" locale={ locale } messages={ messages }>
    <CommonProperties
      ref={(instance) => {
        this.CommonProperties = instance;

Properties

  • propertiesInfo object: See above
  • propertiesConfig object:
  • containerType string: type of container to display the properties, can be “Modal” or “Custom”. default: ”Custom”
  • rightFlyout boolean: if custom container is a right-flyout, set to true. default: false
  • applyOnBlur boolean: calls applyPropertyChanges when focus leave common-properties. default: false
  • disableSaveOnRequiredErrors boolean: Disable the properties editor “save” button if there are required errors
  • enableResize boolean: adds a button that allows the right-side fly-out editor to expand/collapse between small and medium sizes. default: true
  • conditionReturnValueHandling string: used to determine how hidden or disabled control values are returned in applyPropertyChanges callback. Current options are “value” or “null”. default: ”value”
    • buttonLabels object:
    • primary string: Label to use for the primary button of the properties dialog
    • secondary string: Label to use for the secondary button of the properties dialog
  • heading boolean: show heading and heading icon in right-side fly-out panels. default: false
  • schemaValidation boolean: If set to true, schema validation will be enabled when a parameter definition has been set in CommonProperties. Any errors found will be reported on the browser dev console. It is recommended you run with schema validation switched on while in development mode.
  • applyPropertiesWithoutEdit boolean: When true, will always call applyPropertyChanges even if no changes were made. default: false
  • maxLengthForMultiLineControls number - maximum characters allowed for multi-line string controls like textarea. default: 1024
  • maxLengthForSingleLineControls number - maximum characters allowed for single-line string controls like textfield. default: 128
  • callbacks object - See below for more details on each callback method
    • applyPropertyChanges // required
    • closePropertiesDialog // required
    • helpClickHandler // optional
    • controllerHandler // optional
    • propertyListener // optional
    • actionHandler // optional
    • buttonHandler // optional
  • View Common Properties Custom Components for the following:
    • customPanels array: array of custom panels.
    • customControls array: array of custom controls.
    • customConditionOps array: array of custom condition operators.
  • light boolean: Carbon controls in common-properties will use light mode. When the light option is disabled, the background color will be the same as the Carbon theme background. When the light option is enabled, the background color is set to $ui-01. Defaults to true

Internationalization and override of labels in CommonProperties

The CommonProperties dialogs have a set of labels that can have customized and internationalized values. CommonProperties uses the react-intl package to provide internationalization of these labels. This requires the IntlProvider element to wrap the CommonProperties element. You can look at the harness/src/intl/en.js file of this repo to see the list of labels and the default values.


Reference methods

/*
* @closeEditor (boolean) - determines if closePropertiesDialog is called or not 
*/
applyPropertiesEditing(closeEditor)

Using CommonProperties in CommonCanvas right-flyout panel

Common Canvas has a right-flyout panel that can render a React object. It can be used to render Common Properties in a flyout panel.

Create a CommonProperties object with containerType set to “Custom” and rightFlyout set to true.

    const rightFlyoutContent =(<CommonProperties
        propertiesInfo={this.propertiesInfo}
        propertiesConfig={{ containerType: "Custom", rightFlyout: true }}
        callbacks={this.callbacks}  
    />);

Pass the CommonProperties object into CommonCanvas’s rightFlyoutContent props. Also set the showRightFlyout boolean to tell CommonCanvas when to show the rightFlyout.

    <CommonCanvas
  config={commonCanvasConfig}
  contextMenuHandler={this.contextMenuHandler}
  contextMenuActionHandler= {this.contextMenuActionHandler}
  editActionHandler= {this.editActionHandler}
  clickActionHandler= {this.clickActionHandler}
  decorationActionHandler= {this.decorationActionHandler}
  toolbarConfig={toolbarConfig}
  toolbarMenuActionHandler={this.toolbarMenuActionHandler}

Callbacks

applyPropertyChanges(propertySet, appData, additionalInfo, undoInfo, uiProperties)

Executes when the user clicks OK in the property dialog. This callback allows users to save the current property values.

  • propertySet: The set of current property values
  • appData: (optional) application data that was passed in to propertiesInfo
  • additionalInfo: Object with additional information returned:
    • messages: (optional) An array of messages associated with the nodes current property values.
    • title: The title of the properties editor
  • undoInfo: Object with information needed to undo this apply:
    • properties: Set of property values;
    • messages: (optional) An array of messages associated with the nodes property values.
    • uiProperties: (optional) Set of UI only properties values
  • uiProperties: The set of UI only property values (optional)
applyPropertyChanges(propertySet, appData, additionalInfo, undoInfo, uiProperties) {
  var data = {
    propertySet: propertySet,
    appData: appData,
    additionalInfo: {
        messages: messages,
        title: title
    }
  };

closePropertiesDialog(closeSource)

Executes when user clicks Save or Cancel in the property editor dialog. This callback is used to control the visibility of the property editor dialog. closeSource identifies where this call was initiated from. It will equal “apply” if the user clicked on “Save” when no changes were made, or “cancel” if the user clicked on “Cancel”

closePropertiesDialog() {
  this.setState({ showPropertiesDialog: false, propertiesInfo: {} });
}

propertyListener()

Executes when a user property values are updated.

propertyListener(data) {


}

controllerHandler()

Executes when the property controller is created. Returns the property controller. See https://github.com/elyra-ai/canvas/wiki/3.6-Common-Properties-Controller for APIs

controllerHandler(propertyController) {


}

actionHandler()

Called whenever an action is ran. id and data come from uihints and appData is passed in with propertiesInfo.

actionHandler(id, appData, data) {


}

buttonHandler()

Called when the edit button is clicked on in a readonlyTable control. The callback provides the following data:

  • data: an object that consists of
    • type: of button the click was invoked from. Currently, only type: edit is returned today from the edit button click of a readonlyTable control.
    • propertyId: of the control that was clicked.
buttonHandler(data) {


}

helpClickHandler()

Executes when user clicks the help icon in the property editor dialog. The callback provides the following data:

  • nodeTypeId: in case of parameterDef, id property of uihints; in case formData, the componentId.
  • helpData: Optional helpData specified in paramDef/formData (see below).
  • appData: Optional application data that was passed in to propertiesInfo
helpClickHandler(nodeTypeId, helpData, appData) {


}

To control whether a node shows the help icon in the right fly-out, a help object with optional helpData needs to be provided in the paramDef or formData:

If no help object is found, no help link will be shown.

Previous
Common Canvas: External subflows support
Next
Common Properties: Parameter definition