Getting started with Common Properties¶
Introduction¶
Common Properties is directed by a JavaScript object called the Parameter Definition. The ‘paramDef’ object describes the properties to be displayed as controls in the <CommonProperties>
React object.
You can look at the harness/src/client/App.js file to see examples of code that uses the common-properties component.
Building a properties panel in a React application¶
To use Common Properties in your React application complete the following steps:
Step 1 : Setup¶
Complete the setup steps documented in the Initial Setup page.
Step 2 : Import Common Properties¶
Import the Common Properties React component from the Elyra Canvas library. Elyra Canvas produces both esm and cjs outputs. By default esm will be used when webpack is used to build the application.
import { CommonProperties } from "@elyra/canvas";
To import only Common Properties functionality in cjs
format use:
import { CommonProperties } from "@elyra/canvas/dist/lib/properties";
Step 2 : Create the propertiesInfo object¶
Next, you’ll need to populate propertiesInfo, which is a required prop, with:
this.propertiesInfo = {
parameterDef: this.parameterDef, // Required - Parameter definitions/hints/conditions
appData: "{user-defined}", // Optional - User data returned in applyPropertyChanges
additionalComponents: "{components}", // Optional - Additional component(s) to display
messages: "[node_messages]", // Optional - Node messages array
expressionInfo: this.expressionInfo, // Optional - Information for expression builde
initialEditorSize: "{size}", // Optional - This value will override the value of
// editor_size in uiHints. This can have a value of
// "small", "medium", "large", or null
id: "{id}" // Optional - Unique parameter definition ID
}
The expressionInfo object must conform to the expressionInfo schema
The optional messages attribute can be used to set validation messages associated with a node. The format of the message objects is defined in Pipeline Flow UI schema
Step 3 : Display the Common Properties object¶
Finally, you’ll need to display the Common Properties object. Inside your render code, add the following:
return (
<IntlProvider>
<CommonProperties
ref={(instance) => {
this.CommonProperties = instance;
}}
propertiesInfo={this.propertiesInfo} // Required
callbacks={this.callbacks} // Required
propertiesConfig={this.propertiesConfig} // Optional
customPanels={[CustomSliderPanel, CustomTogglePanel]} // Optional
customControls={[CustomSliderControl]} // Optional
customConditionOps={[CustomConditionOps]} // Optional
light // Optional
/>
</IntlProvider>
);
See the Localization section of the Initial Setup page to see how <IntlProvider>
can be configured.
Props
- propertiesInfo
object
: See above - callbacks object - See the Callbacks page
- propertiesConfig
object
- See the Properties Config page - customPanels
array
: An array of custom panels. See Custom Panels section of the Common Properties Custom Components page. - customControls
array
: An array of custom controls. See Custom Controls section of the Common Properties Custom Components page.. - customConditionOps
array
: An array of custom condition operators. See Custom Condition Operators section of the Custom Components page. - light
boolean
: Carbon controls in Common Properties will use light mode. When thelight
option is disabled, the background color will be the same as the Carbon theme background. When thelight
option is enabled, the background color is set to $ui-01. Defaults totrue
Reference methods¶
The <CommonProperties>
React object provides one reference method that can be called on a ref
of the common-properties instance.
/*
* @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 the right-flyout as follows:
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 the rightFlyoutContent
prop of Common Canvas. Also, set the showRightFlyout
boolean to tell Common Canvas the rightFlyout should be displayed (true) or hidden (false).
<CommonCanvas
canvasController={canvasController}
rightFlyoutContent={rightFlyoutContent}
showRightFlyout={showRightFlyout}
/>