Programmer's Guide:
Using Items and Principal Items

SAAPI defines two interfaces that are widely used in its object model. These interfaces are IERUItem and IERUPrincipalItem. In this documentation, any objects that implement these interfaces are called Items and Principal Items, although these are generic terms since there are no actual objects named Item or Principal Item.

What is an Item?

An Item is any object inside a room that is distinct from other objects in the sense that it has its own creator and create date. The IERUItem interface is the common interface implemented by these objects. Nearly all SAAPI objects inside Rooms are Items.

The IERUItem interface defines the properties and methods that all Items share. The properties Name, ID, Creator, CreateDate, Modifier, and ModifyDate give basic information about an Item. The Parent property returns the object that contains the Item. The Type property is very important; it tells you specifically what kind of object the Item is, so that you can tell which other interfaces it supports. IsUnread and EffectiveIsUnread indicate whether the object is marked as unread for the current user context. The Room property returns the Room object that contains the specified Item.

IsContainer and IsTopic are helper properties that indicate whether the Item implements the IERUContainer or IERUTopic interfaces. You could determine this information by getting the Type property and comparing it against the list of object types that are either Containers or Topics, but it is much easier to use these properties to categorize objects. IsPage is similar to IsContainer and IsTopic, but doesn't guarantee that a particular interface is supported. IsPage categorizes Items according to whether they appear as pages in the eRoom user interface.

IERUItem also defines a large number of interface-accessor properties. These are provided for programming languages that do not support the definition of interface-specific variables, such as VBScript. They return another interface for the same object, giving the same result as calling QueryInterface from C++ or assigning to a variable with a different type in VB. The IERUItem interface has an interface accessor property for every interface that an Item could support. Using interface accessors is a one way path - you can't get back to the IERUItem interface from properties in other interfaces. That is why IERUItem is the interface used most widely to identify objects in the signatures of methods in SAAPI, particularly for return parameters. Most of interface accessor properties are self-explanatory, returning the interface with the same name (prepended by IERU), except for Page. The Page property returns the page-specific interface appropriate for the current object (e.g. IERUFolderPage), if any. This property is not particularly useful in the current version, but is retained for backward compatibility with earlier versions of SAAPI.

See IERUItem for more details on this interface.

What is a Principal Item?

A Principal Item is an object that appears inside item boxes in the eRoom user interface. These include objects that can be created in the eRoom user interface when you click on the Create button in the toolbar (Folder Page, Inbox Page, Discussion Page, Topic Page, Database Page, Calander Page, Note Page, Poll Page, File, and Link), as well as some objects that are created indirectly (Mail Page and Version Page). All Principal Items are Items, but not all Items are Principal Items. Principal Items have a common set of features that are exposed through the IERUPrincipalItem interface.

In addition to its ID (available from IERUItem) a Principal Item can be identified by its URL or path, using the URL and Path properties in IERUPrincipalItem. The URL can be used to display the Principal Item in a web browser. The path of an object is the equivalent of a pathname of a file on disk; it identifies the route from the home page of the room through the hierarchy of containers that lead to the object. The path can be used to retrieve the Item through the GetItemByPath method of IERURoom.

IERUPrincipalItem has Size and SizeUnits properties that indicate the number of bytes or characters in an object, or the number of child objects it contains.

The RowPosition and ColumnPosition properties, as well as the SetPosition method, allow you to get and set the position that the object's icon occupies in its containing folder, when displayed in the user interface.

The Icon property returns the Icon used by the object, and the SetIcon method lets you choose a different icon.