Quick Dive into Parsley (Basic Messaging Example - Part 4)

This is part of a series of articles that should get you up and started using Spicesfactory's Parsley.
This is part 4.
In Part 1, I explained the reasons as to why we chose to use Parsley in our projects.
In Part 2, I explained what Parsley is and some basic concepts and how they relate to Parsley.
In Part 3, I showed how to set up Parsley and showed a basic injection example.

This article builds upon what was covered in Part's 2 and 3, so if you haven't seen them, I encourage you to start with Part 1.

In this article will look at a very basic example of how messaging works in Parsley.

Parsley Basic Messaging Example

What is Messaging?

   Messaging under the context covered here is the ability for two classes/components to communicate between each other without explicitly calling each others methods.  So basically "messaging" involves some decoupling, and that is the basic idea that drives messaging.

   Flash provides a fairly powerful and flexible messaging mechanism which is Flash  Events.  Flex adds Flex Events and Binding.  Yes, Binding is a messaging mechanism as it allows to invoke methods of other component's without calling them explicitly, in a very transparent way.  But Binding is focused on one specific task, notify that data has been updated, which is useful, and it's incredibly simple to set up.  The "problem" with Binding is that in the process of decoupling methods, you couple properties.  Now I'm not saying that Binding is bad, actually I think it's great, it is simply not something to be used everywhere.

  Flash and Flex Events are great.  From the sender's perspective, it's totally decoupled.  The class/component that needs to send the message does not need to know anything about who is listening.  All you do is dispatch an event.  Now from the receiving part is where it's not entirely decoupled.  In Flash and Flex, to be able to catch a message you must be listening for messages, and you implement this through event listeners. Event listeners, must be attached to some instance of a class/component which can be the the object that dispatched the event.  Now, events in Flash have the ability to "bubble" and what means is that you can add event listeners to the view parents of the object that dispatched the event and still catch the message.  Flash and Flex events have the capability to travel through the view hierarchy and be caught elsewhere.  So this still provides some decoupling but you still have to attach your listeners to some instance of that is part of the view hierarchy.  You could go for the root, which is the Application object, to decouple, but this means that you can't have more specific scopes.  Although Flash / Flex events are great, there is still a small gap to be filled, and that's where Parsley's messaging comes in.

Parsely's Messaging

  As discussed above, Parsley comes in to fill the gap and not only provides fully decoupled senders, it also provides fully decoupled receivers.  One of the great things about how Parsley implements it's messaging mechanism, is that it not only decouples the sender from the receiver, it decouples both from the Parsley framework itself.  You do not need to extend any class, nor you need to attach/bind/assign listeners to any specific object.  Also, Parsley's messaging is generic, it is not aimed towards any specific pattern.  So you can totally take advantage of Parsley's messaging to implement any MVC pattern or any other pattern and not have to extend/add/change any of Parsley's classes to do so.  It's simple and very flexible.  Additionally, you can use extend Flash/Flex events, but you do not have to.

So let's take a look at how it works.  You can have Parsley manage specific Flex events, or you can use simple classes to send messages.

We will begin with a simple class.  You can look at the docs on how to have Parsley manage standard Flex events.

Dispatching Messages

   Essentially you should begin by creating a class that will hold your message.  In this particular case, I'm building a simple application that logs every message sent and displays it in a listbox.  Here is the basic structure of our application.  You might notice that I'm not following convention regarding package names, this is on purpose to make the example much easier to follow.

So here is the messaging class called LoggerMessage.as

package messages
{
    /***************************************************************
     * This is a simple class that will hold a message so it can be 
     * delivered thought our application.  It only has one property
     * that is the message itself.  Note that it does not 
     * extend Flexs Event.  It is inteded to be used for a log in 
     * future.
     * */ 
    public class LoggerMessage
    {
        /********************
         * This is the private var that holds our message
         * */
        private var _message:String;
        
        /********************
         * Constructor that takes the parameter as message
         * @param message  is a String that contains the text that will be set
         * */         
        public function LoggerMessage( message:String)
        {
            _message = message;
        }
        
        /*********************************
         * read only property that delivers the message.
         * */
        public function get message():String
         {
             return _message
         }
    }
}

There is nothing special about this class.  It simply has a read only property which is the message itself that can only be defined when you instantiate the class.

Let's move on to the SendView.mxml file which is the view that actually sends the message.  There is a few things that you should notice.  There is a <Configure /> tag which if you recall from the previous article, it tells Parsley that you want it to manage this view.  There is a [MessageDispatcher] tag which we didn't see in the previous article.  This tells Parsley that you want it to inject a message dispatching function into the variable declared immediately below.  This function will help us dispatch non Flex Event messages.  Here is the code for SendView.mxml.

