Subject

Whitebeam provide the ability to create message groups which can then have messages posted to them by users. Messages and their replies are structured into threaded conversations in the Application Interface. The use of this interface is explained by this tutorial.

Message Group Application Interface

Contents:

• Dependencies
• Formal definition

• Creating a message group
• Removing a message group
• Listing all message groups

• Retrieving Messages from a Message group
• Creating a message in a group
• Deleting a message from a group
• Thread navigation

Overview

This application interface encapsulates the concept of Message Groups. It provides a high level abstraction to the underlying rb.message.group interface, incorporating concepts such as threading of articles, traversing and article tree, and preparation of various message attributes for HTML display.

Dependencies

In order to use message groups at all, the message template must be enabled for the client you intend to run this implementation under. The MessageGroup programming abstraction is then enabled by including the message.js file:

Formal Definitions

Detailed Usage

This part of the tutorial is split into 2 parts. The first part will describe how to carry out the basic functions of managing a message group eg creating/deleting etc. The second part describes how to carry out the main functions of message management. Each part will begin with a hypertext link to a table listing the properties of either the MessageGroup or message.

Message Group Management Overview

Creation of a message group

The following code will create a new message group:

	aMessageGroup = new MessageGroup("dogs");
	result = aMessageGroup.create("This is my dog description");
	if (result == null){
		rb.page.write("Error trying to create the new bulletin board");
	}else{
		feedback = "Bulletin board with name '"+result+"' created";
	}

This call utilises the member.js file whereby a MessageGroup object needs to be instantiated first, then an appropriate action carried out on that object. The values for the myMessageGroupName (name) and myMessageGroupDescription(description) are mandatory. The name for the group must be unique. A duplicated name will result in an error and a value of null being returned. The return code from a successful creation method call will be the name of the new message group.

Removing a message group

The following code will remove a message group:

	aMessageGroup = new MessageGroup("dogs");
	result=aMessageGroup.remove();
	if (result == null){
		rb.page.write("Error trying to remove the bulletin board");
	}else{
		feedback = "Bulletin board with name '"+result"' removed";	
	}

As for the creation method call, this call requires the MessageGroup object to be instantiated first. This call does not take a value. On success of removal, the return value will be the name of the group removed; on failure, a value of null will be returned.

Lists all groups available

Once created, there will be the time when a list of all available groups needs to be presented. This can be achieved with the following code:

	var groups = MessageGroup.listGroups();

This code will firstly obtain an array of message group names which is placed into an object named groups. This group's object can then be iterated through so that each name returned can be displayed within a form widget. This has been done here:

	<select name="selectednewsgroup">
	<rb:repeatfor expr="var g in groups">
		<option rb:eval="value#groups[g].name">
			<rb:eval expr="groups[g].name"/>
		</option>
	</rb:repeatfor>
	</select>

Note that this is a static method which simply lists the names of available groups without changing any visible properties of the MessageGroup Object.

Alternatively if you want to pull from the database information about a single message group then initialise a MessageGroup and call the method load():

//  Initailize the group
	var myGroup = new MessageGroup("dogs");
	MessageGroup.load();

By contrast, MessageGroup.load() is a full instance method which sets the first, last and description properties of the MessageGroup object

Message Management Overview

Overview

The following section describes the basic functions regarding the management of a message. This will cover creating a message, deleting a message and thread navigation. First, the structure of a message needs to be understood. This can be found here.

Retrieving Messages from a Message group.

Once you have created your message group in the previous section, you will want to get all the messages it contains. This can be achieved by first initialising the group that you are now managing by using the method call MessageGroup.get(). This will return no useful information but instead retrieves the headers of all specified articles within the message store for this group, performs thread analysis, and populates the article, message, and thread properties of the group. In other words this must be carried out before continuing with message management. This method call can be further optimised by providing the starting index number of the articles to be loaded from the message store.

Once you have initialised the group you may then try to load a certain message. The following will initialise the group, define a message to be found and then return the message.

//  Initailize the group
	var myGroup = new MessageGroup("dogs");
	myGroup.get();
