Definition Elements

Define tags, abstract tag superclasses, or other named reference-able definitions. These are elements which contain other elements. This page only discusses component definitions.

component

ELEMENT component (description*, display-name*, icon*, component-type, component-class, facet*, group-type-ref*, attribute*, property*, component-extension*)

The component element describes a control tag, or abstract tag parent. The definition format is similar to the component in the JSF faces-config format. Extra details are usually present in the component-extension. An example definition: The component-type and component-class are required. In the component-extension the tag-name will usually be necessary and the base-component-type is needed when this control extends some base definition.

Definition inheritance trees

The definition inheritance tree for the components is defined through the base-component-type extension. Inheritance trees are defined by controls and complex-types pointing to their parent or base definition, or else if no base is declared, then the default base is used. For controls, the default base is an abstract component definition with component-class javax.faces.component.UIComponent. For complex-types, the default base-complex-id points to a definition with complex-id com.ibm.xsp.BaseComplexType and class java.lang.Object. (The 2 definitions corresponding to the default base-validator-id and the default base-converter-id both use the default complex-type base definition as their parent.)

The inheritance tree means that property elements from the parent and ancestor definitions are implicitly defined on the current definition. In Designer the base properties will appear in the All Properties view for the control tag. In most cases it is not recommended to redefine a property from an ancestor definition in your control tag. Especially you should not define an overriding property with a different property-class, or anything that might provide compile-time or runtime type errors. There are some exceptions, for example if an ancestor property is not defined as localizable, but the tag property should be localizable, then it is OK to override the ancestor property.

The definition inheritance tree does not necessarily correspond to the Java class inheritance tree, but often where your control class is inheriting from an existing definition it may be useful to point to that definition as the parent, to inherit its property definitions. However if only some of the properties from the proposed parent apply to the current control, not all of them, then it is best not to declare that control as the parent. Instead it may be possible to reuse groups of properties using group-type-refs, or else copy/paste the property and use the label reference mechanism to reuse the property labels.

component-extension

ELEMENT component-extension ANY
Expected contents:
tag-name, base-component-type, component-family, renderer-type, namespace-uri, default-prefix
Also component designer-extension.

Present in component.

Property Level Elements

As well as the common property element, the component element may also contain multiple facet elements. Only components contain facets, they are not present in complex-type definitions.

facet

ELEMENT facet (description*, display-name*, icon*, facet-name, facet-extension*)

The facet declaration is not yet used by Designer (as of 8.5.2). It was intended to indicate which facet names will be used by the current control, so that the Designer tool might indicate that controls can be placed in that named area. However that functionality is currently achieved by placing an Editable Area control in the render-markup instead.

A facet's facet-name is used in a page as a key of a value placed in the <this.facets/> map.

For example (XPage snippet):

where the "column" control is declared with:

facet-extension

ELEMENT facet-extension ANY
Expected contents: (none)

Present in facet.

Lower Level Elements

These lower level elements only contain text. These are used within the other elements above.

base-component-type

