ShowTable of Contents
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:
<component>
<description>A control that links to a different page ...</description>
<display-name>Link</display-name>
<component-type>com.ibm.xsp.OutputLink</component-type>
<component-class>com.ibm.xsp.component.xp.XspOutputLink</component-class>
<group-type-ref>com.ibm.xsp.group.focus</group-type-ref>
<group-type-ref>com.ibm.xsp.group.i18n</group-type-ref>
<group-type-ref>com.ibm.xsp.group.text.escape</group-type-ref>
<property>
<description>Indicates the name of the frame ...</description>
<display-name>Target Frame</display-name>
<property-name>target</property-name>
<property-class>java.lang.String</property-class>
</property>
<component-extension>
<base-component-type>com.ibm.xsp.UIOutputLink</base-component-type>
<renderer-type>com.ibm.xsp.LinkEx</renderer-type>
<tag-name>link</tag-name>
<designer-extension>
<category>core</category>
<selected-event>onclick</selected-event>
</designer-extension>
</component-extension>
</component>
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-type
s 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):
<xp:column>
<xp:this.facets>
<xp:text xp:key="header"/>
<xp:text xp:key="footer"/>
</xp:this.facets>
</xp:column>
where the "column" control is declared with:
<facet>
<facet-name>header</facet-name>
</facet>
<facet>
<facet-name>footer</facet-name>
</facet>
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 component
s with the same component-type
. Other component
s 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 component
s, complex-type
s, converter
s, validator
s, and group
s.
The group-type-ref refers to group-type
of some group
. The effect is to include the property
s 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-component
s 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-name
s, and composite-name
s 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:
Also see
description, display-name, icon.
component designer-extension
found in
component-extension,
composite-extension
contains:
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:
<component-extension>
<tag-name>button</tag-name>
<designer-extension>
<category>core</category>
</designer-extension>
</component-extension>
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:
<component-extension>
<designer-extension>
<selected-event>onchange</selected-event>
</designer-extension>
</component-extension>
could refer to an "onchange" property like so:
<property>
<description>JavaScript code executed when ...</description>
<display-name>Input Change Script</display-name>
<property-name>onchange</property-name>
<property-class>java.lang.String</property-class>
<property-extension>
<pass-through>true</pass-through>
<designer-extension>
<category>events</category>
<event>true</event>
<subcategory>change-event</subcategory>
</designer-extension>
</property-extension>
</property>
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.
<component-extension>
<tag-name>eventHandler</tag-name>
<designer-extension>
<visible>false</visible>
</designer-extension>
</component-extension>
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:
<component-extension>
<tag-name>outline</tag-name>
<designer-extension>
<in-palette>true</in-palette>
<category>Porus</category>
</designer-extension>
</component-extension>
or
<composite-extension>
<designer-extension>
<in-palette>false</in-palette>
</designer-extension>
</composite-extension>
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):
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:inputText id="inputText1"></xp:inputText>
<xp:panel></xp:panel>
</xp:view>
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:
<component-extension>
<tag-name>panel</tag-name>
<designer-extension>
<generate-id>false</generate-id>
</designer-extension>
</component-extension>
or
<composite-extension>
<tag-name>custom1</tag-name>
<designer-extension>
<generate-id>true</generate-id>
</designer-extension>
</composite-extension>
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):
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
---<xp:br></xp:br>
<xp:text
value="<%=
this.header?this.header:'{header}'
%>"></xp:text>
<xp:br></xp:br>
<xp:callback id="childrenArea">
<xp:br></xp:br>
</xp:callback>
<xp:br></xp:br>
---
</xp:view>
then the renderer-markup will be like:
<composite-extension>
<designer-extension>
<render-markup><?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
---<xp:br></xp:br>
<xp:text value="<%=
this.header?this.header:'{header}'
%>"></xp:text>
<xp:br></xp:br>
<xp:callback id="childrenArea">
<xp:br></xp:br>
</xp:callback>
<xp:br></xp:br>
---
</xp:view></render-markup>
</designer-extension>
</composite-extension>
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:
<component-extension>
<tag-name>viewPager</tag-name>
<designer-extension>
<is-deprecated>true</is-deprecated>
</designer-extension>
</component-extension>