Registering custom widgets using catalog files (deprecated)

Use a catalog file to register each custom widget and to specify the location of the various resources used by each widget.

Before you begin

Before you register a widget, you must create its iWidget definition and define its iScope. You do not need to create the full implementation for the widget. After you have registered the widget, you can complete the implementation and then update the server. You can register the widget in an existing catalog file or you can create one.

About this task

The following steps describe how to create a catalog file. If you are updating an existing catalog file, you can skip step 1 and step 2, depending on whether you are creating a category for your custom widget.

Procedure

If you are creating a catalog file, define the name of the catalog.
For example:
```
<catalog id="hello">
		<resource-type>Catalog</resource-type>
</catalog>
```
Tip: The catalog ID cannot contain spaces. The catalog file name must be in the following format: catalog_name_of_the_catalog_id.xml. For example, if you define a catalog ID to be <catalog id="hello"> , the catalog file name should be catalog_hello.xml.

If you want to create a category for your widget instead of using an existing one, define the category. Categories group related widgets. Users can choose to view widgets by category in the widget palette. For example:

<category name="Viewers">
		<title>
			<nls-string xml:lang="en">Viewers</nls-string>
		</title>
		<description>
			<nls-string xml:lang="en">Contains widgets that can display the files of common applications.</nls-string>
		</description>

Create the registration definition for your custom widget. For example:

<entry id="{com.ibm.bspace}documentViewer" unique-name="{com.ibm.bspace}documentViewer">
			<title>
				<nls-string xml:lang="en">Document</nls-string>
			</title>
			<description>
				<nls-string xml:lang="en">This widget displays a Microsoft Word document.</nls-string>
			</description>
...
			<shortDescription>
				<nls-string xml:lang="en">Document</nls-string>
			</shortDescription>
		</entry>

Within the definition, provide the location of the various resources used by the widget. For example:
```
<definition>endpoint://{com.ibm.bspace}bspaceCommonWidgetRootId/iWidget/widgets/htmlFragment/documentViewer_iWidget.xml</definition>
```
Use an endpoint notation.
To provide the location of resources used by the widget, you can use the following resources:
- definition, which defines the location of the widget definition.
- preview, which defines the location of the preview image displayed in the widget palette.
- icon, which defines the location of the icon image displayed in the widget palette.
- previewThumbnail, which defines the location of a thumbnail of the preview image.
- help, which defines the location of the documentation for the widget.

To create an endpoint file, use the following example.

<?xml version="1.0" encoding="UTF-8"?>
<!-- START NON-TRANSLATABLE -->
<tns:BusinessSpaceRegistry xmlns:tns="http://com.ibm.bspace/BusinessSpaceRegistry" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://com.ibm.bspace/BusinessSpaceRegistry BusinessSpaceRegistry.xsd ">

<tns:Endpoint>
<tns:id>{com.ibm.bspace}bspaceCommonWidgetRootId</tns:id>
<tns:type>{com.ibm.bspace}bspaceCommonWidgetRootId</tns:type>
<tns:version>1.0.0.0</tns:version>
<tns:url>/BusinessSpace/</tns:url>
<tns:description>Location of Business Space Common Widgets</tns:description>
</tns:Endpoint>

<tns:Endpoint>
<tns:id>{com.ibm.bspace}bspaceWidgetRootId</tns:id>
<tns:type>{com.ibm.bspace}bspaceWidgetRootId</tns:type>
<tns:version>1.0.0.0</tns:version>
<tns:url>/BusinessSpace/</tns:url>
<tns:description>Location of Business Space Widgets</tns:description>
</tns:Endpoint>

<tns:Endpoint>
<tns:id>{com.ibm.bspace}bspaceServerRootId</tns:id>
<tns:type>{com.ibm.bspace}bspaceServerRootId</tns:type>
<tns:version>1.0.0.0</tns:version>
<tns:url>/BusinessSpace/</tns:url>
<tns:description>Location of Business Space Server</tns:description>
</tns:Endpoint>

<tns:Endpoint>
<tns:id>{com.ibm.bspace}bspaceWidgetHelpRootId</tns:id>
<tns:type>{com.ibm.bspace}bspaceWidgetHelpRootId</tns:type>
<tns:version>1.0.0.0</tns:version>
<tns:url>/BusinessSpaceHelp/</tns:url>
<tns:description>Location of Business Space Widgets Help</tns:description>
</tns:Endpoint>
</tns:BusinessSpaceRegistry>
<!-- END NON-TRANSLATABLE -->

Create each service endpoint starting with <tns:Endpoint> with a unique ID (<tns:id>) and the URL for the new endpoint (<tns:url>). The type (<tns:type>) must have the same value as the ID (<tns:id>). You can change the name and description, for example, My team's insurance task list.

When adding endpoints in the file, pay attention to the following information:

<tns:id>: The ID can be any string but must be unique for all registered endpoints. Ensure that this ID is unique when you are adding additional endpoints.
<tns:type>: The type must have the same value as <tns:id>.
<tns:url>: For the service endpoint, if the URL is relative, then it is assumed that the REST service endpoint is co-located with the server. If the URL is relative, make sure the URL is same as the context root you deployed, but with beginning and end directory indications, for example, <tns:url>/BSpaceWidgetsWPS2/</tns:url>. If your endpoint is on a remote system, update this field with an absolute URL, but with an end directory indication.
<tns:description>: Type a meaningful description that further details the nature of the data set that this endpoint is working on. It could either be based on the cluster that is working on the data set or the nature of the data set, for example, insurance claim tasks or accounting data tasks.