//  Pull back the message object
	var myCurrentMessage = new Object;
	myCurrentMessage.messageID = "<9arrk8%247qn%24135@thl.redbourne.net>";
	MessageInfo = group.loadMessage(myCurrentMessage.messageID);

Creating a message in a group.

There are two ways to post a message. The first way is to create a message at the top level of the group and the second is to reply to an already posted message. To create a message at the top level, first obtain the group information from the store. Next create the message object. Finally, to commit the information to the store, the postMessage is used. Here, the method call myGroup.setMessage(msg) followed by the call myGroup.postMessage() could have been used instead of the immediate use of the myGroup.postMessage(msg) method. The former would be used if a web page receives 'posted' parameters and these are needed either for a reply or new posting. The code to support this is as follows.

//  Initailize the group
	var myGroup = new MessageGroup("dogs");
	myGroup.get();
//  Create the message
	var msg = new Object;

      msg.groups= new Array;

      msg.from="ashleyb@redbourne.com"  // mandatory (very important)
	msg.groups[0] = "dogs";
	msg.subject="This is my new message subject";
	msg.body="This is the body of my message";
//  Post the message to the group
	var ret = myGroup.postMessage(msg);

The alternative method to add a message is to reply to one already posted. Here, attributes from the parent message will need to be incorporated into the new message and also updated itself. To allow this to happen the following order of method calls needs to be carried out:

//  Initailize the group
	var myGroup = new MessageGroup("dogs");
	myGroup.get();
//  Pull back the message object
	var myCurrentMessage = new Object;
	myCurrentMessage.messageID = "<9arrk8%247qn%24135@thl.redbourne.net>";
	var msg = myGroup.setMessage(myCurrentMessage);
//  Returns a new message object ready to act as a reply to the above		
	var newMsg = myGroup.blankReply();
//  The form is now filled in by the user with the new message text or set below
   	newMsg.subject="This is a reply to message one"
   	newMsg.body="This is the body text";							
	var ret = myGroup.postMessage();

Here, the form is set-up so that the current message is the parent message. Next using the blankReply() method, the attributes of the current message are mutated to be a reply eg blanking the subject. Finally, once the reply has been filled in , the postMessage() method can be called.

Removing a message in a group.

The following method will remove a message from the message group:

//  initailize the group
	var myGroup = new MessageGroup("dogs");
	myGroup.get();
//  carry out the call on a message in the group to find the next in thread
	var myCurrentMessage = "<9arrk8%247qn%24135@thl.redbourne.net>";
	var previousMessageInThread = myGroup.removeMessage(myCurrentMessage);

You must have a valid message ID in order to carry out a remove method call. Child messages of a deleted message will be shuffled up to a parent if necessary. The call will return either the parent message or the previous top-level message prior to the one deleted on success. Alternatively, a null value returned indicates that no further messages are left in the group as this was the last to be deleted.

Message Thread Navigation

MessageGroup.threadNext(), when passed a message ID will return a message object equal to the next message in the thread, the reverse is true for the method MessageGroup.threadPrev(). These methods have been used in the following piece of code to display links to the next and previous messages in a thread of messages:

//  initailize the group
	var myGroup = new MessageGroup("dogs");
	myGroup.get();
//  carry out the call on a message in the group to find the next in thread
	var myCurrentMessage = "<9arrk8%247qn%24135@thl.redbourne.net>";
	var myNextMessageInThread = myGroup.threadNext(myCurrentMessage);

In addition to next and previous in thread navigation, we can also carry out next and previous thread navigation. The method calls to carry out this are MessageGroup.thread.[messageID].nextThread() or MessageGroup.thread.[messageID].lastThread(). An example use of one of the methods would be:

//  initailize the group
	var myGroup = new MessageGroup("dogs");
	myGroup.get();
//  carry out the call on a message in the group
	var myCurrentMessage = "<9arrk8%247qn%24135@thl.redbourne.net>";
	var myNextMessage = myGroup.thread[myCurrentMessage].nextThread();