Update: This blog post took me the better part of a day and a half and just as I was posting it I realized I had a huge hole in the logic for my application because of the problem at the bottom. My plan is to come back and clean this up, as Peter suggested, divide it up into a couple of parts. The most important parts are the first couple of paragraphs that talk about the sharedModel classes and the last paragraph that mentions how the AFCS team architected things to build on top of very low level base classes like CollectionNode. Largely this blog post is a mess and digging into CollectionNode was interesting but I recommend it only after having some time playing with the other classes in sharedModel. After that this might be a useful post to read. Diving into the video tutorials is also highly recommended.
The basic building blocks of Adobe Flash Collaboration Service (AFCS) are really the sharedModel package and the CollectionNode classes included in it. Using the classes in the sharedModel package you can share any piece of data across AFCS connections and use these classes to build custom collaboration components like charts or maps where data can be updated and must change for everyone who is connected. I’ll first talk about some of the classes in the sharedModel package and then dive into how to use the CollectionNode, which provides the base functionality for sharing data.
Shared Models
The classes in the Shared Model package include a number of ways to share data and actions with AFCS. For the most part, the classes in sharedModel all use the CollectionNode to exchange data but they abstract a bit of the nuts and bolts of CollectionNode to make it easier to use. For instance the SharedProperty class lets you take any arbitrary property and share it across AFCS instances. It includes the ability to specify a CollectionNode or to just use one that will be generated as soon as the component using SharedProperty is created. Nigel Pegg has a great tutorial that covers using SharedProperty. Another set of classes in the sharedModel package are the Baton classes. The Baton is essentially a SharedProperty that gives you more control over when a user can edit something. The Baton class helps define when something is currently in use and shouldn’t be editable by anyone else in the room. It includes methods to grab() and putDown() a baton as well as a batonHolderChange event, which can be used to make changes to the user interface. Nigel’s video goes through this as well using the example of a TextInput box. Using the Baton classes it is easy to disable editing of the TextInput while someone else is typing inside of it.
CollectionNode
All of the classes above use collection nodes and there are three major parts to the basic CollectionNode: creation, configuration, usage. As the documentation states, an AFCS room is essentially a bunch of CollectionNodes exchanging data and each of those nodes has specific configurations that define who and how people can interact with them. One thing to note is that CollectionNodes can only be created by a room owner, or someone with UserRoles.OWNER so when creating a CollectionNode, the owner must be the first person in the room so they can “initialize” it. After that the developer can use the NodeConfiguration classes to customize what level of user has read or write access to the node.
Creating a new CollectionNode is pretty straightforward. In this example I’m going to create a mini-game where the participants have to match up a ColorPicker to “win”. To set up the game, I’ve got one CollectionNode with a “Color” node that will contain the values of the ColorPicker. Here’s how I create the CollectionNode:
protected function application1_creationCompleteHandler(event:FlexEvent):void
{
nodeGame = new CollectionNode();
nodeGame.sharedID = "gameNodes";
nodeGame.addEventListener(CollectionNodeEvent.SYNCHRONIZATION_CHANGE, onSync);
nodeGame.addEventListener(CollectionNodeEvent.ITEM_RECEIVE, onItemRecieve);
nodeGame.subscribe();
}A few things to notice. First, the sharedID property is described in the docs as the “logical address of the collection within the room” and is how AFCS will refer to it so it needs to be unique. It is also the name that you will see when you browse the nodes in the room console that comes with the SDK. Second, in order to use the node we have to make sure it’s synchronized or we’ll get an error. After creating the node I added a CollectionNodeEvent listener that fires when we have a synchronization change event. I also added an event handler for when we receive messages upon subscribing to the node, which I’ll talk about later. Once the SYNCHRONIZATION_CHANGE event fires we can start making changes to our CollectionNode:
protected function onSync(event:CollectionNodeEvent):void
{
var config:NodeConfiguration = new NodeConfiguration();
config.modifyAnyItem = false;
config.userDependentItems = true;
nodeGame.createNode("Color",config);
createMessage(false);
}Now that we’re able to make changes to the CollectionNode I can create the Node that will store messages, in this case the “Color” Node. First I need to use the NodeConfiguration class to set up some rules for the game. By setting the modifyAnyItem property to false I make sure we’re not allowing users to modify messages that aren’t created by them. The userDependentItems property set to true means that when the user leaves the room, we clear out all of the messages belonging to them. In our game we don’t want to find a match with someone who isn’t playing any more. The NodeConfiguration classes allow us to tweak things like what happens to messages as well as define permissions for specific nodes within my CollectionNode. Once we’ve created the NodeConfiguration I can use the createNode() method to create a Node named “Color” and pass in the configuration values I just created. The last method there is a function I created. After we create the node and configure it I want to send the value of my ColorPicker to AFCS so I can start playing the game. I do that with a createMessage()
protected function createMessage(overwrite:Boolean):void
{
var colorMessage:MessageItem = new MessageItem("Color");
colorMessage.itemID = cSession.userManager.myUserID + "_color";
colorMessage.body = color1.selectedColor;
nodeGame.publishItem(colorMessage,overwrite);
}My createMessage() takes one variable, a Boolean that we'll use to tell AFCS whether or not we are allowed to overwrite an existing message. The first part of the code is where we create our MessageItem to be sent. I'm just creating a new MessageItem and passing in which Node it will belong to, in this case the "Color" node I created above. Then I give it an itemID, which is how it will be referred to by AFCS. I use the current userID and prepend that to the word color. Finally I set the body of the message. The body of a MessageItem can be a String, a Boolean, a Number, or a key-value pair. In this case we're just going to pass in our selectedColor value. Once we create the MessageItem we need to add it to the Node. To do that we use the publishItem() method on the CollectionNode. This is where I pass in the overwrite flag. In this case, I don't want the MessageItem to be overwritten because this should be the first time we're adding it since we called it from the OnSync method. But later I want to make sure we overwrite it because we're making updates to it.
As soon as we publish our message, it's going to go into AFCS and then AFCS is going to send it back to us so we make sure it was sent correctly. When that happens it will fire an ITEM_RECEIVE event, for which we added an event handler in our initial function. That code looks like this:
protected function onItemRecieve(event:CollectionNodeEvent):void
{
var tempMessage:MessageItem = event.item;
var userName:String = cSession.userManager.getUserDescriptor(tempMessage.associatedUserID).displayName
arrColors.push({color:tempMessage.body,user:userName});
if(tempMessage.associatedUserID != cSession.userManager.myUserID)
{
if( tempMessage.body == color1.selectedColor )
{
Alert.show('Winner! Your partner is: ' + userName);
}
}
}This is where we start to get to the game. The first two lines just put the MessageItem and user displayName into their own variables. Next we put the selectedColor from our message and the displayName into an array that's stored on the client. This is kind of important. A lot of the sharedModel classes, like SharedProperty for instance, will handle storing data for you but the CollectionNode class doesn't, it's a very basic, low level component. So in this case we can't tell AFCS to send us a list of messages to check and see if there is a match, we have to keep a record within our own application. I do that by storing the information in an Array. Once I do that I want to check if we have a match but I need to make sure we're not matching our own color so I do a quick check using the associatedUserID and myUserID from the ConnectSession. Once we know that isn't the case I can check the body of the message with my current color to see if there is a match and pop up the appropriate dialogue.
When we make changes to our color to try and find a match we also need to send the update to AFCS and check our Array so I added an event handler to my ColorPicker for any change event:
protected function color1_changeHandler(event:ColorPickerEvent):void
{
createMessage(true);
for(var i:Number=0; i<arrColors.length; i++)
{
if(event.color == arrColors[i].color)
{
Alert.show('Winner! Your partner is: ' + arrColors[i].user);
}
}
}In this case the first thing we do is call createMessage() with the overwrite flag set to true so we are overwriting our current message with the new color value instead of creating a new one. Then we run through our array of colors to see if this new color matches anything on the system. Do you notice a problem?
The problem is this: We configured our Node to remove all messages as soon as someone leaves the room but because we're using CollectionNode instead of one of the higher level classes we also have that array that is storing the values. We're using that array to check for a match after we change our color but we don't ever clear out old messages from our array so we might get a match from someone who is no longer logged in. We're also not checking the array and updating values so we have a lot of old data.
Welcome to Multi-User Applications
Multi-user applications are fun but there is also a lot to deal with. Luckily, the AFCS team has done a very good job of building base functionality into classes like CollectionNode and then building on top of them with classes like SharedProperty that take care of a lot of the complicated parts of managing a collaborative application. I tried to get nitty gritty and show how CollectionNode works but I really encourage you to start with the higher level classes, get an idea of what's happening, and then break down to the low level base classes when you need to start creating very customized collaborative applications with specific rules, custom components, and many different types of data.
You can grab the full project here (Flash Builder 4 FPX file) and see how the parts fit together. I'll be updating it in the next few days to take into account the problem above and include a version that people can play.
If you’re a Fireworks user you’ll be happy to know that the team has been hard at work improving the FXG export feature so you can more easily take your designs from Fireworks and use them in Flash Catalyst. The new script is available over on Adobe Labs and includes a ton of fixes to the old FXG script as well as some new functionality based on a more finalized FXG specification:
