How to use a Rhino NameRenderer

Table of Contents


Introduction

This document is a reference for SGI software engineers who will be using NameRenderers for Rhino applications. NameRenderer is a class that can generate a name that represents a particular Item. Many of the Rhino infrastructure components use a NameRenderer to display the name associated with an Item, including the ItemView, the ItemTable, the ResultView, and the TreeView. The NameRenderer gives the programmer the ability to define what name an Item should have, and have that name used everywhere that the Item's name is displayed.

There is one NameRenderer for each Category. The NameRenderer is responsible for monitoring the Category and generating names for any Items that listeners have expressed interest in.

For more information on NameRenderers in general, see the NameRenderer documentation API documentation.


Before you begin

Before you begin to create a NameRenderer for a particular Category, you need to understand the names and terms that the Rhino infrastructure uses in relation to Categories. See the The names of Categories on the client and on the server documentation for more information.

Specifying the NameRenderer to use for a Category

The HostContext keeps track of which NameRenderer to use for each Category. To specify a Category's NameRenderer, place the NAME_RENDERER resource in the Category's resource file. For example, to specify that the RhinoExampleCategory should use the "com.sgi.rhexamp.category.NameRenderer" class as its NameRenderer, the following entry would be made in /com/sgi/rhexamp/category/rhexampRhinoExampleCategoryP.properties:
com.sgi.rhexamp.category.rhexampRhinoExampleCategory.NameRenderer = com.sgi.rhexamp.category.NameRenderer
If this resource is not specified, then the HostContext creates a ResourceBasedNameRenderer object for the Category.

Using the ResourceBasedNameRenderer

The ResourceBasedNameRenderer is a subclass of NameRenderer that is used to display names if there is no NAME_RENDERER resource specified (see Specifying the NameRenderer to use for a Category). To use the ResourceBasedNameRenderer, you must place specific resources in the Category's resource file.

There are three resources to add to the Category's resource file:

  1. The "categoryName" resource, defined as <category name>.categoryName (see the CATEGORY documentation for more information). This resource should contain a string that will be used as the name of the Category.
  2. The "pluralCategoryName" resource, defined as <category name>.pluralCategoryName (see the CATEGORY_PLURAL documentation for more information). This resource should contain a string that will be used as the name of the Category in its plural form.
  3. The "nameAttr" resource, defined as <category name>.nameAttr (see the NAME documentation for more information). This resource should contain the name of the Item's Attribute whose value will be used as the name of the Item.
As an example of these resource, the RhinoExample Category contains the following entries in its resource file:
${RHINO_EXAMPLE_CATEGORY}.categoryName = Rhino Example
${RHINO_EXAMPLE_CATEGORY}.pluralCategoryName = Rhino Examples
${RHINO_EXAMPLE_CATEGORY}.nameAttr = name
In this example, the name of the Category will be "Rhino Example", the plural name of the Category will be "Rhino Examples", and the name of the Item will be the contents of the "name" Attribute of the Item.

In addition to the three resources listed above, there are three more resources that control the way that the ResourceBasedNameRenderer works. These resources differ from the ones above in that they are not specific to a particular Category. It is expected that this resource will be common to all NameRenderers, and there are default values in the rhino tree. It is possible to override these resources in a product's PackageP.properties file, or individually in a specific Category's resource file.

  1. The ItemAndCategoryFormat (see the ITEM_NAME_FORMAT documentation for more information). This resource gives the FormatString which will be used to combine the Category name and the Item name. {0} will be replaced by the Item name, {1} by the Category name. This is used in several UI components to display the name of the Item (for example: "Cluster c1").
  2. The ItemView.titleFormatString (see the IV_TITLE_FORMAT documentation for more information). This resource gives the FormatString which will be used to combine the name of the Item, the name of the Category, and the name of the server into a single string. The name of the Item will be substituted in {0}, the name of the Category in {1}, and the name of the host that the GUI is connected to in {2}.
  3. The ItemTable.titleFormatString (see the IT_TITLE_FORMAT documentation for more information). This resource gives the FormatString which will be used to combine the name of the Category and the name of the server into a single string. The name of the Category will be substituted in {0} and the name of the host that the GUI is connected to in {1}.
For example, the default values for these properties, as defined in SysadmUIP.properties, are as follows:
A: ItemAndCategoryFormat = {1} {0}
B: ItemView.titleFormatString={1} {0} (on {2})
C: ItemTable.titleFormatString={0} (on {1})

Using a subclass of NameRenderer

To provide complete control of the name that is used for an Item, it is also possible to subclass the NameRenderer class and provide the necessary Java code for rendering names. See the NameRenderer documentation for more information. It is also possible to subclass the ResourceBasedNameRenderer to add to the existing functionality of the ResourceBasedNameRenderer.