Examples: Adding Management Center properties view widgets

By reviewing code samples that create some common properties view widgets, you can better understand how to implement these widgets in your own properties views. The code samples also illustrate how to make a required property and how to add an enablement condition for certain properties.
The sample code creates the following types of properties view widgets:

Common properties view widgets

Properties view widget Description
1 Input text property User can type text in an entry field. Example:
2 Radio group property User can choose one option from a series of mutually exclusive options. Example:
3 Stepper property User can step up or down through a series of numerical values within a set range. Example:
4 Input text property (required) Same as Input text property, except that a red asterisk is included on the widget label, and red validation messages display until the user enters a valid value. Example:
5 Combination box property User can choose from a drop-down list of selectable options. Example:
6 Check box property User can toggle between a true value and a false value. Example:
The sample code also demonstrates the following widget behavior:
A required field
You can set any property to be required. As a result, Management Center displays validation messages for the property until the user completes the property. For an example, see the property that is labeled with the callout 4 (Input Text Required Property).
Enablement conditions
You can set enablement conditions for a property. As a result, the property is displayed to the user only when certain conditions are met, for example, a specific radio button is selected in another property. For examples of properties that are controlled by an enablement condition, see the properties that are labeled with the callouts 3 (Stepper Property), 4 (Input Text Required Property), and 5 (Combobox Property).

Example properties view

The sample code creates the following properties view, which contains the six types of properties view widgets that are listed in the previous table. Figures 1 to 4 show how certain properties are displayed and hidden when the user selects different options from the Radio Group Property. This behavior is controlled by enablement conditions that are defined in the properties view definition. Figures 3 and 4 show the behavior of a validation message for a required field.

Figure 1. User selects Option A from Radio Group Property

The Combobox Property and Checkbox Property (5 and 6) are displayed.

Properties view when Option A is selected
Figure 2. User selects Option C from Radio Group Property

As in Figure 1, the Combobox Property and Checkbox Property (5 and 6) are displayed.

Figure 3. User selects Option B from Radio Group Property
As a result:
  • The Stepper Property and Input Text Required Property (3 and 4) are now displayed.
  • The Combobox Property (5) is no longer displayed.
Also, the Input Text Required Property field is a required field. For this reason, the red validation messages are displayed to the right of the field and at the top of the window. The validation messages remain until the user specifies text in the field.

Properties view when Option B is initially selected
Figure 4. User enters text in Input Text Required Property

As a result, the validation messages are cleared.

Object definition code sample

The following code snippet is from the object definition for the properties view shown in figures 1 to 4. The numbered callouts indicate the properties view widget that the code references.
<!-- The xWidgetProp_testWidgetRadioGroupProperty property has 3 values: optionA, optionB, optionC -->
<PropertyDefinition propertyName="xWidgetProp_testWidgetRadioGroupProperty">
	<PropertyValue displayName="${mycompanyPageLayoutResources.testWidgetRadioGroupProperty_optionA}" value="optionA" />
	<PropertyValue displayName="${mycompanyPageLayoutResources.testWidgetRadioGroupProperty_optionB}" value="optionB" />
	<PropertyValue displayName="${mycompanyPageLayoutResources.testWidgetRadioGroupProperty_optionC}" value="optionC" />

<!-- The xWidgetProp_testWidgetStepperProperty property is an integer, range is from 1 to 2147483647 -->
<PropertyDefinition propertyName="xWidgetProp_testWidgetStepperProperty" 

<!-- The xWidgetProp_testWidgetInputTextRequiredProperty is a required property -->
<PropertyDefinition propertyName="xWidgetProp_testWidgetInputTextRequiredProperty" 
	<EnablementCondition conditionId="testWidgetPropertyGroup1Condition" 
		propertyName="xWidgetProp_testWidgetRadioGroupProperty" enablementValue="optionB" />

<!-- The xWidgetProp_testWidgetComboboxProperty property has 3 values: 1, 2, 3 -->
<PropertyDefinition propertyName="xWidgetProp_testWidgetComboboxProperty">
	<PropertyValue displayName="${mycompanyPageLayoutResources.testWidgetComboboxPProperty_option1}" value="1" />
	<PropertyValue displayName="${mycompanyPageLayoutResources.testWidgetComboboxPProperty_option2}" value="2" />
	<PropertyValue displayName="${mycompanyPageLayoutResources.testWidgetComboboxPProperty_option3}" value="3" />

<Xml name="template">

Properties view definition code sample

The following code snippet is from the properties view definition for the properties view shown in figures 1 to 4. The numbered callouts indicate the properties view widget that the code references.

Notice how the enablement conditions are set up in the properties view definition:

<PropertyGroup name="widgetProperties" collapsable="false" groupTitle="${PageLayoutResources.widgetPropertiesPrompt}">
<PropertyInputText name="${PageLayoutResources.widgetNamePrompt}" propertyName="widgetName"
	promptText="${PageLayoutResources.widgetNamePrompt}" />

<!-- Use Input Text -->
<PropertyInputText propertyName="xWidgetProp_testWidgetInputTextProperty"
	promptText="${mycompanyPageLayoutResources.testWidgetInputTextPropertyPrompt}" />

<!-- Use RadioGroup-->
<PropertyRadioGroup propertyName="xWidgetProp_testWidgetRadioGroupProperty" 
	promptText="${mycompanyPageLayoutResources.testWidgetRadioGroupPropertyPrompt}" />						

<!-- This property group will be enabled when the value of xWidgetProp_testWidgetRadioGroupProperty property is optionB -->
<PropertyGroup name="testWidgetPropertyGroup1" collapsable="false">
	<EnablementCondition conditionId="testWidgetPropertyGroup1Condition" 
		propertyName="xWidgetProp_testWidgetRadioGroupProperty" enablementValue="optionB" />

	<!-- Use Stepper -->
	<PropertyStepper propertyName="xWidgetProp_testWidgetStepperProperty" 
		promptText="${mycompanyPageLayoutResources.testWidgetStepperPropertyPrompt}" />	
	<!-- Use Input Text: required property -->
	<PropertyInputText propertyName="xWidgetProp_testWidgetInputTextRequiredProperty"
		promptText="${mycompanyPageLayoutResources.testWidgetInputTextRequiredPropertyPrompt}" />	

<!-- This property group will be enabled when the value of xWidgetProp_testWidgetRadioGroupProperty property is optionA or optionC -->
<PropertyGroup name="testWidgetPropertyGroup2" collapsable="false">
	<EnablementOrCondition conditionId="testWidgetPropertyGroup2Condition">
		<EnablementCondition propertyName="xWidgetProp_testWidgetRadioGroupProperty" enablementValue="optionA" />
		<EnablementCondition propertyName="xWidgetProp_testWidgetRadioGroupProperty" enablementValue="optionC" />
	<!-- Use Combobox -->
	<PropertyCombobox propertyName="xWidgetProp_testWidgetComboboxProperty" 
		promptText="${mycompanyPageLayoutResources.testWidgetComboboxPropertyPrompt}" />

<!-- Use Checkbox -->
<PropertyCheckbox propertyName="xWidgetProp_testWidgetCheckboxProperty" 
	text="${mycompanyPageLayoutResources.testWidgetCheckboxPropertyPrompt}" />