| Icon | Shown in the upper left corner of the ItemView. Typically, the Icon represents the type of Item being viewed, and additionally the state of the Item |
| Fields | Shown in the upper right corner of the ItemView. This section is divided into two columns, the left for the name of the field, and the right for the value of the field. The fields section is designed to show information about the Item that can be represented by fairly short Strings |
| Additional Info section | This section occupies the center of the ItemView. It is an optional section. This section is designed to show information about the Item that can't easily be represented as a single line of text. Examples include ItemTables, graphs, or additional icons. Any Java component can be shown here. If there are no components to show in this section, then the ItemView will not show the Additional Info section. |
| TaskShelf section | This section occupies the bottom of the ItemView. It shows a TaskShelf containing Tasks that can operate on the displayed Item in the Item's current state |
While in the early stages of writing Categories, it may be desirable
to show an ItemView that shows all of the Attributes of an Item. The ItemView
supports this idea by means of a "no-code" ItemView. This version of an
ItemView is not designed for use in a shipping Rhino application, but can
be of great assistance while investigating the Rhino Infrastructure or
for giving preliminary demos. No code or resource files need to be written
to use the "no-code" ItemView - it can be launched as soon the server side
Categories have been written and the Rhino infrastructure has been installed
on the client. To turn the ItemView into a shippable ItemView, it is necessary
to provide resources that describe the way that the Attributes of the
Item are to be displayed. The rest of this document will describe how
to accomplish this. To launch a "no-code" ItemView, follow the
instructions in the section titled How to launch
ItemViews. An example of the "no-code" ItemView for the
RhinoExampleCategory is shown to the right.
Before writing any code or resource files for the ItemView, begin by analyzing the information that needs to be displayed. Divide the information into two groups: information that will go in the Fields section, and information that will go in the Additional Information section. While there are no absolute rules about what kind of information goes where, here are some suggestions on how to divide the information:
A: com.sgi.rhexamp.category.rhexampRhinoExampleCategory.ItemView.field0=name B: com.sgi.rhexamp.category.rhexampRhinoExampleCategory.ItemView.field1=type C: com.sgi.rhexamp.category.rhexampRhinoExampleCategory.ItemView.field2=modeBecause the first part of each line is identical, it is common to use macros to shorten the lines of the resource file and to make the file easier to read. An example of the same resources using macros is shown below.
A: RHINO_EXAMPLE_CATEGORY=com.sgi.rhexamp.category.rhexampRhinoExampleCategory
B: IVprefix=${RHINO_EXAMPLE_CATEGORY}.ItemView
C:
D: ${IVprefix}.field0=name
E: ${IVprefix}.field1=type
F: ${IVprefix}.field2=mode
The three "field" resources (D - F) define the names of the fields and the order in which the fields will be displayed in the ItemView. In this example, the names of the fields correspond exactly with the names of the Attributes in the Item that will be displayed in the field. By naming the fields in this manner, the ItemView can use default behavior and automatically associate the correct Attribute with the field. It is also possible to give the fields names that are not the same as the names of Attributes. In that case, it may be necessary to use the "basedOn" property (defined below) to tell the ItemView which Attribute is associated with a field.
Running an ItemView with the 5 lines described above in the
resource file will result in an ItemView that is shown on the right.
Notice that the order of the fields is "name", "type", and then
"node", which is as specified in the resource file. ItemView has used
a default label for each of the fields. Information about how to
customize the label is described below. The ItemView is using the
default "toString" method (methods are described below). This is the
simplest method, and uses the results of calling Java's toString
method on the value of the Attribute.
If a field is given a name that does not correspond to the name of an Attribute, the "basedOn" property is used to tell the ItemView which Attribute the field represents. The "basedOn" resources are defined as: <Category name>.ItemView.basedOn.<field>, where <Category name> is the name of the Category, and <field> is the name of a field. (See the BASED_ON documentation for more info).
The renderer method (as described below) does not require that the field be associated with a particular Attribute. When using this method, it is not necessary to specify the "basedOn" property even if the name of the field does not correspond to an Attribute. All the other methods, including the default "toString" method, require that the field be associated with a particular Attribute of the Item.
For example, suppose that the "name" Attribute should be displayed twice, once at the beginning of the list, and once at the end. A resource file as follows would do just that:
A: RHINO_EXAMPLE_CATEGORY=com.sgi.rhexamp.category.rhexampRhinoExampleCategory
B: IVprefix=${RHINO_EXAMPLE_CATEGORY}.ItemView
C:
D: ${IVprefix}.field0=Name1
E: ${IVprefix}.field1=type
F: ${IVprefix}.field2=node
G: ${IVprefix}.field3=Name2
H:
I: ${IVprefix}.basedOn.Name1=name
J: ${IVprefix}.basedOn.Name2=name
This would result is the name being shown twice, as is seen to the right:
The next step is to define the strings that will be used as the labels for the fields. The "label" resources are defined as: <Category name>.ItemView.label.<field>.label. (See the LABEL documentation for more info). Optionally, another resource can be specified that gives the name of a glossary entry that will be displayed if the user clicks on the label. This resource is defined as: <Category name>.ItemView.label.<field>.glossary, and if this resource is defined, then the label will appear blue.
For example, define labels for the example ItemView, the following properties would be added to the resource file:
A: RHINO_EXAMPLE_CATEGORY=com.sgi.rhexamp.category.rhexampRhinoExampleCategory
B: IVprefix=${RHINO_EXAMPLE_CATEGORY}.ItemView
C:
D: ${IVprefix}.field0=name
E: ${IVprefix}.field1=type
F: ${IVprefix}.field2=mode
G:
H: ${IVprefix}.label.name.label=Name:
I: ${IVprefix}.label.type.label=Type:
J: ${IVprefix}.label.type.glossary=glossary.Type
K: ${IVprefix}.label.mode.label=Access:
L:
M: glossary.Type = The type of the Item
Displaying the ItemView now shows that the desired labels are
displayed. Notice that the "type" label is displayed as a link, and
the picture shows the glossary window that results when the user
clicks on the link.
The next step is to choose what method the ItemView should use to display the field. (In this usage, "method" does not refer to a Java method, but rather to the typical English definition of the word) The "method" resource controls this, and is defined as: <Category name>.ItemView.method.<field> (see the METHOD documentation for more info). Four methods are available:
${IVprefix}.method.name=toString
A: ${IVprefix}.method.type=lookup
B:
C: ${IVprefix}.lookup.type.Printer=Impresora
D: ${IVprefix}.lookup.type.Clock=Reloj
E: ${IVprefix}.lookup.type.NetscapeExecutable=Netscape
In this case, the type of the Item will be displayed in it's Spanish equivalent:
A: ${IVprefix}.field3=server
B: ${IVprefix}.label.server=Server:
C:
D: ${IVprefix}.method.server=richText
E: ${IVprefix}.selector.server=server_selector
F: ${IVprefix}.category.server=rhexampServerCategory
For example, to use the string "(Desconocido)" (Spanish for "Unknown") if the "type" Attribute is missing from the Item, add the following resource:
A: ${IVprefix}.method.type=lookup
B:
C: ${IVprefix}.lookup.type.Printer=Impresora
D: ${IVprefix}.lookup.type.Clock=Reloj
E: ${IVprefix}.lookup.type.NetscapeExecutable=Netscape
F: ${IVprefix}.missing.type=(Desconocido)
A: ${IVprefix}.fieldRenderer=${RHINO_EXAMPLE_CATEGORY}Renderers
If a field uses the renderer method, but no
ItemViewFieldRenderer is defined with the "fieldRenderer" property,
then the ItemView will attempt to load a class with the name
<Category Name>FieldRenderer. For example, for the
RhinoExampleCategory, it would attempt to load the class
com.sgi.rhexamp.category.rhexampRhinoExampleCategoryFieldRenderer.
If the "fieldRenderer" resource is not specified and the
<Category Name>FieldRenderer class is not found, then
ItemView will throw an assertion.
The ItemViewFieldRenderer has five methods that must be implemented. See the documentation for ItemViewFieldRenderer about the specifics of each method.
A: ${IVprefix}.additionalInfoRenderer=${RHINO_EXAMPLE_CATEGORY}Renderers
If no ItemViewAdditionalInfoRenderer is defined with the "additionalInfoRenderer" property,
then the ItemView will attempt to load a class with the name
<Category Name>AdditionalInfoRenderer. For example, for the
rhinoExampleCategory, it would attempt to load the class
com.sgi.rhexamp.category.rhexampRhinoExampleCategoryAdditionalInfoRenderer.
If the "addtionalInfoRenderer" resource is not specified and the
<Category Name>AdditionalInfoRenderer class is not found, then
ItemView will not display anything in the "Additional Information" section.
The API for the ItemViewAdditionalInfoRenderer is almost identical to that of the ItemViewFieldRenderer. In this case, there are four methods that must be implemented:
%> java com.sgi.sysadm.manager.RunItemView <package qualified Category name> <Item selector>
For example, to launch an ItemView of the Item "foo" in Category "BarCategory", where the ItemView's resource file is in com/sgi/myProduct/category (relative to classpath), type:
%> java com.sgi.sysadm.manager.RunItemView com.sgi.myProduct.category.BarCategory foo
To launch a "no-code" ItemView, pass the Category selector instead of the fully qualified name:
%> java com.sgi.sysadm.manager.RunItemView BarCategory foo
A "no-code" ItemView will also be displayed if no resources corresponding to the Category are found.
To programmatically launch an ItemView, use one of two methods: To launch an ItemView in a new frame (called an ItemViewFrame), use the launchItemViewFrame method in ItemViewFrame. The launchItemViewFrame method takes a ItemViewLaunchRequestEvent, which encapsulates all the information about which ItemView to launch. For example:
1: ItemViewFrame.launchItemViewFrame( 2: new ItemViewLaunchRequestEvent(this, 3: "com.sgi.myProduct.category.BarCategory", 4: "foo"), 5: new UIContext());
1: ItemView iv = ItemView.createItemView(_hostContext,
2: "com.sgi.myProduct.category.BarCategory");
3: iv.setItem("foo");
4: _panel.add(iv.getPanel());
A: # Set up some macros to use in this resource file. See the
B: # ResourceStack documentation for more about macros.
C: RHINO_EXAMPLE_CATEGORY=com.sgi.rhexamp.category.rhexampRhinoExampleCategory
D: IVprefix=${RHINO_EXAMPLE_CATEGORY}.ItemView
E: ITprefix=${RHINO_EXAMPLE_CATEGORY}.ItemTable
F:
G:
H: # Set the width and height of the ItemView. See the PANEL_WIDTH and
I: # PANEL_HEIGHT documentation for more information.
J: ItemViewPanel.width=333
K: ItemViewPanel.height=260
L:
M: # Set up the three fields. Call the fields "name", "type", and "mode".
N: ${IVprefix}.field0=name
O: ${IVprefix}.field1=type
P: ${IVprefix}.field2=mode
Q:
R: # Tell the ItemView which Attributes of the Item to use to show the
S: # appropriate field. It is not necessary to set the "basedOn" resource
T: # for a field that is using the "renderer" method, which is why there is
U: # no "${IVprefix}.basedOn.mode" resource. In this case, the next two
V: # lines are unnecessary, because the name of the Attribute is the same
W: # as the field. They are included here to make the resource file easier
X: # to understand and for illustration purposes.
Y: ${IVprefix}.basedOn.name=name
Z: ${IVprefix}.basedOn.type=type
AA:
AB: # Sets the labels to be used for the three fields.
AC: ${IVprefix}.label.name.label=Name:
AD: ${IVprefix}.label.type.label=Type:
AE: ${IVprefix}.label.mode.label=Access:
AF:
AG: # Sets the method that the ItemView will use to display the
AH: # three fields.
AI: ${IVprefix}.method.name=toString
AJ: ${IVprefix}.method.type=lookup
AK: ${IVprefix}.method.mode=renderer
AL:
AM: # Resources necessary because the "type" field is using the
AN: # "lookup" method. See the description of the lookup method for more information.
AO: ${IVprefix}.lookup.type.Printer=Printer
AP: ${IVprefix}.lookup.type.Clock=Clock
AQ: ${IVprefix}.lookup.type.NetscapeExecutable=Netscape
AR:
AS: # Tells the ItemView what classes to use as the
AT: # ItemViewFieldRenderer and the ItemViewAdditionalInfoRenderer. In this
AU: # case, both renderers are in the same class, but this is not
AV: # necessarily the case.
AW: ${IVprefix}.fieldRenderer=${RHINO_EXAMPLE_CATEGORY}Renderers
AX: ${IVprefix}.additionalInfoRenderer=${RHINO_EXAMPLE_CATEGORY}Renderers
AY:
AZ: # Resources specific to the AdditionalInfoRenderer. The
BA: # AdditionalInfoRenderer has access the the ResourceStack, so this file
BB: # is a good place to put resources that control the
BC: # ItemViewAdditionalInfoRenderer or ItemViewFieldRenderer. The names of
BD: # the resources are specific to the code that is written in the
BE: # renderers.
BF: ItemView.AdditionalInfo.marginLeft=0
BG: ItemView.AdditionalInfo.marginTop=0
BH: ItemView.AdditionalInfo.marginBottom=0
BI: ItemView.AdditionalInfo.marginRight=0
BJ: ItemView.AdditionalInfo.layoutType=vertical
BK: ItemView.AdditionalInfo.label=Additional Information:
BL: ItemView.AdditionalInfo.text=This area is available for displaying \
BM: additional, item-specific Components to represent this item. In this \
BN: example, we're just displaying text in a RichTextComponent, but you can \
BO: put any Component you want in here.