ELEMENT base-component-type (#PCDATA)

This references the component-type of this component's base or parent component. Any property defined on the parent or ancestors can be set on this component's tag. It is usually present. When not present it defaults to the component definition for javax.faces.component.UIComponent. It can be used to build the component hierarchy, see definition inheritence trees for details.

component-class

ELEMENT component-class (#PCDATA)

This is as in the faces-config format.
It must be present and it must extend javax.faces.component.UIComponent. The component class must have a public constructor with no arguments, so that when the XPage is built to a generated .class file, that class can compile.

component-type

ELEMENT component-type (#PCDATA)

This is as in the faces-config format.
The component-type is a unique identifier for a component or composite-component. No two xsp-config files should contain components with the same component-type. Other components will refer to a component by the component-type when defining it as their parent using the base-component-type.

group-type-ref

ELEMENT group-type-ref (#PCDATA)

Present in components, complex-types, converters, validators, and groups.

The group-type-ref refers to group-type of some group. The effect is to include the propertys of that group into the container definition.

tag-name

ELEMENT tag-name (#PCDATA)

The name of the XML tag for this definition, to be used in a page. It is usually present in a -extension element.

This is necessary when defining an XML tag for a component , complex-type , validator or converter . For composite-components the composite-name is used instead.

Tag names are not always required. For example a definition without a tag can be used to represent an abstract superclass or interface, from which other definitions can inherit. Also group definitions never correspond to an XML tag, so they do not have a tag-name.

In the JSF reference implementation, the tag-name would be defined in a Tag Library but in XSP it is defined in the xsp-config file instead.

The tag-names, and composite-names should be unique per namespace-uri . For example, in the set of files with a common namespace you should not have a component with the same tag-name as a composite-component's composite-name .

A tag-name should not be the named "this", as that would conflict with the use of "this" as a prefix for property containment tags. The tag-name should not contain a dot (.), as it would be mis-identified as a render-kit tag. The recommendation is to only use the letters a-z and a-Z, to begin with a lower case letter and to capitalize the first letter of subsequent words in the tag name.

Designer Extension elements

See the overview of designer-extension elements.

definition designer-extension

types:

• component designer-extension
  
• complex-type designer-extension
  
• composite-component designer-extension
  

Also see description, display-name, icon.

component designer-extension

found in
component-extension, composite-extension
contains:

• category; see component category
  
• selected-event
  
• visible; see component visible
  
• in-palette
  
• generate-id
  
• render-markup
  
• is-deprecated; see component is-deprecated
  

Also see description, display-name, icon.

component category

Present in designer-extension in component-extension and in component-extension.
The component category is a non-translated string. It corresponds to the categories that appear in the Controls Palette of the XPages editor. The Designer editor does provide translations for two categories, "core" and "container". The component category is different from complex-type category and from property category.
For example:

selected-event

The property-name of the event property that is the most commonly used event for this control.
When the designing user adds the control to an XPage and selects the Events view in the lower center panel, the named event will be selected by default. The designing user can choose to select one of the other events instead, but it is best if the selected-event is the most commonly used event. When this is not configured, by default the first event in the first visible events category will be selected. (When running Designer in English, that is often the "onclick" event, since the Mouse category is the first events category, and the events are ordered alphabetically).

For example:

could refer to an "onchange" property like so:

component visible

Present in designer-extension in a component-extension or a component-extension.
This is different from the property visible extension.
It indicates that this control should not have a design-time visualization in the Design tab when added to an XPage. The control will still be selectable in the Outline view. An example is the Event Handler control, which is used by the Events view when you add an action to a control event.

in-palette

Present in designer-extension in a component-extension or a component-extension.
Indicates whether this control should appear in the main palette, or whether the application developing user must click on the "Other..." option to find the control in the "Create Control" dialog. Users may override this extension by changing the preferences in File, Preferences, Domino Designer, Palette.
The default value of this extension depends on whether the control is a composite-component or a regular component. The composite-components, corresponding to Custom Controls, appear in the palette by default, so you would set in-palette>false< to exclude them from the palette. The components, are only in the "Create Control" dialog by default, so you would set in-palette>true< to include them in the main palette.
For example:

or

generate-id

Present in designer-extension in a component-extension or a component-extension.
Determines whether an "id" is present in the design-time Source generated when a control is dragged from the palette. The "id" corresponds to the "Name:" property in the main tab of the Properties view in the XPages Editor. This is used with controls that have a different behavior depending on whether an "id" is present or not. For example, if you drag an edit box and a panel onto an XPage the source will be like so (XPage snippet):

The xp:inputText tag corresponding to the Edit Box is named "inputText1". The xp:panel (the Panel control) does not have an ID because it is configured with generate-id>false<. The Panel is configured like that because a Panel without an ID (and without a style/styleClass), will not output any DIV element to the browser, and will solely act as a server-side control, where it can be used to make data sources available to contained controls. That is the preferred default use of a panel, but the user may set an ID if they wish it to output a DIV element, for example if they wish to partial update the panel control when a button is clicked.
The default value of this extension depends on whether the control is a composite-component or a regular component. The composite-components, corresponding to Custom Controls, do not have an ID by default, since they have the same behavior as a panel (outputting a DIV if an ID is present), so you would set generate-id>true< to ensure that an ID was generate by default (though the user could manually remove the ID). The components will generate an ID by default, so that the ID is already set if the user needs to configure a partial update of the control, or if they need to programmatically retrieve the control by ID, so you would set generate-id>false< to avoid generating an ID when the control added to the XPage from the palette.
This option only controls the initial presence of the ID when dragged from the palette, users can always change the value of the ID, adding or removing it, or they can create control instances in the Source tab by typing in the control, or copy/pasting from existing control declarations.
For example:

or

render-markup

Present in designer-extension in component-extension or a component-extension.
Contains some escaped XPage markup used by the Design tab to provide the appearance of the control in the XPages Editor.
A full discussion of render-markup is in the article Native and Custom Control Custom Visualization Best Practices.
This corresponds to the "Design Definition" tab in the Custom Control editor.
The value is expected to correspond a chunk of XPage sourcce that will be used by Designer to render the control at design time. Any valid XSP tags can be used, including references to images.
Moreover, the markup can contain JavaScript snippets, wrapped within <% and %> pseudo tag. These snippets will be executed before the markup is rendered and can generate any markup. For example, the JavaScript code can evaluate property values, or loop against component properties. The JavaScript context gives access to the component's design time properties through the 'this' keyword. The JavaScript code cannot execute Java code, to prevent possible security problems (SPR#JQUL84YFLV).
For example, for a custom control with a property named "header", if you paste this into the Design Definition tab (XPage snippet):

then the renderer-markup will be like:

And the Design tab representation of a custom control instance will show the value set for the header property, and an Editable Area callback control.

component is-deprecated

Present in designer-extension in a component-extension or a component-extension.
This is different from the property is-deprecated extension.
Used to indicate that the control is obsolete and deprecated. When components marked as deprecated are used in an XPage, a warning appears in the Problems view, indicating that they should no longer be used. For example, if you go to the Source tab of an XPage and type in <xp:viewPager/>, and save the XPage, then the Problems view will contain the warning:
The tag xp:viewPager is deprecated and no longer supported.
(The xp:viewPager control was only used in the beta versions of 8.5.0, and has never been supported in a released version.)
When marking a control as deprecated, you should also provide documentation explaining why it is not used, and how XPages should be reworked to avoid using the deprecated control. (The new xp:pager control should be used instead of the old xp:viewPager control.)
For example: