Buddy list tutorial

From EsWiki

Jump to: navigation, search

This is a tutorial that explains how to add and remove buddies. Please note that if you want to persist buddies, or require that the buddy relationship be symmetric or authorized by the other user, a server extension will be required (either a plugin or an event handler). When buddy lists are not persisted, they are lost when the user logs off.

Contents

What You'll Learn

  • Adding a buddy from the client
  • Removing a buddy from the client
  • Displaying a full buddy list
  • Adding a buddy from a plugin
  • Removing a buddy from a plugin

Prerequisites

  • You must have ElectroServer 4 installed and running.
  • You need the client-side ElectroServer 4 API.
  • Advanced Chat Tutorial

Download

If you wish to simply download the entire set of BuddyList files (source code and compiled), it is found in BuddyList.zip. Please note that the client API files included in the zip are for ES4.0.6. If you are using some other version of ES4, you will need to replace the API with that for the version that matches your ES4 and republish the swf.

Let's Get Started!

In the steps below you will learn how to modify your Advanced Chat to allow users to add and remove buddies.

Features to add

First, we should plan what we intend to add to the Advanced Chat. These features are:

  • Add Buddy button
  • Remove Buddy button
  • Show Buddies button

Chat UI

In Flash, add three Button components, labeled c_addBuddy, c_removeBuddy, and c_showBuddies. Place appropriate text on each button, and put the buttons on the Chat UI where convenient. You may want to move the textfield for chat messages down a bit to allow room for buttons.

Main.as

Needed imports

The sum of all the imports needed for this tutorial is given below. If you are working from the Advanced Chat source code, the only new one is BuddyStatusUpdatedEvent. 

 
	//Flash imports
 
	import fl.controls.List;
	import fl.controls.TextArea;
 
	import fl.controls.listClasses.CellRenderer;
	import fl.controls.listClasses.ListData;
	import flash.utils.getQualifiedClassName;
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.text.TextField;
	import flash.display.SimpleButton;
	import flash.events.MouseEvent;
 
 
	//ElectroServer imports
	import com.electrotank.electroserver4.esobject.EsObject;
	import com.electrotank.electroserver4.message.request.LogoutRequest;
	import com.electrotank.electroserver4.message.request.PublicMessageRequest;
	import com.electrotank.electroserver4.message.event.JoinRoomEvent;
	import com.electrotank.electroserver4.message.event.PublicMessageEvent;
	import com.electrotank.electroserver4.message.event.ConnectionEvent;
	import com.electrotank.electroserver4.message.request.LoginRequest;
	import com.electrotank.electroserver4.message.response.LoginResponse;
	import com.electrotank.electroserver4.message.event.UserListUpdateEvent;
	import com.electrotank.electroserver4.message.MessageType;
	import com.electrotank.electroserver4.message.request.LeaveRoomRequest;
	import com.electrotank.electroserver4.message.request.PrivateMessageRequest;
	import com.electrotank.electroserver4.message.request.CreateRoomRequest;
	import com.electrotank.electroserver4.message.event.PrivateMessageEvent;
	import com.electrotank.electroserver4.message.event.BuddyStatusUpdatedEvent;
 
	import com.electrotank.electroserver4.entities.RoomVariable;
	import com.electrotank.electroserver4.user.User;
	import com.electrotank.electroserver4.ElectroServer;
	import com.electrotank.electroserver4.zone.ZoneManager;
	import com.electrotank.electroserver4.zone.Zone;
	import com.electrotank.electroserver4.message.event.ZoneUpdateEvent;
	import com.electrotank.electroserver4.room.Room;

This includes the ones that were already in there from Advanced Chat.

enableChatScreen function

First, we will modify the enableChatScreen function from before to add a BuddyStatusUpdatedEvent listener. Just add this line: 

			es.addEventListener(MessageType.BuddyStatusUpdatedEvent, "onBuddyStatusUpdatedEvent", this);

disableChatScreen function

Similarly, we need to add a matching line in disableChatScreen. 

			es.addEventListener(MessageType.BuddyStatusUpdatedEvent, "onBuddyStatusUpdatedEvent", this);


