ShowTable of Contents
Files with the .xsp-config extension are used to describe the controls that are available in the IBM Lotus Domino Designer tool. The information in the files is used in Designer to provide tooling support when editing the XPages XML files. For example, the xsp-config files list all the Controls that are present in the Controls palette, and if you select a control and view the Properties panel, the All Properties tab is populated by the lists of properties declared in the xsp-config files. The information in the xsp-config files is also used to build the .class file generated from each XPage XML file, so it needs to be accurate to prevent compile errors at design-time and to prevent ClassCastExceptions or other type related errors at runtime.
The xsp-config format is based on JSF's existing faces-config format, but the xsp-config files are only loaded at design-time in the Domino Designer tool and builders, rather than at runtime when the XPages are executing.
In this document most examples are from xsp-config files. The samples from the XPage source tab are marked with (XPage snippet).
This article is part of the XPages Extensibility API Developers Guide
The table of contents above describes the contents of this page, but there are 5 separate pages in this document.
- Overview and top-level elements
- Page 2, components, defining controls
- Page 3, property level elements, allowing properties
- Page 4, complex-types, non-control objects like converters and data sources
- Page 5, other definitions.
Throughout all the pages the following header sections are used, and all of these definitions are described:
Top Level Elements.
The 2 higher level elements contain the definition elements.
These 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.
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.
Lower Level Elements.
Lower level elements generally only contain text. These are used within the other level elements.
designer-extension elements and their contents.
Design-time only extensions used within the definition elements and property level elements.
Top Level Elements
The higher level elements contain the definition elements.
ELEMENT faces-config ((application | factory | component | converter | managed-bean | navigation-rule | referenced-bean | render-kit | lifecycle | validator | complex-type | composite-component | group | faces-config-extension )*)
This like the faces-config file format, but the following elements were added:
Many of the existing elements from the faces-config format are ignored, and should be provided in a faces-config file instead of in an xsp-config file.
definitions have a different function in the xsp-config file than in the faces-config file.
The new file format takes the place of a JSP Tag Library, in that it defines XML tag
tag-names and the
namespace-uri to which they are contributed.
It differs from Tag Libraries in that properties can be referenced from an existing
group definition, or inherited from a parent
It also provides other information that will be used when loading a page from a file. For example, the
property-extension gives more information on the expected value of a property, so that pages can be validated by the design-time builder.
ELEMENT faces-config-extension ANY
Also faces-config designer-extension
The faces-config-extension used to also contain an element "public" (<public>false</public>). You will see that in Custom Control xsp-config files from 8.5 and 8.5.1, but it is not useful in the Notes/Domino environment, and should not be added to your files. [It was left over from the Lotus Component Designer technology.]
Lower Level Elements
Lower level elements generally only contain text. These are used within the other elements above.
ELEMENT default-prefix (#PCDATA)
For example, the prefix "xc" is defined as:
xmlns prefix to act as a synonym for the
For example, the "
xp" here (XPage snippet):
ELEMENT namespace-uri (#PCDATA)
namespace-uri corresponds to the
xmlns namespace declarations at the top of every XPage, like so (XPage snippet).
XPage pages that use the controls and complex-types defined in a configuration file will need to reference the namespace defined in that file, so that the tags are resolved.
The XML format, which the XPage source is based on, suggests that tags can be namespaced by a uri, so that each person or company that provides tags can declare any URI to uniquely identifying that company, and so long as the URIs do not conflict, it allows tags with the same name but from different companies to be used in the same XML page.
In XPages, any tags that do not have a namespace, or are from a namespace that is not declared in a loaded XPage configuration file, will be treated as HTML, and passed through to the output HTML page. So the configuration files must have a namespace.
There is no "hard" compiler requirement that people use different namespaces, but it is advised to do so for a number of reasons. It provides disambiguation between identical tag-names from different sources. It means you don't accidentally override the XPages core tag names, which would lead to unexpected behaviors in applications using those tags. Some parts of the Designer tooling may expect control libraries to have different namespaces, leading to odd behaviors if they are the same.
The exception to the rule for uniqueness is the custom control namespace, which is the same in every custom control created by the Designer editor:
Since custom controls design element names are unique within the application where they are defined, that does not generally cause a problem. However if you are exporting a custom control, to share with other developers, it is best to change the
namespace-uri of that custom control to prevent conflicting with the names of custom controls defined in applications. You can rename the custom control namespace in the Properties view of the Custom Control editor.
namespace-uri is generally URL-like, but it is not resolved as a URL and there is no requirement that it should resolve. (People have been known to publish information about their tags at the namespace URL, at their own discretion.)
namespace-uri must be known for each xsp-config file. It is usually defined with the optional
It is normally present in the
faces-config-extension. Otherwise the
namespace-uri can be present in
component-extensions. In that case the first definition in the xsp-config file should declare the
namespace-uri (or they should all have the same
namespace-uri), and any initial definitions without a
namespace-uri will be ignored.
Designer Extension elements
The element <designer-extension> can be added to most -extension elements (component-extension, property-extension etc.).
The contents of the designer-extension will vary depending on the type of element it is used in,
for example, a designer-extension in a property-extension will have different contents than a designer-extension in a component-extension,
so each type of designer-extension will be discussed separately here.
The name "designer-extension" is left over from when the xsp-config files used to be parsed both in the server runtime and in the Designer editing tool. The extensions place directly in the <property-extension> or <component-extension> were needed for creating the page on the server at runtime, while the extensions placed in a <designer-extension> within the <property-extension> were only used in the Designer editing tool. The xsp-config files are now only used in Designer, so there is no longer any reason for a distinction between extensions in the property-extension and extensions in a property-extension's designer-extension.
The designer-extension element is always optional, but for some elements it would be unusual if it were absent; for example most property elements have a category designer-extension, used to group related properties together in the All Properties tab of the XPages Editor.
For most elements the Designer tool will read the elements:
<description>, <display-name>, <icon>
They are usually defined on the main element, like the <component> or <property> element, rather than nested in an component-extension or in a designer-extension.
are translated text with a description and label for the current element. You can provide them as untranslated text like:
<description>Disables the validators assigned to this control.</description>
<display-name>Disable Validators Flag</display-name>
They are translated like:
with the corresponding _en.properties file containing:
property.disableValidators.name= Disable Validators Flag
property.disableValidators.descr= Disables the validators assigned to this control.
There is a legacy JSF faces-config translation process, using <description xml:lang="fr"> which is not recommended, but if you already have files translated using that mechanism, it should work OK, choosing the correct description to match the Designer install locale.
The name format for the properties file corresponding to the xsp-config file depends both on the locale or language of the Designer install, and also depends on whether the xsp-config file is loaded from a library or within an NSF. In these examples, fr_BE is the locale "French (Belgium)".
When loading xsp-config files from within an NSF, it is assumed that translated custom controls will have files like:
|custom1.xsp||The XPage source of the custom control.|
|custom1.xsp-config||The XPages configuration file for the custom control.|
|The localized text from the XPage source of the custom control. |
(See the XPages localization options for details.)
|The localized text from the XPages configuration file for the custom control.|
When loading xsp-config files from a library, the translated .properties files for the configuration files do not contain xsp-config in the file names, like so:
The label reference mechanism.
|controls.xsp-config||The XPages configuration file for the controls in the library (may be one of many).|
|The localized text from the XPages configuration file.|
To reuse translations from an existing property translated in a different xsp-config file, that xsp-config file should have been loaded before this xsp-config file (depending on the order the xsp-config files are listed in your XspLibrary implementation), so you can use the label reference mechanism, like so:
or to reuse a definition translation it would be like so:
The references must begin with %/ and end with /name% or /descr%. To reference components, the component-type should be between the /s. Other definition references use the -id value, e.g. for complex-types use the complex-id.
, the values are like so:
The icons are resolved from the classpath of the XPages library contributing the xsp-config file, or are resolved as resources within the current NSF. By default the Controls palette will display the small icon, but if users right-click in the palette and choose "Use Large Icons" then the larger icons will be used.
If you need to localize the icons, use the JSF faces-config translation mechanism like <icon xml:lang="fr">.
Also see description, display-name, icon
The outer tag faces-config doesn't have <description>, <display-name>, <icon>, so unlike most other tags, those elements are read from the designer-extension.
At present this extension is not used in the Designer tool, so the description and display-name are not displayed anywhere.
<?xml version='1.0' encoding='UTF-8'?>
<display-name>Core tags in the Example Namespace</display-name>
<description>The core.xsp-config file contributing to the Example Namespace.</description>