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-types provided by other developers at other companies. The complex-ids 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-types, 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 propertys 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.

1. The converter definitions all extend from the base converter.
2. The validator definitions all extend from the base validator.
3. The Simple Actions all extend from the base:
   

   <base-complex-id>simpleActionInterface</base-complex-id>

4. The Data Sources all extend from the base:
   

   <base-complex-id>dataInterface</base-complex-id>

5. The Resources (defined for the XPage root "resources" property) all extend from the base:
   

   <base-complex-id>resource</base-complex-id>

<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>

Present in complex-type.

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 converters with a converter-id are parsed in the xsp-config file. Any converters 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 converters tags should use propertys rather than attributes, 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.

<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>

Present in converter.

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>

Present in validator.

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 propertys 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>

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 propertys 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.

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 propertys 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 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.

<complex-class>com.ibm.xsp.complex.Parameter</complex-class>

An identifier for this complex-type that is unique across all the loaded configuration files. By convention complex-ids are prefixed like Java package names, to prevent conflicts with complex-types 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.

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.

<complex-id>com.ibm.xsp.complex.parameter</complex-id>

An identifier for this converter that is unique across all the loaded configuration files. By convention converter-ids are prefixed like Java package names, to prevent conflicts with converters 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.

<converter-id>javax.faces.Number</converter-id>

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>

<default-property>colors</default-property>

<eg:palette>

    <eg:color name="red">

    <eg:color name="green">

    <eg:color name="blue">

</eg:palette>

<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>

An identifier for this validator that is unique across all the loaded configuration files. By convention validator-ids are prefixed like Java package names, to prevent conflicts with validatorss 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.

<validator-id>com.ibm.xsp.DoubleRange</validator-id>