attemptToAddBuddy function

When the "Add Buddy" button is pressed the attemptToAddBuddy function is called. This function makes sure the username is not empty and then sends an add buddy request. If there is information about the buddy that needs to be remembered, place it in the EsObject that is sent with the request. 

	private function attemptToAddBuddy() {
		output("Attempting to add buddy");
		if (c_userName.text != "") {
			var esob:EsObject = new EsObject();
			//esob.setBoolean("isBuddy", true);
			es.addBuddy(c_userName.text, esob );
			output("AddBuddyRequest sent");
		}
	}

attemptToRemoveBuddy function

Similarly, when the "Remove Buddy" button is pressed the attemptToRemoveBuddy function is invoked. 

	private function attemptToRemoveBuddy() {
		output("Attempting to remove buddy");
		if (c_userName.text != "") {
			es.removeBuddy(c_userName.text);
			output("RemoveBuddyRequest sent");
		}
	}

attemptToShowBuddies function

When the "Show Buddies" button is pressed, the attemptToShowBuddies function is called. The buddylist is kept in the client's own Electroserver object, so no message needs to go to the server. 

	private function attemptToShowBuddies() {
		var buddyList:Object = es.getBuddyList();
		// TODO: iterate through the object, build message to display in window
		var buddies:String = "";
		for (var buddy:String in buddyList) {
			//output(buddy + ": " + buddyList[buddy]);
			var esob:EsObject = buddyList[buddy];
			if (esob == null) {
				// buddy has been removed
				output(buddy + " no longer a buddy");
			} else {
				if (buddies.length < 1) {
					buddies = buddy;
				} else {
					buddies = buddies + ", " + buddy;
				}
			}
		}
		if (buddies.length < 1) {
			buddies = "You have no buddies.  You must be lonely!";
		} else {
			buddies = "My buddies: " + buddies;
		}
		output(buddies);
	}

onBuddyStatusUpdatedEvent function

When a user logs on or off, a message is sent to each client that lists this user as its buddy, with a BuddyStatusUpdatedEvent. Here is an example of how to process that event. 

	public function onBuddyStatusUpdatedEvent (e: BuddyStatusUpdatedEvent) {
		var u:User = e.getUser();
		switch(e.getActionId()) {
			case BuddyStatusUpdatedEvent.LoggedIn:
				output(u.getUserName()+" logged in.");
				break;
			case BuddyStatusUpdatedEvent.LoggedOut:
				output(u.getUserName()+" logged out.");
				break;
			default:
				output("Buddy update event not handled.");
				break;
		}
	}

onButtonClick

In this tutorial, all buttons call the same function, and then it checks to see which one was pressed and acts accordingly. You could also have three separate functions, it is really up to your own preference. 

   	private function onButtonClick(e:MouseEvent):void 
   	{
   		if (e.target == c_sendButton) 
   		{
   			attemptSendMessage();
   		}
   		else if(e.target == c_privateMessage )
   		{
   			attemptToSendPrivateMessage();
   		}
		else if(e.target == c_addBuddy )
		{
			attemptToAddBuddy();
		}
		else if(e.target == c_removeBuddy )
		{
			attemptToRemoveBuddy();
		}
		else if(e.target == c_showBuddies )
		{
			attemptToShowBuddies();
		}
   		else if(e.target == c_joinRoom )
   		{
   			attemptToJoinRoom();
   		}
   	}

As noted above, it checks to see what button was pressed, and handles it accordingly by calling the appropriate functions.

Plugins and Buddies

That's all that is needed for basic buddies. More complicated buddy handling requires a plugin or event handler on the server. For example, if we wanted to have a plugin manage the add and remove of buddies in conjunction with database calls, we would use lines similar to these: 

     boolean ok = getApi().addBuddy(username, buddyName, esob);
 
     boolean ok = getApi().removeBuddy(username, buddyName);
Retrieved from "http://www.es-wiki.com/index.php?title=Buddy_list_tutorial"
Personal tools
download