Property Level Elements

Multiple property level elements can be defined within the definition level elements. Different definitions allow different types of property level elements, or are more commonly used with certain types of property level elements.

property

ELEMENT property (description*, display-name*, icon*, property-name, property-class, default-value?, suggested-value?, property-extension*)

This is as in the faces-config file format. A property is defined as part of some other definition.

For example a property named title on a component named input could appear in an XSP file as (XPage snippet):

or, if the property can have a complex-type value, it could appear as (XPage snippet):

A composite-component's properties can be referenced from value bindings within the composite-file page.

propertys can be categorized like so:

• The individual or item property types:
  
  • Method binding.
    See method-binding-property. The value in a page will be one of: a string, a binding that can evaluate to a method on some managed-bean, or a complex-type whose class extends MethodBinding, like the Simple Action complex-types.
  • Primitive.
    The value will be either a primitive (see property-class), or a binding that evaluates to a primitive.
    
  • Complex.
    The value will be either a complex-type tag, or a binding that evaluates to an instance of a complex-class.
    
  • Generic object.
    The value at runtime can be anything. The value in the page is constrained to be a String or a value binding.
    
• The container property types, which can contain multiple instances of an item type:
  
  • Collection, containing one of the item types.
    The value in a page will be a list containing any of the item types above. See the example at collection-property.
  • (Other container types have been proposed, maps and arrays, but they are not currently available)

There are examples at method-binding-property and at collection-property.
An example primitive property would be:
or an example of a boolean primitive property is the Edit Box "required" property:
An example property allowing a complex-type value is the Edit Box "converter" property:
The Edit Box "value" property allows a generic object value:

property-extension

ELEMENT property-extension ANY
Expected contents:
required*%,collection-property*%,
localizable*, property-item-class*, method-binding-property*, method-return-type*, method-param*, allow-non-binding*, allow-load-time-binding*, allow-run-time-binding*, property-add-method*, tag-attribute*,
default-property%, container-class% Also property and property-type.

* occurs in a property's property-extension
% occurs in a property-type's property-extension

attribute

ELEMENT attribute (description*, display-name*, icon*, attribute-name, attribute-class, default-value?, suggested-value?, attribute-extension*)

This is as in the faces-config format.

Attributes are generally treated the same as properties. They can be represented by a <this.propertyName/> tag in the final page. The possible attribute values, which depend on the attribute-extension contents, are the same as the property values. It is recommended for components to use propertys instead of attributes.

The difference between a property and an attribute is that a property has corresponding get and set methods on the definition class. Attributes are instead set using the UIComponent.getAttributes() map. Putting a value into the attributes map will call any set methods if they exist. The functional problems that may occur by incorrectly declaring a property as an attribute or an attribute as a property are around the handling of null values returned from a load-time value binding. An attribute null value will be handled by calling getAttributes().remove(propertyName), while a property null value will be handled by calling getAttributes().put(propertyName, null). Both of those methods will throw a runtime exception if the property is incorrectly declared as being an attribute or not.

Attributes are not allowed on complex-type objects because they do not have an attributes map.

attribute-extension

ELEMENT attribute-extension ANY
Expected contents: same as in property-extension.

Present in attribute.

Lower Level Elements

Lower level elements generally only contain text, except for method-param. They are used within the other elements above.

allow-load-time-binding

ELEMENT allow-load-time-binding (#PCDATA)

This can be present in a property's property-extension or an attribute-extension (not in a property-type's property-extension). It is a boolean that defaults to true.

If true then the value of the property in a page can be a load time value binding. Load time value bindings are strings containing "${" and matching "}". They are converted to a value binding when the page is loaded, the value binding is then evaluated and the result is set as the value of the property.

If false then load time value bindings are not supported for this property. If a string in the form of a load time binding is used, it will cause a validation error.

For example:

allow-non-binding

ELEMENT allow-non-binding (#PCDATA)

This can be present in a property's property-extension or an attribute-extension (not in a property-type's property-extension). It is a boolean that defaults to true.

