In this tutorial you will learn how to use room variables. You will start with a modified version of the chat created in the Basic Chat Tutorial. You will be hooking up a simple form that asks each user a few questions after logging in. Then when a user creates a new room or joins a new room the answers to those questions will be stored in room variables on the server. A display on the screen will show information about the last user to join the room.

Getting started

This tutorial is based on the Basic Chat created in an earlier tutorial. A new .fla file with some minor changes applied is ready for you to download here. Using this file, we are going to go step by step through all of the new code you will need, in order to work with room variables.

So let’s get started!

To illustrate the use of room variables, we are going to do the following. The first time a user logs in, they will have to set a few personal details which will be stored in the client. When they join a room later on, these details will be sent to the server and the server will store them as room variables. The details of the last user that joins a room will overwrite the previously stored details. So at any given time the room variables will hold the details of the last user to join that room.

We are going to need a few new variables to represent the information mentioned above. Go to the Actions layer, frame labeled Login and type this code at the very top to declare the variables:

// useful variables
var gender:String;
var ageGroup:String;
var hasADog:Boolean;
var color:Boolean;

Now let’s take a look at the form that asks for the user’s details.

Store User details
Open the popup movieclip found on the Chat frame label and go to label Ask.

There are fields for the gender, age, favorite color of the user and an option of whether they have a dog or not. The two available options for the age group you see won’t give you very useful statistics, I just put 2 of them there for the sake of simplicity. You may use more of them and definitely more interesting than these two!

The names for the radio button groups are gender, color and age. The name of the instance of the checkbox is dog_chk.

Now, still on keyframe Ask at the Actions panel, type in the following code:

function ok() {
var myGender = gender.selection.__data;
var myAgeGroup = age.selection.__data;
var doIHaveADog = dog_chk.selected;
var myColor = color.selection.__data;
_parent.storeUserDetails({gender:gender, ageGroup:ageGroup, hasADog:hasADog, color:color});
close();
}

As soon as the user presses OK the data in the form will be collected and storeUserDetails() will execute. Let’s create that function.

Go to the main timeline, at the keyframe labeled Chat. At the bottom of the code, type this:

function storeUserDetails(details:Object):Void {
gender = details.gender;
ageGroup = details.ageGroup;
hasADog = details.hasADog;
color = details.color;
}

Now we have stored the user’s details in the variables we declared earlier.

We want the users to see the user details form as soon as they login. So, at the top of the code on the Chat keyframe, type:

showPopUp("Ask");

DISPLAY USER DETAILS
We need a space where we can display the information of the last user that enters a room.

Notice the red rectangle you see below the room list. It has an instance name of detailsBG. This is how it is structured.

In each keyframe the color of the rectangle changes as the label indicates.
This movieclip will change according to the color stored in the room variables. The labels are named according to the colors we have on the radio buttons on the User details form.

We need a textfield to display the room variables. Go to the main timeline. The details_txt textfield you see there will be used for this purpose.

Introducing room variables

Finally, it’s time to see how room variables work.

When you create a room, you can create a number of room variables at the same time. The code that creates a new room is inside the popup movieclip, keyframe labeled NewRoom. Go there and modify the makeRoom() function like this:

function makeRoom() {
var roomObj:Object = new Object();
roomObj.roomName = roomName_inp.text;
roomObj.Description = description_inp.text;
roomObj.password = password_inp.text;

// Create some room variables
roomObj.roomVariables = new Array();
roomOb.roomVariables.push({name:"gender", data:"", persistent:true});
roomOb.roomVariables.push({name:"ageGroup", data:"", persistent:true});
roomOb.roomVariables.push({name:"hasADog", data:"", persistent:true});
roomOb.roomVariables.push({name:"color", data:"", persistent:true});

_parent.es.createRoom(roomObj);
}

Now every new room that is created will hold these four room variables, each one having an empty value.

Notice the persistent property? When a room variable has persistent = false, it means that it will be deleted as soon as the user that creates it leaves the room. If persistent is set to true, the variable will remain in the room, even if the user who created it leaves. The default value is false.

Another property of a room variable is locked. If set to true, the variable cannot be modified once created. However it can still be deleted. The default value is false.

Let’s now create the function that sends the user’s details to the server. At the bottom of the Chat keyframe code, add this:

function updateRoomVariables():Void {
es.createRoomVariable({name:"gender", data:gender});
es.createRoomVariable({name:"ageGroup", data:ageGroup});
es.createRoomVariable({name:"hasADog", data:hasADog});
es.createRoomVariable({name:"color", data:color});
}

As you can see, the user’s details are updating (overwriting) the room variables. As we said before, when users join a room, we want the room variables to be updated. So, we have to add something in the roomJoined() function, at the Chat keyframe. The function should now look like this:

function roomJoined(result:Object, room:Object) {
if (result.success) {
//successfully joined room
chatBox.text = "";
updateRoomVariables();
} else {
showPopUp("Error", result.error);
}
}

Display last user details

Let’s create now the function that displays the user information stored in the room.

function showRoomDetails():Void {
var room:Object = es.getRoom();
var roomVariables:Object = room.roomVariables;

details_txt.text = "Last user's details in room " + room.Name.value + ":\n";
details_txt.text += " gender: " + roomVariables.gender + "\n";
details_txt.text += " age group: " + roomVariables.ageGroup + "\n";
details_txt.text += " has a dog: " + roomVariables.hasADog;

detailsBG.gotoAndStop(roomVariables.color);
}

Place the above code inside the actions panel in the Chat keyframe. The first line of the function gets the room you are currently in.

var room:Object = es.getRoom();

The server returns a room object which has all the information you need about this room, including all the room variables stored in that room, so you can easily access each variable by its name. (e.g. room.roomVariables.gender). This function displays the last user’s details inside the details_txt TextField and changes the color of the detailsBG movieclip according to the color stored in the room variable color.

When should this function be called? You must keep in mind that when es.createRoomVariable() is executed, the updated room variables are not immediately available to the client. The message with the parameters for the creation or modification of the room variable travels to the server, the server creates or modifies the variable and then it fires an event that notifies all the clients of the room variable update, es.roomVariablesUpdated.

So, we have to create a callback function that will catch this event. In the code of the Chat keyframe, find the line that says :

es.roomListUpdated = showRooms;

and add just below that the following lines:

es.roomVariablesUpdated = roomVariablesUpdated;

function roomVariablesUpdated(type:String, roomVariables:Object, name:String):Void {
showRoomDetails();
}

As you can see, the only thing that roomVariablesUpated() does is call showRoomDetails().

Take a look at the parameters of the roomVariablesUpated() function, type, roomVariables and name.

• type can be “all”, “updated”, “created” or “deleted”. The first time you enter a room, type equals to “all”. From then on type is one of the rest 3.

• roomVariables is an object that holds all of the room variables.

• name is the name of the variable that was updated, created or deleted. If type = “all”, name is blank.

One thing you have to remember about room variables is that users can only see the room variables of the room they are currently in. Room variables are not visible outside that room. If they were, the data returned in the es.getRoomList() object could be huge and applications or games made with ElectroServer would slow down substantially.