Setting property definition properties for custom controls

Define your own properties for the custom control. You can specify default editors and values to use when setting properties for custom controls inside XPages. You can also write scripts that determine when properties are visible and considered valid inside XPages.

Before you begin

After you define properties, you can organize them into groups and rearrange them in a tree view for easy access. After you insert the custom control into an XPage, you can set values for the properties by clicking the All Properties tab in the Properties view.

About this task

For example, the following two scenarios describe situations in which developers may want to define their own properties and values:

Scenario 1

You are working with a custom control that contains a label. You want to be able to bind a value to the label and allow the label to vary for each use on an XPage or custom control. To do this, you take the following steps:
  1. Select the custom control in the XPages editor.
  2. In the Properties view, click the Property Definition tab.
  3. Click New Property.
  4. Type name in the Name field, and specify string as the property type.
  5. Add a label to the custom control.
  6. Click File > Save to save your changes.
  7. Create an XPage and add the custom control to it.
  8. Select the custom control in the XPage.
  9. In the Properties view, click the All Properties tab.
  10. In the other category, find the property called name.
  11. In the Value field, type country.
  12. Click File > Save to save your changes.

Scenario 2

You are working with a custom control that displays the days of the week. You want to define a property that determines if the weekdays should display in a combo box or a list box. To do this, you take the following steps:
  1. Select the custom control in the XPages editor.
  2. In the Properties view, click the Property Definition tab.
  3. Click New Property.
  4. Type display in the Name field, and specify string as the property type.
  5. Add both a combo box and a radio button to the custom control.
  6. In the XPages editor, select the combo box.
  7. In the Properties view, click the Combo Box tab.
  8. With Visible selected (the default), click the computed property menu button.
  9. Select Compute value.
  10. In the script editor, select EL as the scripting language.
  11. Select Compute on Page Load.
  12. In the field, type this formula: return "combo" == compositeData.get("display");.
  13. Click OK to close the script editor.
  14. In the XPages editor, select the list box.
  15. In the Properties view, click the List Box tab.
  16. With Visible selected (the default), click the computed property menu button.
  17. Select Compute value.
  18. In the script editor, select EL as the scripting language.
  19. Select Compute on Page Load.
  20. In the field, type this formula: return "list" == compositeData.get("display");.
  21. Click OK to close the script editor.
  22. Click File > Save to save your changes.
  23. Create an XPage and add the custom control to it.
  24. Select the custom control in the XPage.
  25. In the Properties view, click the All Properties tab.
  26. In the custom category, find the property called display.
  27. In the Value field, type list.
  28. Click File > Save to save your changes.

To set property definition properties, do the following steps

Procedure

  1. Open the custom control as an independent design element in the editor.
  2. In the Properties view, click the Property Definition tab.
    Note: By default, Domino® Designer provides a root node from which you can build the property tree. The root node does not have any properties.
  3. Click New Property to insert a new property directly under the root node. By default, the first property is called property_1. The next one is property_2, then property_3, and so on.
    Note: Steps for creating groups of properties are below.
  4. On the right side of the Properties view, click the Property tab, and do the following steps:
    1. In the Name field, type the name of the property. The tree view to the left automatically gets updated with the new name.
    2. In the Type field, type the property type or select the type of property from the list. The list contains the following options:
      • boolean
      • byte
      • char
      • double
      • float
      • int
      • long
      • localizable string
      • resource path
      • short
      • string
      The default type is string.
    3. In the Editor field, select the editor that will open by default when defining values for the property. To select an editor that is not in the list, click the icon to open the Select Editor dialog box and do the following steps:
      1. To search for a particular editor, type the name of the editor in the field at the top. If Domino® Designer finds matching editors, they display in the Matching editors field below.
      2. To find an editor without searching, expand the categories in Matching editors field, and select an editor.
      3. To learn more about a particular editor, see the Editor details section. This section provides a brief description of the editor.
      4. After you select an editor, click OK to close the Select Editor dialog box. The editor name displays in the Editor field.
    4. In the Parameters field, type any parameters that are required to initialize the default editor. This field is enabled only if the default editor requires parameters. For example, the combo box editor requires a String parameter that is a delimited list of values.
    5. In the Default value field, type the default value of the property.
    6. Select the Allow multiple instances check box if the property allows multiple values. If selected, you will be able to create multiple instances of the property when setting properties for the custom control inside an XPage.
  5. To set validation properties, click the Validation tab, and do the following steps:
    1. Select the Required field check box if the property requires you to type a value for the property when the custom control is inside an XPage.
    2. In the script editor, type a JavaScript™ expression that produces a boolean. When true, the property value is considered valid.
  6. To set properties for making the property visible when the custom control is inside an XPage, click the Visible tab, and type a JavaScript™ expression that produces a boolean. When true, the property value is visible.
  7. Repeat the steps above for any new properties that you want to define for the custom control.
  8. To organize properties into groups, click New Group. By default, the first group property is called group_1. The next one is group_2, then group_3, and so on. Domino® Designer automatically adds a new property to the group by default.
  9. On the right side of the Properties view, click the Group tab, and do the following steps:
    1. In the Name field, type the name of the group. The tree view to the left automatically gets updated with the new name.
    2. Select the Allow multiple instances check box if the group allows multiple values. If selected, you will be able to create multiple instances of the group when setting properties for the custom control inside an XPage.
  10. To set properties for making the group visible when the custom control is inside an XPage, click the Visible tab, and type a JavaScript™ expression that produces a boolean. When true, the group is visible.
  11. To delete properties and groups, select the property or group in the tree view and click Delete.
  12. To rearrange properties and groups in the tree view, select a property or group and click Move Up or Move Down.
  13. Click File > Save to save your changes.