<?xml version="1.0" encoding="utf-8"?>
<!--
This is a simple view that will send messages
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="128" height="86"
     xmlns:parsley="http://www.spicefactory.org/parsley" horizontalAlign="center" cornerRadius="2" borderStyle="inset">

    <!--
    Configure is very important.  Configure dispatches an event that instructs Parsley that you 
    wish to have this view Managed by Parsley.  If you do not include this tag or do not launch
    the configure event, Injection nor Parsley messaging will not happen in this view.
    -->
    <parsley:Configure />
    
<!--
    This CheckBox simple get's a check once the dispatcher has been injected.  
    If no injection has occured, the value will be null
-->    
    <mx:CheckBox label="Sender Ready" enabled="false" selected="{dispatcher != null}"/>
    
<!--
    The Text input is not tied to anything
-->
    <mx:TextInput width="100%" id="messageTextBox"/>
    
<!--
    The button will dispatch our events.
-->    
    <mx:Button label="Send Message" enabled="{dispatcher !=null}" click="handleButtonClick(event)"/>

    <mx:Script>
        <![CDATA[
            import messages.LoggerMessage;
        
    /******************************************
     *   In this example we will be using Parsley's Message dispatcher 
     *   which does not require the use of FlexEvents.  This takes 
     *   decoupling a little bit further, since the receiving end of the
     *   message will not have an event.target option in which they can
     *   access the sender.  This can also be declared in MXML.
     *   Important NOTE: Dispatcher does not have to be Bindable. I made
     *                   it Bindable so I could bind it to the checkbox and 
     *                    button for this example. 
     ***/            
             [MessageDispatcher]
             [Bindable]
            public var dispatcher:Function;
            
            private function handleButtonClick(event:MouseEvent):void
            {
                if (dispatcher != null)
                 {
                     dispatcher(new LoggerMessage(messageTextBox.text));
                 }
            }   
        ]]>
    </mx:Script>
</mx:VBox>

Take a look at the function executed when the button is pressed.  It first checks if the variable of type Function called dispatcher is not null.  This is the variable in which the  [MessageDispatcher] got injected into.  The message dispatcher function expects one argument, the instance of a class (any class) that you wish to send.  The keyword here is "any" in any class.  So I create a new instance of LoggerMessage with the text from the TextBox as the message.  That instance of the message will be sent to any class that wishes to receive it.  You can have more than one listener.  That's it for dispatching messages, now on to the receiving part.

Message Handlers

Receiving messages is quite simple and it is the same whether the message was sent using Parsley managed FlexEvents or the MessageDispatcher.  You must simply put a [MessageHandler] tag above the function declaration that you wish to get called.  Note that you will also have to include the <Configure />  tag to have Parsley manage this view.  Let's take a look at ReceiveView.mxml.

<?xml version="1.0" encoding="utf-8"?>
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml"  width="140" height="112"
     xmlns:parsley="http://www.spicefactory.org/parsley" horizontalAlign="center" cornerRadius="3" borderStyle="solid">
    <mx:Label text="Received Messages" fontWeight="bold"/>
    
    <!--
    Configure is very important.  Configure dispatches an event that instructs Parsley that you 
    wish to have this view Managed by Parsley.  If you do not include this tag or do not launch
    the configure event, Injection nor Parsley messaging will not happen in this view.
    -->
    <parsley:Configure />    
    
     <!--
     This is a simple list component that will display the messages that will be received.
     -->
    <mx:List id="messageDisplayList" dataProvider="{receivedMessages}" 
              width="100%" height="86" x="0" y="0" ></mx:List>
    
    <mx:Script>
        <![CDATA[
            import mx.collections.ArrayCollection;
            import messages.LoggerMessage;
        
            /**************************
             * Private property that holds an ArrayCollection of the messages that have 
             * been received.
             * */
            [Bindable]         
               private var receivedMessages:ArrayCollection = null;
               
               /**************************
                * This function will receive any message that is of the type
                *  LoggerMessage Notice the MessageHandler tag.  That instructs
                *  Parsley that you wish to route any dispatched message of 
                * type LoggerMessage to this function.  Parsley figures this 
                * out because of the data type of the parameter of the function 
                * automatically.  MessageHandler can also be declared in MXML.
                * */
               [MessageHandler]
               public function handleLogMessage(logMessage:LoggerMessage):void
                {
                    if (receivedMessages == null)
                       receivedMessages = new ArrayCollection();
                    receivedMessages.addItem(logMessage.message);
                }
            
        ]]>
    </mx:Script>
    
</mx:VBox> 

  Notice towards the bottom there is a function called handleLogMessage(...) above that there is the [MessageHandler] tag.  How does Parsley know when to call this function?  Simple, by the datatype that it is expecting.  Any message sent through the Parsley dispatcher, or declared to be managed by Parsley, that is of the type LoggerMessage, will be received by this function, and Parsley will call this function for you.

So here is the app running.  View source is enabled.



Well that should get you started with Parsley.  I most certainly encourage you to go and read the docs, as this barely scratched the surface of what Parsley does.

In the next article, we look at this same example but using Managed Flex/Flash Events.