Using an extension point to override design time tooling for Core and Extension Library controls

An extension point is provided to let you override design time tooling for the Core and Extension Library controls that are shipped with Designer.

The extension point com.ibm.designer.domino.xsp.editor.componentOverride is provided to let you override design time tooling for the Core and Extension Library controls that are shipped with Designer.

You should only contribute one extension per control using this extension point. This lets you override the palette entry for a control, add your own drop wizard, or add a control properties panel.

The following sections provide more details on extension point com.ibm.designer.domino.xsp.editor.componentOverride.

Syntax

<!ELEMENT extension (components+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED
>

Description: A universal extension point that is used to override the tooling for XPages shipped controls.

Details:

point - a fully qualified identifier of the target extension point
id - an optional identifier of the extension instance
name - an optional name of the extension instance

Syntax

<!ELEMENT components (component+)>

<!ATTLIST components

schemaUri     CDATA #REQUIRED

panelsFactory CDATA #IMPLIED
>

Description: A Container element that defines the design time override support for a particular schemaUri.

Details:

schemaUri - The schema URI that applies to the group of controls where tooling is being overridden. This property MUST correspond exactly to the namespace URI used for the same controls in the XPages registry.
panelsFactory - A fully qualified name of a class that implements com.ibm.designer.domino.xsp.api.panels.IPanelsFactory. Clients are advised to extend com.ibm.designer.domino.xsp.api.panels.AbstractPanelsFactory rather than implementing the interface above. This is the default factory for a whole group of controls, individual controls may override this factory to provide custom behavior. The panelsFactory class is responsible for generating panel Class objects based on the ids provided in the panels selection of this extension point.

Syntax

<!ELEMENT component (paletteItem? , panels?)>

<!ATTLIST component

tagName       CDATA #REQUIRED

panelsFactory CDATA #IMPLIED
>

Description: Design time override support of an individual XPages control. Each component will typically have a paletteItem item associated with it.

Details:

tagName - The tag Name associated with this component. Note : the schemaUri is defined in the components element that encloses it. The tag name is the XML local name of the tag, e.g. 'inputText'.
panelsFactory - A fully qualified name of a class that implements com.ibm.designer.domino.xsp.api.panels.IPanelsFactory. Clients are advised to extend com.ibm.designer.domino.xsp.api.panels.AbstractPanelsFactory rather than implementing the interface above. Typically the factory is defined in the components item, but the factory may be overwritten at the individual control level, though this is rarely necessary. The panelsFactory class is responsible for generating panel Class objects based on the ids provided in the panels selection of this extension point.

Syntax

<!ELEMENT paletteItem EMPTY>

<!ATTLIST paletteItem

label       CDATA #IMPLIED

iconSmall   CDATA #IMPLIED

iconLarge   CDATA #IMPLIED

visible     (true | false)

description CDATA #IMPLIED

action      CDATA #IMPLIED
>

Description: Palette Item override information about the enclosed component.

Details:

label - A short label that describes the control. This label will appear in the Controls Palette so it should be descriptive enough to inform users of the use of the control.
iconSmall - The path to the small icon for the Controls Palette item. Note that to override the existing icon you must specify both the large and small icons.
iconLarge - The path to the large icon for the Controls Palette item. Note that to override the existing icon you must specify both the large and small icons.
visible - A boolean flag denoting whether this Controls Palette item is visible.
description - A short description to be used as the tooltip for the Controls Palette item.
action - A fully qualified name of an action class that extends com.ibm.designer.domino.xsp.api.palette.XPagesPaletteDropActionDelegate. Clients wishing to provide custom drop actions for shipped controls must specify this.

Syntax

<!ELEMENT panels (panel+)>

Description: List of panel elements for the enclosed component element

Syntax

<!ELEMENT panel EMPTY>

<!ATTLIST panel

title     CDATA #REQUIRED

id        CDATA #REQUIRED

indented  (true | false)

lazyInit  (true | false)

icon      CDATA #IMPLIED

contextId CDATA #IMPLIED

>

Details for panel elements:

title - The title that appears in the attribute view for this panel ( translatable ).
id - A unique id for the current panel. IDs may be reused across controls, e.g., if two controls use the same "font" panel then both definitions will reuse the same ID. The ID in turn is provided to the factory defined in the panelsFactory attribute of the 'component' above. The factory must resolve the ID to a Class.
indented - The attribute that defines whether or not the panel should be indented
lazyInit - The attribute that defines whether or not the specified panel should always be initialized or only initialized when it is about to become visible
icon - The icon that is to be used in conjunction with this property panel tab. The path should be relative to the current plugin.
contextId - A fully qualified context id that is used to display help for the property panel.

Example

This code provides an example of how to use this extension point:

<extension point="com.ibm.designer.domino.xsp.editor.componentOverride">

    <!-- Define the namespace URI for the controls were overriding -->
    <components schemaUri="http://www.ibm.com/xsp/core">

        <!-- Override the tooling for a particular control, in this case viewPanel -->
        <component tagName="viewPanel"
         panelsFactory="com.myco.override.PanelsFactory">

            <!-- Override the palette entry for the control -->
            <paletteItem label="View Panel Override" 
             iconSmall="icons/palette/vp_small.gif"  
             iconLarge="icons/palette/vp_large.gif"
             description="Overridden View Panel"
             visible="true"
             action="com.myco.override.viewPanelDropAction"/>

            <!-- Add a new property panel for the control -->
             <panels>
                 <panel icon="icons/panel/vp_panel.gif" 
                  id="com.myco.override.newpanel" 
                  indented="true" 
                  title="New Panel">
                 </panel>
             </panels>

        </component>

    </components>

</extension>

Additional details

API Information - If you are interested in creating custom tooling for existing XPage controls, you must implement the APIs corresponding to this extension point. It is strongly advised that you extend the default implementation rather than re-implementing the interfaces entirely from scratch.

Supplied Implementation - com.ibm.designer.domino.xsp.api.palette.XPagesPaletteDropActionDelegate is the default drop action delegate for all palette drop actions. Controls use this action by default if not overridden by the component extension. You can override individual parts of the paletteItem, but if you wish to override an existing property panel for a shipped control, then you must override it in its entirety. You can also hide an existing property panel for a shipped control by contributing a panel with the same id and returning null for the panel in the getPanelControlClass function in the Panels Factory.