Programmer's Guide:
Using Rooms

What is a Room?

A Room is the container for all of the data related to a particular project. A member list is associated with each Room so that access to the data may be restricted. The actions of members of the Room may be further constrained by the role assigned to each member. The person who creates the Room is by default the Room's coordinator. The coordinator has the ability to modify the Room's member list by adding or removing members and assigning privileges to those members.

Each Room has an ID Graphic, a search page, and a home page. A Room's home page is the first page a user sees upon entering a Room. The home page is the root of the tree of items contained in the Room. The ID Graphic appears in the upper right hand corner of every page in the Room, and in the directory of Rooms displayed by the Facility. It is set by the Room's coordinator., and usually displays a logo or other image which represents the purpose of the room. The search page allows any member of the Room to search for any item in that Room. See Searching in Rooms and Facilities for more information about writing programs that search rooms and facilities.

SAAPI programs interact with Room objects through the IERURoom interface. Common tasks you'd perform with a Room object include generating reports that contain member information, populating the room's member list iwth information retrieved from another source, creating new items within the room, and iterating over items contained in the eRoom.

Room names: URLName and DisplayName

Rooms actually have two names: a URL name and a display name. The display name is the name that appears in most parts of the eRoom user interface, and the URL name is the name that appears in the room's URL. Both names are specified when the room is created, and both can be changed later, though changing the URL name will break any existing links to the room that are stored elsewhere. By default, the URL name is derived from the display name by removing spaces and other characters that are not valid within URLs. The display name and URL name can be retrieved from a Room by accessing the DisplayName and URLName properties defined in IERURoom.

Opening a Room from a Server Manager

You retrieve a Room object by starting with a Server Manager, use the GetRoomByName method when you know the name of the room, or use the GetRoomByID method when you know the room's ID. Both of these methods are defined in the IERUFacility interface; therefore, you are required to get a Facility from the Server Manager first.

Dim SMgr as IERUSvrManager
Dim Fac as IERUFacility
Dim Room as IERURoom
Set SMgr = CreateObject("eRoom.ServerManager")
Set Fac = SMgr.GetFacility("myfacility", "user1")
' Get the Room by name...
Set Room = Fac.GetRoomByName("myroom")
' ... or get the Room by ID
Set Room = Fac.GetRoomByID("{12345678-1234-1234-1234-123456789ABC}")

Accessing Rooms by ID can make your SAAPI programs more stable, since they won't be susceptible to name changes.

Creating a Room

To create a Room, your SAAPI program must first access the Facility object in the context of a user who has "Can create rooms" privileges. Then, you can create a Room using the CreateRoom method of the IERUFacility interface. For example:

Dim NewRoom as IERURoom
Fac.CreateRoom("MyNewRoom", "My New Room")

To create a new Room by copying an existing Room, access the existing Room, and then pass it as the optional third parameter to CreateRoom:

Dim NewRoom as IERURoom
Dim TemplateRoom as IERURoom
Set TemplateRoom = Fac.GetRoomByName("Template")
Set NewRoom = Fac.CreateRoom("NewRoomFromTemplate", "New Room From Template", TemplateRoom)

Deleting a Room

To delete a Room, you must access the Facility object in the context of a user who is either a coordinator of the Room or a facility administrator. See Access Control and User Contexts for more details about coordinators and facility administrators. To delete a Room, simply call the Delete method of IERURoom:

MyRoom.Delete

Home pages

When you create a new Room, a Folder Page object called the home page is automatically created inside it. You can access the home page with the HomePage property in IERURoom. A Room's home page is the root of its containment hierarchy. Although home pages are Folder Pages, they have some restrictions that other Folder Pages do not: they cannot be copied, moved, renamed, or deleted.

The following example creates a new Link on a Room's home page.

Dim CltManager As New ERUCltManager
Dim Item As IERUItem
Dim Container As IERUContainer
Dim Room As IERURoom
Dim MyLink As IERUItem

Set Room = CltManager.GetRoom("http://localhost/eroom/fac7/fac7-room1", "pfoley", "pf", "", "")
Set Container = Room.HomePage
Set MyLink = Container.CreateLink("Look Here!", "http://www.instinctive.com")

Room Coordination

Users have access rights to objects within a Room based on their member rights in the Room. A member can have one of these three types of rights: observer, participant, or coordinator. For general information about member rights, see Access Control and User Contexts.

Besides having full privileges within a room, coordinators have special rights to administer many aspects of the room. Coordinators can add and remove members from the room's membership list. They can also modify the settings for the Room. Settings for a Room include changing the URL or display name, specifying whether the Room is listed in the Facility List, and setting the ID graphic. Coordinators may assign special privileges to participants that they do not have by default, like modifying the member list or facility administrator rights.

Adding and removing members

You add members to a Room by choosing them from the Facility's member list. Use the AddMember method to add a User or Group to a Room. Use the RemoveMember method to remove a User or Group from an eRoom.

The following example adds a user to a room:

Dim Member as IERUMember

'Get an IERUMember interface to the user, looking it up by its ID.
Set Member = Fac.GetMember("123")
'Add the user to the room with participant's rights.
Room.AddMember Member, erRoleParticipant
'Additionally, give the user rights to modify the member list.
Member.User.CanModifyMemberList = TRUE

Room settings

In addition to using Room objects to access the items contained within them, your SAAPI program can read or write a variety of settings which apply to the Room as a whole. These settings are manipulated through the Room's IERURoom interface. For instance, you can find out who created the Room, when it was created, and when it was last modified by accessing the Creator, CreateDate and ModifyDate properties, respectively. You can get and set the name which appears in the eRoom UI and the name used in the Room's URL through the DisplayName and URLName properties. The URL for the room is stored in the URL property.

You can also affect whether and how the Room appears in the room directory displayed in the eRoom user interface when you visit the facility's URL. The ShowInFacilityList property dictates whether users who are not members of the Room can see the Room in the room directory. The Description property contains the text that appears below the room name in the room directory. You can get the URL of the IDGraphic that appears in the room directory and the room's pages via the IDGraphicURL property, and assign a new ID graphic using the SetIDGraphic method.