If true then the value of the property is not required to be a load time or runtime binding. The actual non-binding values allowed will depend on the property definition, but can include primitive values, or complex-type tags.

If false then only load time or runtime value bindings are allowed as the value(s) of this property. Which of those are allowed will depend on how the property defines allow-load-time-binding and allow-run-time-binding.

For example:

allow-run-time-binding

ELEMENT allow-run-time-binding (#PCDATA)

This can be present in a property's property-extension or an attribute-extension (not in a property-type's property-extension). It defaults to true in a property-extension, and it defaults to false in an attribute-extension.

If true then the value of the property in a page can be a runtime value binding. Runtime value bindings are strings containing "#{" and matching "}". They are converted to a javax.faces.el.ValueBinding when the page is loaded, and the value binding is set as the value of the property. The get* method for the property should then return the evaluated result of the value binding, to be used when rendering the page.

If false then runtime value bindings are not supported for this property. If a string in the form of a runtime binding is used, it will cause a design-time validation error.

For example:

collection-property

ELEMENT collection-property (#PCDATA)

When collection-property is present more than one value is allowed for the property, property-type or attribute. It can be present in a property-extension or an attribute-extension. There are 3 types of collection-property:

• using an add method.

  This is when collection-property and property-add-method are present in the attribute-extension or property's property-extension.
  

  property-item-class is supported. container-class is not supported. The property-class will be ignored.

  No java.util.Collection object will be created when loading the page. Instead each item in the collection will be individually set onto the object using repeated calls to the add method. The property-item-class should be the class of the single parameter to the add method.

  For example, the Panel control's "data" property allows multiple data sources:
  

    <property>
  

      <description>Control Data List</description>
  

      <display-name>Control Data</display-name>
  

      <property-name>data</property-name>
  

      <property-class>java.util.Collection</property-class>
  

      <property-extension>
  

        <collection-property>true</collection-property>
  

        <property-item-class>com.ibm.xsp.model.DataSource</property-item-class>
  

        <property-add-method>addData</property-add-method>
  

        <allow-run-time-binding>false</allow-run-time-binding>
  

        <designer-extension>
  

          <category>data</category>
  

        </designer-extension>
  

      </property-extension>
  

    </property>

  
  

• collection-property on composite-component or property-type definitions.
  

  When a property on a composite-component or a property-type definition contains collection-property it is not possible to supply a property-add-method. In that case the property-class must be or extend from java.util.Collection.
  

  property-item-class is supported. container-class is not supported (the property-class is used instead).

  The generated XPage .class file will attempt to create an instance of the property-class to save as the property value (or will use java.util.ArrayList if the property-class is Collection). Each item will be added to the collection using the add(Object) method.
  

• collections of property-types.

  This is when collection-property is present in a property-type's property-extension.
  

  container-class is supported but not required. property-item-class is not supported. property-add-method is not supported.

  Each item will be a property-type tag, so the item class will be com.ibm.xsp.binding.PropertyMap. The container-class defines the java.util.Collection class that will be used to store the items.

container-class

ELEMENT container-class (#PCDATA)

The container-class is a Java class that can be present in a property-type's property-extension when collection-property is also present.

It defines the container that the property-type instances will be placed in when they are stored in the parent composite-component or property-type.

The collection-property container-class must implement java.util.Collection. If not present it defaults to java.util.ArrayList.

For example:

localizable

ELEMENT localizable (#PCDATA)

A boolean indicating that this property is localizable and that its value in the page file should usually be replaced by a localized value from a resource bundle. It is only applicable when the property-class is java.lang.String or java.lang.Object. It defaults to false. For more details see the Extracted Values section in the Localization Options article.
For example,

method-binding-property

ELEMENT method-binding-property (#PCDATA)

A boolean used to indicate that this property is a method binding. It will usually be present if the property-class is a javax.faces.el.MethodBinding. It defaults to false. See also method-return-type and method-param.
For example,

If a method binding property should appear in the Events tab (like the XPage root control's "beforeRenderResponse" method binding appears), then it should supply a subcategory extension.
The most commonly used method binding property is the "action" property, available on Button and Event Handler controls, where the returned String is the name of the next page to navigate to.
A more complicated method binding property is the Edit Box "validator" property, which has parameters that may be used when validating the edit box value.
That property may be used in an XPage like so (XPage snippet):

method-param

ELEMENT method-param (method-param-name, method-param-class)

A method-param is defined in a property-extension when method-binding-property is present. It defines one of the parameters in the expected methods. The order of the method-params defines the expected ordering of the method's parameters.

For example:

method-param-name

ELEMENT method-param-name (#PCDATA)

The method-param-name is the name of a parameter to the method expected by this method binding property. This is part of a method-param which can be present in a property-extension when method-binding-property is also present.

For example:

method-param-class

ELEMENT method-param-class (#PCDATA)

The method-param-class is the Java class of a parameter to the method expected by this method binding property. This is part of a method-param which can be present in a property-extension when method-binding-property is also present.

For example:

method-return-type

ELEMENT method-return-type (#PCDATA)

This can be present in a property-extension when method-binding-property is also present. It references the Java class of the object to be returned from the method given as the value of this property in a page.
When the return type is a Java primitive or java.lang.String, then such values may be set as the value of the property in the XPage source. For example, the button action property has a method-return-type of String, so the Button action property may be a String, like so (XPage snippet):

If not present the return type defaults to void, returning nothing.

For example:

property-add-method

ELEMENT property-add-method (#PCDATA)

property-add-method can be present in a property-extension or an attribute-extension when collection-property is true. It references a method on the definition class, taking a parameter of the property-item-class type, that should be used to add individual items in the collection to the runtime object.

It is not supported in a property-type's property-extension.
See the example at collection-property, which contains the line:

property-class

ELEMENT property-class (#PCDATA)

The property-class is not the only thing that defines the type of value allowed for a property. See the property section for details of the different types of properties. The property-class cannot be javax.faces.component.UIComponent, or any subclass of UIComponent; if a named component is needed, use facets instead.
The property-class will be one of:

• a Java class, like
  

  <property-class>javax.faces.convert.Converter</property-class>

• a primitive, like
  

  <property-class>int</property-class>

  where the primitives are: char, byte, short, int, long, float, double, boolean, and string.
  Note, string is an alias for java.lang.String which is also treated as primitive.
  Generally only string, boolean, int and double are used.
• object, like
  

  <property-class>object</property-class>

  is an alias for java.lang.Object and is special because such properties allow any runtime value, though the format in the XPage file must be a String or value binding.
  If you intended a value to be some Object but you accidentally define it as a String, then even when the computed value in the page returns an Object, the runtime ValueBinding will use the property's expected type (String), and will convert the value returned to a String, so the ValueBinding will always return a String instead of an Object.
• an array, like
  

  <property-class>javax.faces.el.MethodBinding[]</property-class>

  Note [] is used to indicate an array. When the class is an array, the value can only be computed in the XPage (with one exception).

property-item-class

ELEMENT property-item-class (#PCDATA)

This can be present in a property-extension when collection-property is also present. The property-item-class is the Java class or interface that items in the collection must instantiate. If not present it defaults to java.lang.Object.

For example:

property-name

ELEMENT property-name (#PCDATA)

property-name is present in property and in property-type.

In a property it defines the property's name, which will appear in a runtime page as either an XML attribute or in a <this.propertyName/> tag.

In a property-type it both acts as the propertyName in the corresponding <this.propertyName/> tag, and it acts as the tag-name.

The property-name must uniquely identify its property or property-type amongst the container definition's other propertys, attributes and property-types.

For example:

required

ELEMENT required (#PCDATA)

A boolean, indicating that this property must be present in the design-time XPage. It defaults to false if not set. Note, that the design-time value may be a computed value that returns null, so the runtime code should still handle null values even when the property is marked as required. For example,

tag-attribute

ELEMENT tag-attribute (#PCDATA)

This should not be used, but is present in some of the XPages runtime xsp-config files for legacy reasons.
If false this indicates that this property will not correspond to an attribute or a <this.propertyName/> tag in a page file. The property or attribute declaration is then ignored. It is sometimes present if there is a get or set method for that property-name in the corresponding Java class.
For example,

Designer Extension elements

See the overview of designer-extension elements.

property designer-extension

found in
property-extension, attribute-extension
contains:

• category; see property category
• default-value; see designer-extension default-value
• editor
• editor-parameter
• event
• is-deprecated; see property is-deprecated
• styles-excluded
• subcategory
• validation-formula
• visible; see property visible

Also see description, display-name, icon.

property category

The property category is used in the XPages Editor in the Properties view, in the All Properties tab, where all of the properties are listed grouped into categories.
The property category extension is different from component category and from complex-type category.
Normally the property category is specified as one of the runtime category values, which are translated by the infrastructure instead of directly in the xsp-config file:
Where the category is not present:

• For a property on a composite-component (custom control) the default category is: custom
• For a property on a component the default category is: other.
• For a property on a complex-type definition, it is recommended not to supply a category. For uncategorized properties on a complex-type definition no default category is used. (The All Properties tab looks untidy when categories are supplied for properties on complex-type definitions.)

If you need to use a category that is not in the list above, you can use an untranslated category value like so:
or you can translate the category by using the %key% syntax used to translate the description and display-name, like so:
where the corresponding .properties file would contain:

designer-extension default-value

The designer-extension default-value is used at design-time when a control is dropped onto an XPage from the Controls palette, or when a complex-type instance is added using the "+" Add buttons in the All Properties tab of the XPages Editor.
For example, to create the following XPage:
1) Create a blank XPage and drag on a Repeat control from the Palette.
2) Select the XPage root control and in the All Properties tab, in the property named "properties" click the "+" Add button.
The XPage source will appear like so (XPage snippet):

In that case the repeat control has rows="30" because the rows property was defined with the designer-extension default-value "30". Likewise, the parameter complex-type was defined with the name property having the designer default-value "param" and with the value property having the designer default-value "val". [The repeat "id" property is controlled by the component extension generate-id.]

The designer-extension default value is the initial value in the XPage source when the tag is initially created. The person designing the page may change that value or may remove the entire attribute (e.g. removing the rows="30" above). So the presence of a default-value is not a guarantee that a value will be present at runtime; it is still necessary to handle the possibility of the value not being set. The default-value will be used as an attribute value in the created tag, so it can only be a String, primitive or computed value; it cannot have a complex-type tag as the value. There is no validation in the xsp-config parsing to verify that the default-value supplied is suitable for the property, so people using the extension should verify that the default-value works when used in an XPage. The designer-extension default-value is used in the Custom Control Property Definition tab, so that default value is a design-time default value.

There are other default value type extensions that may be confused with the designer-extension default-value. In this example:
The only value that would be read and used by XPages or by the Domino Designer tool is the value "some designer-extension default value". The default-value and suggested-value directly under the property element are suggested by the JSF faces-config.xml format, but are not used by XPages. The default-value directly under the property-extension will not be used by XPages. You may see that default-value in some xsp-config files because there is an old JSF tool for generating control classes from faces-config.xml files that uses that default value as the runtime default value (so it would generate: private String someName = "some property-extension default value";).

An example:

editor

The editor is used in the XPages Editor, in the Properties view, All Properties tab, to provide assistance in entering the property value. For example, if you select the XPages root control, go to the All Properties tab and click into the "style" property, you'll see a button with tooltip "Launch external property editor", and if you click on the button, you'll see a "Style Editor" dialog where you can choose the styles for the control. That is a StylesEditor (full name is below). If you click into the "viewState" property, you'll see a drop-down combo box control where you can choose one of the means of saving the view state. That is a comboParameterEditor with an associated editor-parameter.

Often the editor for a property is inferred from the property-class. For example, a boolean property will get a combo box with values "true" and "false". When the property-class corresponds to a complex-type tag, then the editor will allow you to create an instance of that complex-type tag. Or if the property-class corresponds to an abstract complex-type definition, then the editor will allow you to choose one of the tags that have that abstract definition as their base-complex-id.

The comboParameterEditor is used with the editor-parameter extension. It has the full ID:


When using the StyleClassEditor:

you may also need to use the styles-excluded extension.

To browse the full list of editors, create a Custom Control, and in the Properties view, Property Definition tab, click New Property. The "Editors:" combo box allows you to choose an editor for the new property, and the button beside that combo box gives more details on the editors. Once you've chosen an editor, you can copy the <editor> element from the custom control's xsp-config file. Open the Navigator view; in the menus Windows, Show Eclipse Views, Other..., General, Navigator. Then browse to myApp.nsf/CustomControl/custom1.xsp-config, scroll down to property_1 and copy the editor from there.

editor-parameter

The editor-parameter is a String value that may be used by the editor specified in the editor extension.

The only default editor that uses an editor-parameter is the comboParameterEditor.
The comboParameterEditor appears in the All Properties tab as a combo box containing the items listed in the editor-parameter. The combo box is also editable, so the user can type in any value they want (or they can type in any value in the XPage source tab either.) The comboParameterEditor assumes that the editor-parameter is a newline-separated or comma-separated list of items. It trims the white-space characters from each of the items. If the items contain a bar character (|) then the value before the bar is the value saved to the XPage source, while the value after the bar appears in the combo box drop-down list. If there is no "|" character then the item is used as both the saved value and as the label in the drop-down list.
It is not possible to translate the editor-parameter (issue logged as SPR#MKEE889GTU).

event

Indicates that this property is an event that should appear in the XPages Editor's Events view, where users can configure client-side (browser) and server-side scripts and simple actions to be executed when the event occurs. Please note, it implies the property supports a client-side or browser event; a property that is only a server-side event is indicated using method-binding-property.
For event properties you do not generally set the property value in the All Properties tab. For the XPages runtime controls provided by IBM, most support setting the property value to a single line of client JavaScript that will be written as an attribute value in the HTML output. Because it is a HTML attribute, the value should not contain new-line characters, double quotes or any non-attribute values. However if using Dojo Toolkit controls (using the "dojoType" property), then events configured in the All Properties tab will not generally be executed, as Dojo controls do not usually support event attributes. In that case the client JavaScript should be configured in the Events tab (which uses the Event Handler control), or using Dojo scripts (like type="dojo/method" scripts).
Event properties should also supply a subcategory extension. For example:

property is-deprecated

This indicates that a property should no longer be used and is considered deprecated or obsolete. Where the property is already used in an existing application, then application designers should consider reworking their application not to use the property.
For example, if you add a Button control to an XPage and then set some value for the "iconStyleClass" property in the All Properties tab, then a warning will appear in the XPage source and in the Problems view, with the message "The property iconStyleClass is deprecated and no longer supported."
To fix the iconStyleClass warning see the article on upgrading XPages from 8.5 to 8.5.1 This is different from the component is-deprecated extension.
For example:

styles-excluded

This is used with the StyleClassEditor editor (full editor ID below), to prevent that editor showing options for style values that would not apply for the current control.
For example, the List Box control "style" property is has styles-excluded:
So if you add a Button control to an XPage, then in the Properties view, select the Background tab, you'll see options to set the border color, border style and border width. If you add a List Box control to an XPage, then go to the Background tab, the border-related options are not present. The same occurs if you're clicking into the style property in the All Properties tab; the "Style Editor" dialog for a List Box doesn't have the border-related options.

The styles-excluded list is separated by commas (","), and each item in the list is trimmed.
For example, the Rich Text control "style" property has:

subcategory

The subcategory extension is used with the event extension and with method-binding-propertys. In the XPages Editor, Events view, the different events are listed categorized by the type of event. So there is a "Mouse" category, including the events "onmouseover" and "onmouseout", and there is a "Key" category, including "onkeyup" and "onkeydown". To add your event to one of the normal categories, specify one of these subcategory values:
If none of those are suitable, you should probably specify
that will create an event with the same name as the control, for example, the Panel control has an "onClientLoad" property marked as container-event, but in the Events tab the category appears as "Panel".
Other subcategories you'll see are "page-event", which was a category created just for the XPage root control, before the invention of the "container-event" generic subcategory. Also, if you add a data source to the XPage root control or to a Panel control, you'll see the "Data" category in the Events view, containing the method-binding-propertys listed on the data source complex-type definitions. Finally if you select the XPage root control, you'll see a "Components (receive)" category, which does not correspond to a property, but to the Platform Event Control, used when including XPages in Composite Applications.
If you invent your own subcategory name, then that category will appear in the Events view, but there is no mechanism to translate such invented categories for when Designer is running in a different language.

validation-formula

The validation formula for a property on a Custom Control (composite-component) may be set in the Custom Control editor, in the Property Definition tab of the Properties view. If you click the New Property button there, then on the right you can choose the Validation tab, where you can choose whether the value is required (setting the required element), and you can enter some JavaScript computation determining whether the value in the XPage source is considered valid (setting the validation-formula extension).
The validation-formula may also be set on components, not just on Custom Controls.
The validation computation supplied for the property is executed at design-time when that property is present on an instance of the control in an XPage. The validation-formula is only applied when the value in the XPage is some primitive (String or int, boolean, double etc), not when the value is computed or is a complex-type tag. The computation can access the current value of the property under the name "value", so it can be used when determining if the value is valid. The value will be available as a String, boolean or double, depending on the property-class.

For example, for a Custom Control named custom3, with a property named "var" with the validation formula:

In the xsp-config file corresponding to the custom control, that validation-formula element appears as:
If you use that "var" property in this XPage (XPage snippet):

Then in the XPage source and in the Problems view, errors will appear for the 2nd and 3rd custom control tags:

Also if you edit those property values in the All Properties or Custom Properties tabs, then when you click out of the "var" property, a "Validation Error" dialog will appear containing the same problem text.

There is an outstanding SPR (MKEE85RE9Z) asking for a way to configure the error message that appears in the Problems view and in the Validation Error dialog, but for now the workaround is to put a comment in the start of the validation formula explaining the problem with the property value and how to fix it. The error message uses the first 64 characters of the validation formula, so the example above includes some spaces after the initial comment, so that the dialog does not show the start of the if statement.

The validation formula also has access to the values of the other properties on the control tag instance, available through their property names. Again, only primitive values are available, and the property values are available as String, boolean or double values. So the validity of a control property can depend on the value of other properties on the same control tag. For example,


When providing a validation formula on a property that's part of a Group definiton (a property-type used on a composite-component), then the "parent" value is also available. When the group tag is in a this.propertyName tag directly under the control, then the parent represents the control. If the group tag is contained in another group tag, then the parent will be the container group tag, and you can refer to parent.parent.otherProperty to reference properties defined on the control.

The validation-formula is expected to return true or false, not to throw an Exception. If there is an exception or error in the JavaScript provided in the validation-formula, then that error will appear in the Problems view, instead of the expected error message. For example, with the formula

because it cannot resolve a property named "badPropName", the Problems view contains the Error:

To see the rest of that truncated exception message, in the menu Help, Support, View Trace, and scroll down to the end to see the stack trace.

property visible

The property visible extension is a JavaScript computation determining whether this property will be visible in the All Properties tab. Even where a property is not visible in the All Properties tab, it will still be possible to set that property in the XPage source, by typing in the property-name directly. This is similar to the validation-formula extension, which is used to determine whether a property value is considered valid. To avoid user confusion when properties appear and disappear in the All Properties tab, it may be better to use the validation-formula instead. The validation-formula section discusses the values available to the computation JavaScript; "value" refers to the current property value, and "otherProp" would refer to the primitive value of a different property on this control tag instance named "otherProp".
The property visible extension is different to the component visible extension.
An example: