Quick Dive into Parsley (Decoupled Bindings - Part 7)

This is part of a series of articles that should get you up and started using Spicesfactory's Parsley.
This is part 7.
In Part 3, I showed how to set up Parsley and showed a basic injection example.In Part 4, I showed how to send messages using Parsley that do not extend the Event class.
In Part 5, I showed how to send messages using Flex Events.
In Part 6, I showed nested contexts and object lifecycle methods.

This article builds upon what was covered in the previous examples, so if you haven't seen them, I encourage you to start with at the beginning of this series.  This article has two examples of how to use the Decoupled Bindings feature of Parsley.
 

Decoupled Binding

   Decoupled binding is a Parsley Feature that provides binding in a decoupled way.  It is not exactly like Flex bindings, as you can’t use it in an MXML object declaration, but it does allow you to create bindings between objects on different components.  Essentially, if you update one, the other one is immediately updated in a decoupled way.  That means that the binding is identified by the object type.

   Truth be told, it acts more like a regular injected object than regular bindings.  So what is the difference between “Decoupled Binding” and regular injection?  Well there are a few.  First “Decoupled Binding” does not require that the “shared” object be manage by the framework, which means it takes less resources.  Second, “Decoupled Binding” objects can be added to the context at any time and not limited to be added at context creation time.  Now I won’t go into all the details regarding “Decoupled Binding” since there is a whole section on the docs (http://www.spicefactory.org/parsley/docs/2.3/manual/) regarding this, and it’s pretty detailed.  You can go straight to section 5 here (http://www.spicefactory.org/parsley/docs/2.3/manual/bindings.php#intro) .

   One useful application of decouple bindings is to publish a current selected object to be used in a master/detail scenario.

Ok, so how do they work?

Well, you have three basic tags.  [Publish], [PublishSubscribe] and [Subscribe].
The [Publish] tag is to be used when you only have ONE publisher.  Only one component is going to update the value, all others are going to be subscribers (readers).  This is basically one way binding.
The [Subscribe] tag is for readers of the value.  They want to be updated when the Publishers updates the value, similar to read only.  You can have multiple subscribers to any publisher.
The [PublishSuscribe] tag allows you to have multiple publishers, and that means that a publisher can also be updated by some other publisher.  They are basically both, a publisher and a subscriber.  You can’t combine a [Publish] with a [PublishSubscribe] on the same type object.  If you plan to have more than one publisher on the same type, use [PublishSubscribe] on all of them.

You essentially place the [Publish] tag infront of any variable declaration that you wish to be a publisher.  Something like:

[Publish][Bindable]

public var myBroadcastingVar:SharedValueObjectClass;

When used in Flex, [Publish] and [PublishSubscribe] must also use the [Bindable] tag.

Subscribers work similarly:

[Subscribe]

public var myBroadcastedVar:SharedValueObjectClass;

Subscribers are not required to be tagged with [Bindable].

One of the great things about Decoupled Binding in Parsley is that it also can be set to use a local scope context or global (default), somewhat like messaging as explained in the previous example.  There is one difference though.  In messaging, the scope is decided only by the message handler.  With decoupled bindings the scoped is selected by the publisher and the subscriber.  You can read more about it in the docs.  You would use something like:

In the Publisher :

[Publish(scope="window")][Bindable]

public var selectedContact:Contact;

And in the subscriber:

[Subscribe(scope="window")]

public var selectedContact:Contact;

You can ask the framework to manage the published object; by default it is not managed.  To have the framework manage the object for you, you would use [Publish(managed="true")].  You can read more about this in the docs.

In this case I’m going to do two examples for the price of one.  The fist example used One Publisher, and the second example uses two publishers.

Decoupled Binding example with one Publisher

Here is the working example with view source enabled.



Here is this structure of the project.

This project is fairly simple. It has two view components called PublishView and SubscribeView.  There is also a DecoupledVO class which is the object that is going to be published and subscribed. 

Let's look at the code.  First the Value Object that will be published.

Here is DecoupledVO.as:

package VO
{
    /***************************************************************
     * This is a simple class that will hold a String that will be
     * shared among different views.  The reason to encapsulate the
     * string into a VO is that it makes it possible for Parsley to
     * identify the object by type.  You can also use Ids.  Refer
     * to Parsley docs. 
     * http://www.spicefactory.org/parsley/docs/2.3/manual/bindings.php#intro
     * 
     * For more Parsley examples visit:  artinflex.blogspot.com
     * */ 
    
    public class DecoupledVO
    {
        [Bindable]
        public var sharedString:String;
    }
}

Nothing special here.  A very simple class with a bindable string property.  This is the object that will be Published.  Why not publish just the string? Well, then you would only be able to publish one string, or have to use id's to identify each individual string.  Parsley knows how to match Publishers and Subscribers through the data type.

Ok, let's look at the publisher.

Here is PublishView.mxml:

<?xml version="1.0" encoding="utf-8"?>
<!--  This view will be set to do a decoupled binding and it will Publish the value from 
  a textInput to be able to be read by other components 
  For more examples visit:  artinflex.blogspot.com
-->
 <mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="210" height="60" borderStyle="solid" cornerRadius="3" paddingLeft="5" xmlns:parsley="http://www.spicefactory.org/parsley">
    <mx:Label  text="Publish" fontWeight="bold"/>
    <mx:TextInput width="200" id="publishingTextInput" />    
    <!--In Flex 3, for binding to be on output, we must specify it with the binding tag-->
    <mx:Binding source="publishingTextInput.text" destination="decoupledVO.sharedString" />
    
    <!--  Configure is how you tell Parsley that you want this view to become 
    part of the Context and participate in all of Parsley’s features.
    For the Publish / PublishSubscribe / Subscribe tags to be seen by Parsley
    this view must be managed. -->    
    <parsley:Configure />
    
    <mx:Script>
        <![CDATA[
            import VO.DecoupledVO;

            /*********************************************
             *     The object that will be published should have its own type to be
             *     identifiable by Parsley without ambiguity.  Alternatively you 
             *  can use IDs.  On the publishing side, Publish objects MUST also
             *  be tagged with Bindable in Flex apps.
             */ 
             [Publish]
            [Bindable]
            public var decoupledVO:DecoupledVO = new DecoupledVO();
            
        ]]>
    </mx:Script>
    
</mx:VBox>

   This component has a TextInput that is bound to the shared string of our object that we are going to publish.  Note that you must instantiate the object that will be published, most likely with new,  you control the creation, and destruction of the object.  If you wanted to have the framework manage the object you would use [Publish(managed="true")].  Note that having the framework manage the object doesn't relieve you from assigning an instance yourself.  With decoupled bindings the framework will not create the instance for you.  The advantage of having the framework manage the object for you is that the object will be able to participate in other Parsley features, such as injection and messaging.

Ok, now let's look at the subscriber.

Here is SuscribeView.mxml:

<?xml version="1.0" encoding="utf-8"?>
<!--  This view will be set to do a decoupled binding and it will Subscribe the value
  that it receives from other components and set it to a textInput.  Note that it is
  really decoupled, as it doesn't have any reference to the publishing object/view.
  For more examples visit:  artinflex.blogspot.com
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="210" height="60" borderStyle="solid" cornerRadius="3" paddingLeft="5" xmlns:parsley="http://www.spicefactory.org/parsley">
    <mx:Label  text="Subscribe" fontWeight="bold"/>
    <mx:TextInput width="200" id="subscribeTextInput" text="{decoupledVO.sharedString}" />
    
    <!--  Configure is how you tell Parsley that you want this view to become 
    part of the Context and participate in all of Parsley’s features.
    For the Publish / PublishSubscribe / Subscribe tags to be seen by Parsley
    this view must be managed. -->    
    <parsley:Configure />
    
    <mx:Script>
        <![CDATA[
            import VO.DecoupledVO;

            /*********************************************
             *     The object that will be subscribed should have its own
             *  type to beidentifiable by Parsley without ambiguity.
             *  Alternatively you can use IDs.  Bindable is not required
             *  on the Subscribe, but since I bound it to the TextInput
             *  I must include Bindable.
             */ 
             [Subscribe]
             [Bindable]
            public var decoupledVO:DecoupledVO;
            
        ]]>
    </mx:Script>
    
</mx:VBox>

   SubcribeView has a TextInput bound to the same property as PublishView.  One thing that is important is that you should not assign an instance to the var that is tagged as the subscriber, as the publisher will pass the reference to it from its own var.  But your code MUST be aware that the subscribed var can have the value of null.  There is no guarantee that the value of that var (in this case decoupledVO) will not be null for some period of time.

The main file just has both views.

Here is ParsleyDecoupledBindingsExample1.mxml:

<?xml version="1.0" encoding="utf-8"?>

<!--
This example demonstrates Parsley's Decoupled Bindings.  
For more examples visit:  http://artinflex.blogspot.com
-->

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" 
    xmlns:parsley="http://www.spicefactory.org/parsley" 
    xmlns:views="views.*"
    height="144" width="230">
<!--    
    ContextBuilder is how you tell parsley to manage objects that are not Views. 
    In this case I'm instructing Parsley to create a context.  No config file was defined
    because we are not asking Parsley to manage any particular object.  We just need to
    create at least one context.
-->
    <parsley:ContextBuilder />
    <mx:VBox x="10" y="10" height="100%">
        <views:PublishView>
        </views:PublishView>
        <views:SuscribeView>
        </views:SuscribeView>
    </mx:VBox>
    
</mx:Application>

Now let's look at the example with two publishers.

Decoupled Binding example with two Publishers

   The previous example assumes that you only have one potential publisher, and remember that when you use [Publish] you can only have one publisher per datatype within the same scope.

  So what happens if you wish to have two publishers?  Well you use [PublishSubscribe] and in fact your publisher is also a subscriber.

Let's look at the example running (view source is enabled).



Here is the structure of the project:

   This example has three views. One that acts as a Publish only, one that is a Publisher and Subscriber, and a Subscriber only. The keyword here is "acts", since it does use PublishSubscribe, but through my own code it behaves as it was only a Publisher.  Other than that it is basically the same as the above example.

   Let's look a the code. I won't include the code to the DecoupledVO.as as it identical to the example above.

   So what does the PublishView.msml look like?

<?xml version="1.0" encoding="utf-8"?>
<!--  This view will be set to do a decoupled binding and it will Publish the value from 
  a textInput to be able to be read by other components. 
  For more examples visit:  artinflex.blogspot.com
-->
 <mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="210" height="60" borderStyle="solid" cornerRadius="3" paddingLeft="5" xmlns:parsley="http://www.spicefactory.org/parsley">
    <mx:Label  text="Publish" fontWeight="bold"/>
    <mx:TextInput width="200" id="publishingTextInput" />    
    <!--In Flex 3, for binding to be on output, we must specify it with the binding tag-->
    <mx:Binding source="publishingTextInput.text" destination="decoupledVO.sharedString" />
    
    <!--  Configure is how you tell Parsley that you want this view to become 
    part of the Context and participate in all of Parsley’s features.
    For the Publish / PublishSubscribe / Subscribe tags to be seen by Parsley
    this view must be managed. -->    
    <parsley:Configure />
    
    <mx:Script>
        <![CDATA[
            import VO.DecoupledVO;

            /*********************************************
             *     The object that will be published should have its own type to be
             *     identifiable by Parsley without ambiguity.  Alternatively you 
             *  can use IDs.  On the publishing side, Publish objects MUST also
             *  be tagged with Bindable in Flex apps.
             *  In this case, since I wish to have multiple publishers of the same
             *  object type, I can't use Publish.  Only ONE object can be set to
             *  Publish.  Therefore I must use PublishSubscribe.  I limit it to
             *  Publishing only through the binding of the TextInput being one way.
             */ 
             [PublishSubscribe]
            [Bindable]
            public var decoupledVO:DecoupledVO = new DecoupledVO();            
        ]]>
    </mx:Script>    
</mx:VBox>

   Well, not much changed from the example above that had only one publisher.  The only difference (besides the comments) is the [PublishSubscribe] tag that replaced the [Publish] tag.  When you run the example you will notice that the TextInput doesn't get updated in the PublishView.  Technically speaking, when the other PublishSubscribeView updates the DecoupledVO, the local decoupledVO object in this view, does get updated, but the TextInput doesn't, simply because I set the binding from the TextInput to the decoupledVO as a one way road, simple trick (take a look at the <Binding> statement.

  SubscribeView is identical to the previous example, nothing changed there.

  Ok, so now let's look at the PublishSubscribeView.mxml:

<?xml version="1.0" encoding="utf-8"?>
<!--  This view will be set to do a decoupled binding and it will Publish and
  subscribe the value from a textInput to be able to be read by other components
  and receive its value from another component. 
  For more examples visit:  artinflex.blogspot.com
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="210" height="60" borderStyle="solid" cornerRadius="3" paddingLeft="5" xmlns:parsley="http://www.spicefactory.org/parsley">
    <mx:Label  text="Publish and Subscribe" fontWeight="bold"/>
    <mx:TextInput width="200" id="publishingSubscribeTextInput" />    
    <!--In Flex 3, for binding to be on output, we must specify it with the binding tag-->
    <mx:Binding source="publishingSubscribeTextInput.text" destination="decoupledVO.sharedString" />
    <mx:Binding destination="publishingSubscribeTextInput.text" source="decoupledVO.sharedString" />
    
    <!--  Configure is how you tell Parsley that you want this view to become 
    part of the Context and participate in all of Parsley’s features.
    For the Publish / PublishSubscribe / Subscribe tags to be seen by Parsley
    this view must be managed. -->    
    <parsley:Configure />
    
    <mx:Script>
        <![CDATA[
            import VO.DecoupledVO;

            /*********************************************
             *     The object that will be published and subscribed should have
             *  its own type to be    identifiable by Parsley without ambiguity.
             *  Alternatively you can use IDs.  On the publishing side,
             *  Publishing objects MUST also be tagged with Bindable in Flex apps.
             */ 
             [PublishSubscribe]
             [Bindable]
            public var decoupledVO:DecoupledVO = new DecoupledVO();
            
        ]]>
    </mx:Script>    
</mx:VBox>

   The PublishSubscribe view is nearly identical to the PublishView, besides the properties being renamed, the main difference is that binding is set to be bi-directional.  This makes the TextInput get updated when the decoupledVO get's updated.

  A very important note:  When you have have one publisher it is pretty obvious which view must instantiate the original object that gets passed by reference to all the subscribers.  When you have multiple PublishSubscribe elements on different views, it is not so obvious.  Technically speaking only one needs to create the instance and all others will receive a reference to that instance, but it is not always obvious which one should be the one with that responsibility, as this example demonstrates.  You can technically figure it out, it should be the last one that joins in, as it will publish it's own instance last and hence it will pass it's reference to all others, and replacing what ever they had.  If you want to be on the safe side you can just assign some instance to all the PublisherSubscribe elements as I did in this example.  Eventually the instances not used will get garbage collected anyways, as there will no longer be a reference to them.

  This is a drawback of using decoupled bindings in comparison with regular Parsley managed objects.  Decoupled bindings does not go through the full sanity checks that regular context created objects do.  If you have a view with a PublishSubscribe tag that joins in at a latter time, it will replace whatever value was already being shared.  I have created an example that shows this behavior.  I have source enabled, but I won't go into the details of the example, it's just so you can play with it.

Here is that example with view source enabled:



Well I certainly hope that these examples were useful, more to come soon.

Next in the series is: Parsley's Dynamic Command and Dynamic Objects.