ShowTable of Contents
Definition Elements
Definition elements define tags, abstract tag superclasses, or other named reference-able definitions. These are elements which contain other elements. Includes the -extension elements which allow any contents.
complex-type
ELEMENT complex-type (description*, display-name*, icon*, complex-id, complex-class, group-type-ref*, property*, complex-extension*)
The complex-type
element represents a tag that can be the value of a property
or an attribute
. The tag class will not be a control class, that is, it will not extend javax.faces.component.UIComponent
.
As an example, suppose you have a component
"mycomponent" with a property
:
<property>
<property-name>startData</property-name>
<property-class>com.example.Data</property-class>
</property>
corresponding to the method
void setStartData(Data data)
By default it would be possible to compute the value of the "startData" property, like so (XPage snippet):
<eg:mycomponent startData="#{javascript: new com.example.Data('Joe','m',25') }"/>
But you might also want to allow the startData property to have a tag value like so (XPage snippet):
<eg:mycomponent>
<eg:this.startData>
<eg:data name="Joe" >
</eg:this.startData>
</eg:mycomponent>
To allow the value of the property in the page to be a tag <eg:data>, you would define a complex-type
<complex-type>
<description>
Data used by the mycomponent control
</description>
<display-name>Data</display-name>
<complex-id>com.example.data</complex-id>
<complex-class>com.example.Data</complex-class>
<property>
<description>
Value to be saved to the name field
</description>
<display-name>Name</display-name>
<property-name>name</property-name>
<property-class>java.lang.String</property-class>
</property>
<complex-extension>
<tag-name>data</tag-name>
</complex-extension>
</complex-type>
The complex-class
should be the same as the "startData" property-class
, so that the complex-type
tag can be used in the "startData" property. Once the classes are the same the Designer editor in the All Properties tab will detect that that tag can be set as a value of the property.
The complex-id
is a String identifier, which can be used to refer to this complex definition. By convention they are prefixed like Java package names, to prevent conflicts with complex-type
s provided by other developers at other companies. The complex-id
s are referenced in base-complex-id
(used to build inheritance trees), and they are referenced in the label reference mechanism (used to reuse translated property names and descriptions in xsp-config files).
The complex-class
is the Java class of the object to be created. It must not be a control class; the class must not extend javax.faces.component.UIComponent
. The simplest implementations do not need to implement any interface. However, if it defines propertys then the decision must be made whether to support computed values for those properties. If not supporting computed values, then each property should set allow-run-time-binding
to false. If supporting computed values, then the complex-class should implement ValueBindingObject
. Also, without explicit handling, computed values give serialization errors when persistence (high-availability mode) is enabled on the server, so it should implement the interfaces StateHolder
and ComponentBindingObject
and follow the XPages-specific templates for computed value serialization.
The property
list identifies the different properties that may be set onto the tag in the XPage source, or in the All Properties tab. Each property should have a corresponding set method in the complex-class
.
The tag-name
specifies the name of the tag in the XPage source. It must be unique for this namespace. See namespace-uri
.
If you wanted to allow different possible tags as the value of the startData
property, then you would build an inheritance tree of complex-type
s, where the base of the tree has the same class as the property-class
, and the different tag implementations point to the base as their parent definition.
<complex-type>
<description>
Abstract Data definition (abstract because no tag-name)
</description>
<display-name>Data</display-name>
<complex-id>com.example.data</complex-id>
<complex-class>com.example.Data</complex-class>
</complex-type>
<complex-type>
<complex-id>com.example.personData</complex-id>
<complex-class>com.example.PersonData</complex-class>
<property>
<description>
Person's name
</description>
<display-name>Name</display-name>
<property-name>name</property-id>
<property-class>java.lang.String</property-class>
</property>
<complex-extension>
<tag-name>personData</tag-name>
<base-complex-id>com.example.data</base-complex-id>
</complex-extension>
</complex-type>
<complex-type>
<complex-id>com.example.officeData</complex-id>
<complex-class>com.example.OfficeData</complex-class>
<property>
<description>
Location of the office
</description>
<display-name>Location</display-name>
<property-name>location</property-name>
<property-class>java.lang.String</property-class>
</property>
<complex-extension>
<tag-name>locationData</tag-name>
<base-complex-id>com.example.data</base-complex-id>
</complex-extension>
</complex-type>
In this case the base definition "com.example.data" does not have a tag-name
, and cannot be used as a tag in the XPage source. It only provides a parent definition that the tag definitions can inherit from. The 2 tags which can actually be used in the XPage are defined with a base-complex-id
that names the parent definition. With that connection in place, when you edit the control property in the All Properties tab, both of those tags will listed as options to be set for the value of the "startData" property.
Any property
s defined on the base definition will be inherited by all the tag definitions, so that they are forced to publish that property on their tag. It is often preferable to instead declare any common propertys in a group
definition, so that individual tag definitions can choose whether to publish the property or not.
Many of the complex-types defined in the runtime are not part of a base-complex-type inheritance hierarchy (except for the implicit extension from the absolute base complex-type). However there are 5 different abstract complex-types which have multiple tags extending that base.
- The converter definitions all extend from the base converter.
- The validator definitions all extend from the base validator.
- The Simple Actions all extend from the base:
<base-complex-id>simpleActionInterface</base-complex-id>
- The Data Sources all extend from the base:
<base-complex-id>dataInterface</base-complex-id>
- The Resources (defined for the XPage root "resources" property) all extend from the base:
<base-complex-id>resource</base-complex-id>
An example complex-type definition is the "xp:parameter" definition, used in the XPage root "properties" property:
<complex-type>
<description>Parameter used to apply additional information ...</description>
<display-name>Parameter</display-name>
<complex-id>com.ibm.xsp.complex.parameter</complex-id>
<complex-class>com.ibm.xsp.complex.Parameter</complex-class>
<property>
<description>Name of the parameter</description>
<display-name>Name</display-name>
<property-name>name</property-name>
<property-class>java.lang.String</property-class>
<property-extension>
<required>true</required>
<allow-run-time-binding>true</allow-run-time-binding>
<designer-extension>
<default-value>param</default-value>
</designer-extension>
</property-extension>
</property>
<property>
<description>Value of the parameter</description>
<display-name>Parameter Value</display-name>
<property-name>value</property-name>
<property-class>java.lang.String</property-class>
<property-extension>
<required>true</required>
<allow-run-time-binding>true</allow-run-time-binding>
<designer-extension>
<default-value>val</default-value>
</designer-extension>
</property-extension>
</property>
<complex-extension>
<tag-name>parameter</tag-name>
</complex-extension>
</complex-type>
complex-extension
ELEMENT complex-extension ANY
Expected contents:
tag-name, base-complex-id, default-property
Also,
complex-type designer-extension.
Present in complex-type
.
converter
ELEMENT converter (description*, display-name*, icon*, (converter-id | converter-for-class), converter-class, group-type-ref*, attribute*, property*, converter-extension*)
This is as in the faces-config file format, except that converter-extension
was added, to allow metadata.
A converter is a complex-type whose parent defaults to the abstract definition with class javax.faces.convert.Converter
. It is possible to choose a different converter as the parent by including a base-converter-id in the converter-extension. The converter definitions are declared differently from other complex-type definitions for historical reasons; the old faces-config.xml file format allowed for converter and validator definitions, but it did not have the concept of a complex-type. The complex-type definitions were invented as an abstraction of converters, validators, and any other objects in an XPage that didn't correspond to a control.
Only converter
s with a converter-id
are parsed in the xsp-config file. Any converter
s with a converter-for-class
are ignored, as they should be registered in a runtime faces-config file, not the design-time xsp-config file.
The converter
s tags should use property
s rather than attribute
s, because the javax.faces.convert.Converter
interface does not include a map to store attributes. The only reason attributes are allowed is for backward compatibility with the faces-config.xml file format.
An example converter is the "xp:convertNumber" converter, used with the Edit Box "converter" property:
<converter>
<description>Converts a value to a number...</description>
<display-name>Number Converter</display-name>
<converter-id>javax.faces.Number</converter-id>
<converter-class>com.ibm.xsp.convert.NumberConverter</converter-class>
<group-type-ref>com.ibm.xsp.group.convertNumber.core</group-type-ref>
<!-- that group-type-ref includes the property: -->
<property>
<description>Specifies whether only the integer part...</description>
<display-name>Integer Only</display-name>
<property-name>integerOnly</property-name>
<property-class>boolean</property-class>
<property-extension>
<allow-run-time-binding>false</allow-run-time-binding>
</property-extension>
</property>
<!-- end property from group -->
<converter-extension>
<tag-name>convertNumber</tag-name>
</converter-extension>
</converter>
converter-extension
ELEMENT converter-extension ANY
Expected contents:
tag-name, base-converter-id, default-property
Also,
complex-type designer-extension.
Present in converter
.
validator
ELEMENT validator (description*, display-name*, icon*, validator-id, validator-class, group-type-ref*, attribute*, property*, validator-extension*)
This is as in the faces-config file format, except that validator-extension
was added, to allow metadata.
Similar to the converter definition, a validator is a complex-type whose parent defaults to the abstract definition with class javax.faces.validator.Validator
. It is possible to choose a different validator as the parent by including a base-validator-id in the validator-extension. The validator definitions are declared differently from other complex-type definitions for historical reasons; the old faces-config.xml file format allowed for converter and validator definitions, but it did not have the concept of a complex-type. The complex-type definitions were invented as an abstraction of converters, validators, and any other objects in an XPage that didn't correspond to a control.
<validator>
<description>Validates that double value lies within the specified range</description>
<display-name>Double Range Validator</display-name>
<validator-id>com.ibm.xsp.DoubleRange</validator-id>
<validator-class>com.ibm.xsp.validator.DoubleRangeValidatorEx2</validator-class>
<group-type-ref>com.ibm.xsp.validator.group.Validator</group-type-ref>
<property>
<description>Specifies the maximum value allowed in the associated control</description>
<display-name>Maximum</display-name>
<property-name>maximum</property-name>
<property-class>double</property-class>
</property>
<property>
<description>Specifies the minimum value allowed in the associated control</description>
<display-name>Minimum</display-name>
<property-name>minimum</property-name>
<property-class>double</property-class>
</property>
<validator-extension>
<tag-name>validateDoubleRange</tag-name>
</validator-extension>
</validator>
validator-extension
ELEMENT validator-extension ANY
Expected contents:
tag-name, base-validator-id, default-property
Also,
complex-type designer-extension.
Present in validator
.
Lower Level Elements
The lower level elements only contain text. These are used within the other elements above.
base-complex-id
ELEMENT base-complex-id (#PCDATA)
A complex-type
's base-complex-id
contains a reference to some other complex-type
's complex-id
. That complex-type
is treated as this complex-type
's parent. All property
s defined on the parent and ancestors are inherited by this complex-type
and can be used on its tag in a page. See definition inheritance trees.
For example:
<base-complex-id>simpleActionInterface</base-complex-id>
base-converter-id
ELEMENT base-converter-id (#PCDATA)
A converter
's base-converter-id
contains a reference to some other converter
's converter-id
. That converter
is treated as this converter
's parent. All property
s defined on the parent and ancestors are inherited by this converter
and can be used on its tag in a page. When the base-converter-id
is not present the parent will default to the abstract definition for the class javax.faces.convert.Converter
. See definition inheritance trees. Generally converters do not define a parent, as only one converter is needed for a given data type.
base-validator-id
ELEMENT base-validator-id (#PCDATA)
A validator
's base-validator-id
contains a reference to some other validator
's validator-id
. That validator
is treated as this validator
's parent. All property
s defined on the parent and ancestors are inherited by this validator
and can be used on its tag in a page. When the base-validator-id
is not present the parent will default to the abstract definition for the class javax.faces.validator.Validator
. See definition inheritance trees. Generally validators do not define a parent, as the implementations are usually encapsulated in a single class.
complex-class
ELEMENT complex-class (#PCDATA)
complex-class
is a complex-type
's Java class. It should not implement javax.faces.component.UIComponent
.
Usually it should be non-abstract class with a public zero-argument constructor. An instance of the class will be created for every tag of this complex-type
tag in the page.
If the tag-name
is absent, the class can be an interface or abstract class and there is no constructor requirement.
The simplest implementations do not need to implement any interface. However, if it defines propertys then the decision must be made whether to support computed values for those properties. If not supporting computed values, then each property should set allow-run-time-binding
to false. If supporting computed values, then the complex-class should implement ValueBindingObject
. Also, without explicit handling, computed values give serialization errors when persistence (high-availability mode) is enabled on the server, so it should implement the interfaces StateHolder
and ComponentBindingObject
and follow the XPages-specific templates for computed value serialization.
For example:
<complex-class>com.ibm.xsp.complex.Parameter</complex-class>
complex-id
ELEMENT complex-id (#PCDATA)
An identifier for this complex-type
that is unique across all the loaded configuration files. By convention complex-id
s are prefixed like Java package names, to prevent conflicts with complex-type
s provided by other developers at other companies.
The base-complex-id
references complex-id
, to build definition inheritance trees. They are also referenced in the label reference mechanism, used to reuse translated property names and descriptions in xsp-config files.
An identifier for this
complex-type
that is unique across all the loaded configuration files. By convention
complex-id
s are prefixed like Java package names, to prevent conflicts with
complex-type
s provided by other developers at other companies.
The base-complex-id
references complex-id
, to build definition inheritance trees. They are also referenced in the label reference mechanism, used to reuse translated property names and descriptions in xsp-config files.
For example:
<complex-id>com.ibm.xsp.complex.parameter</complex-id>
converter-id
ELEMENT converter-id (#PCDATA)
An identifier for this converter
that is unique across all the loaded configuration files. By convention converter-id
s are prefixed like Java package names, to prevent conflicts with converter
s provided by other developers at other companies.
The base-converter-id
references converter-id
, to build definition inheritance trees. They are also referenced in the label reference mechanism, used to reuse translated property names and descriptions in xsp-config files.
For example,
<converter-id>javax.faces.Number</converter-id>
default-property
ELEMENT default-property (#PCDATA)
The name of the property
to place child values in if they are not nested in a <this.propertyName/> tag.
It can be present in a complex-extension, a converter-extension, a validator-extension, or a property-type
's property-extension
.
For example, if a complex-type
palette
has a property named colors
, it might be represented in a page as (XPage snippet)
<eg:palette>
<eg:this.colors>
<eg:color name="red">
<eg:color name="green">
<eg:color name="blue">
</eg:this.colors>
</eg:palette>
but if
palette
's
complex-extension
contained
<default-property>colors</default-property>
then it could be represented like so, without the <eg:this.colors/> tag (XPage snippet):
<eg:palette>
<eg:color name="red">
<eg:color name="green">
<eg:color name="blue">
</eg:palette>
An example is the Action Group (used in the Events view), which uses the "actions" property as the default property:
<complex-type>
<description>Action Group action executes a group of simple actions...</description>
<display-name>Action Group</display-name>
<complex-id>com.ibm.xsp.actions.actionGroup</complex-id>
<complex-class>com.ibm.xsp.actions.ActionGroup</complex-class>
<property>
<description>Ordered list of simple actions to execute.</description>
<display-name>Actions</display-name>
<property-name>actions</property-name>
<property-class>java.util.List</property-class>
<property-extension>
<collection-property>true</collection-property>
<property-item-class>javax.faces.el.MethodBinding</property-item-class>
<method-binding-property>true</method-binding-property>
<property-add-method>addAction</property-add-method>
</property-extension>
</property>
<property>
<description>Condition which determines if the actions are executed...</description>
<display-name>Condition</display-name>
<property-name>condition</property-name>
<property-class>boolean</property-class>
</property>
<complex-extension>
<tag-name>actionGroup</tag-name>
<base-complex-id>simpleActionInterface</base-complex-id>
<default-property>actions</default-property>
</complex-extension>
</complex-type>
validator-id
ELEMENT validator-id (#PCDATA)
An identifier for this validator
that is unique across all the loaded configuration files. By convention validator-id
s are prefixed like Java package names, to prevent conflicts with validators
s provided by other developers at other companies.
The base-validator-id
references validator-id
, to build definition inheritance trees. They are also referenced in the label reference mechanism, used to reuse translated property names and descriptions in xsp-config files.
For example:
<validator-id>com.ibm.xsp.DoubleRange</validator-id>
.
.
The value should be translated. For example, this xsp-config snippet:
If the category begins and ends with %, then it will use the value between the % symbols as a key in the .properties file.
If the category does not begin and end with %, then the category is not translated and will appear the same in all locales.
At present the complex-type category is only used for complex-types that are simple actions, where the category is used in the Add Simple Action dialog.
The simple action categories are "Basic", "Document" and "Component", and those names are translated in the xsp-config files where the simple actions are defined.
The dialog also allows you to choose category "All", which shows all simple actions.
This is used by simple action declarations to indicate whether they should be used in the Client tab of the Events view or the Server tab, defaulting to the Server tab. There is only one possible value "client".