Quick Dive into Parsley (Basic Injection Example - Part 3)

This is part of a series of articles that should get you up and started using Spicesfactory's Parsley.
This is part 3.
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.  If you are very new to Parsley or new to IOC, you are strongly encouraged to read through Part 2.
In Part 4, we will look at a simple Messaging example.

In this article will look at a very basic example to get the idea of how Injection works in Parsley.

Parsley Basic Injection Example

Parsley works with Flex 3, Flex 4, and Flash.  I will show examples using Flex 3 projects because they can easily be imported into Flex 4, sorry Flash users.  You can still get the idea but I'm going to have to send you back to the docs.  Flex 4 users must note that when building a Flex 4 project and when adding non visual components in MXML, they go in between the <fx:Declarations> </fx:Declartions> tags

Download Parsley

If you haven't downloaded Parsley yet, you should.  You can download it here.  As of this writing the current version of Parsley is 2.3.0.   You can download the source code, but we will be working with the compiled SWC files.

Setting up Parsley

Parsley's zip download includes a release folder.  In that folder you will find five SWC files.  You only really need two of those, one for Spicelib (which Parsley uses) and one for Parsley itself.  Which ones you use, depends on what tool/framework you are using.

For example if you are using Flex 3, you would use the parsley-flex3-2.3.0.swc and the spicelib-flex-2.3.0.swc; if you are using the Flex 4 framework you would use parsley-flex4-2.3.0.swc and spicelib-flex-2.3.0.swc files.

So, now that you have selected the two files that you need, simply copy them to the "libs" folder of your FlexBuilder's project.  That's it.  Parsley is ready to be used in that project.  If you don't have a "libs" folder already in your project, you can go to the Project Properties and select Flex Build Path on the left, then select the Library Path tab on the right side.  Add a swc folder and make sure it is set to Merge into Code as the link type.

Using Parsley
Now that Parsley is ready to go let's look at how you actually use it.  If you recall from the previous article, for Parsley to be able to help you, it needs to be told what objects you wish for it to manage.  You do that with the <ContextBuilder /> tag.  You should include the <ContextBuilder /> in any view that you wish to be the "root" of any context.  For our simple example we will include the <ContextBuilder /> tag in the main application file.  This basically creates something similar to an application wide singleton.  The <ContextBuilder /> tag has several options, but one of the most important is the config option.  Config basically tells the ContextBuilder where is the file that has the description of what objects you wish to have Parsley manage.  The config file can be either MXML or XML.  Having the file in MXML has the benefit of making sure that the classes that you wish Parsley to mange do get linked into the final swf.

So here is an example.  In my main application MXML file I would have the following:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" 
    width="280" height="128" 
    xmlns:views="view.*" xmlns:parsley="http://www.spicefactory.org/parsley"
    viewSourceURL="srcview/index.html"> 
 
    <parsley:ContextBuilder config="BasicExampleContextConfig" />    
</mx:Application>
    

Now let's look at what a Context config file looks like.  This is what my "BasicExampleContextConfig.mxml" looks like:

<?xml version="1.0" encoding="utf-8"?>
    <!--
    This is the file that declares which objects you wish to manage through Parsley.
    Any object declared within the Object Tag will be allowed to participate in any of Parsley's 
    features.  This is a Simple MXML implementation, but this can also be declared in and XML file.
    -->

<mx:Object
    xmlns:mx="http://www.adobe.com/2006/mxml"  
    xmlns:model="model.*">
<!--    
Withing the object tags you declare de objects.  In this case I'm just including the basic 
Model class    
-->    
    <model:BasicModel />    
</mx:Object>

Now if you simply ignore all the comments, it's just and <Object> <BasicModel /> </Object>.
That's it.  Parsley will now create an instance of the class BasicModel and manage that instance for you.
Flex 4 users.  Remember that non visual elements must go in between <fx:Declarations> </fx:Declartions> tags so, the Context config file would look like this.

<?xml version="1.0" encoding="utf-8"?>
    <!--
    This is the file that declares which objects you wish to manage through Parsley.
    Any object declared within the Object Tag will be allowed to participate in any of Parsley's 
    features.  This is a Simple MXML implementation, but this can also be declared in and XML file.
    -->
    
<mx:Object
    xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:model="model.*">
    
    <fx:Declarations>
            <!--    
            Withing the object tags you declare de objects.  In this case I'm just
            including the BasicModel class    
            -->    
        <model:BasicModel />    
        
    </fx:Declarations>
</mx:Object>

You are probably wondering what is in the BasicModel class.  Well, nothing fancy.  Basic Model can be any class that you want Parsley to manage for you.  When we talk about being managed by Parsley it means that it has access to Parsleys features; that includes: messaging, being created and destroyed automatically, and Injection, among other things.  So let's look at it.

package model
{
    /*********************************************************************
     * BasicModel is a very simple class to demonstrate the Shared Model
     * Concept.  It contains a Bindable String and a Bindable Integer
     * That will be shared by different views.
     * ******************************************************************/
    public class BasicModel
    {
    /*********************************************************************
     * Constructor    
     * ******************************************************************/
        public function BasicModel()
        {
        }

        [Bindable]
        public var sharedString:String;   // The string to be shared
        
        [Bindable]
        public var sharedInteger:int;    // The integer to be shared
    }
}

Notice that the constructor is not taking any parameters. If the constructor was taking parameters, it could still be managed by Parsley and declared in the MXML context config file, but more on that on a different article.

Great, so now we have a class that is being managed by Parsley.  So what can we do with it.  Well, let's inject it somewhere.
I'll create a small view called "ViewOne", which will be a VBox that will hold 3 elements.  The first a CheckBox that will be checked once our object has been injected, the second a TextInput that will be bound to the sharedString of our BasicModel, and finally a NumericStepper that will be bound to our BasicModel's sharedInteger property.
So here is ViewOne:

<?xml version="1.0" encoding="utf-8"?>
<!--
This is a simple view that will have our BasicModel Object injected into it.
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" width="128" height="82" xmlns:parsley="http://www.spicefactory.org/parsley">

    <!--
    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 will not happen in this view.
    -->
    <parsley:Configure />
    
<!--
    This CheckBox simple get's a check once the Basic Model has been injected.  If no injection has
    occured, the value will be null
-->    
    <mx:CheckBox label="BasicModel Ready" width="100%" enabled="false" selected="{sharedBasicModel != null}"/>

<!--
    The Text input will access the shared string of our model.  I'll use two 
    directional Binding so that it will be updated when it's changed on any other view.
    Note that Flex 3.x Binding is only one way by default.
-->        
    <mx:Binding destination="sharedTextBox.text" source="sharedBasicModel.sharedString" />
    <mx:Binding destination="sharedBasicModel.sharedString" source="sharedTextBox.text" />    
    <mx:TextInput width="100%" id="sharedTextBox"/>
    
<!--    
    The Numeric stepper will access the shared integer of our BasicModel.    I'll use two 
    directional Binding so that it will be updated when it's changed on any other view.
    Note that Flex 3.x Binding is only one way by default.
-->
    <mx:Binding destination="sharedStepper.value" source="sharedBasicModel.sharedInteger" />
    <mx:Binding destination="sharedBasicModel.sharedInteger" source="sharedStepper.value" />
    <mx:NumericStepper width="100%" id="sharedStepper" />


    <mx:Script>
        <![CDATA[
            import model.BasicModel;
   
    /*****************************************************************************
     * sharedBasicModel is the property accesible within this view that will have
     * the shared BasicModel injected into it.  Parsley figures out what to inject
     * because of the Class Type.
     * Parsley doesn't care if it's Bindable or not.  I've declared it Bindable
     * so that I could bind it to some Flex Components
     * The [Inject] metatag is what instructs parsley inject the shared object. 
     * **************************************************************************/    
            [Inject]
            [Bindable]
            public var sharedBasicModel:BasicModel;            
        ]]>
    </mx:Script>
</mx:VBox>

Towards the bottom in the Script section is where Parsley gets involved.  Notice that both the Stepper and the TextBox are bound to a local property called "sharedBasicModel".  It's local right, but above the declaration for sharedBasicModel you have two tags, one the [Bindable] so that binding works and the second one is the [Inject] tag.  Parsley reads this [Inject] tag and looks through the current context to see if it is managing any class of the type "BasicModel", if it is, then it assigns (injects) it's managed object into this local variable.   

VERY IMPORTANT NOTE:  For injection to work, the property to be injected must be public, otherwise it can't be assigned from outside this class.

Now, Parsley doesn't do look for the [Inject] or any other tag in every view, it does this only for the views that you tell it to do so.  And you tell it with the <Configure /> tag.  This tag simply launches a bubling event that Parsley catches and proceeds to manage this view also.  Without this, injection will not work.  Note: You can instruct Parsley to manage All views automatically without the need to use the <Configure /> tag, but more on that on a later time.

That's it.  All you have to do is add this view as child of the view that has the context and it will work.
Notice how there is almost nothing different from how you would do this with manual dependency injection.  Parsley doesn't make you extend anything or write a bunch of code to get things working.

And this is what our projects structure looks like if you copied and pasted the code:

Now that we have a view, well let's go back to the Main app file (in my case it's ParsleyBasicExample1.mxml and add two views to see it work.
Here is the "final" version of the main file.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" 
    width="280" height="128" 
    xmlns:views="view.*" xmlns:parsley="http://www.spicefactory.org/parsley" viewSourceURL="srcview/index.html">
    
<!--    
    This is a very simple application which demonstrates how to set up
    Parsley's managed Dependency Injection.
    
    It uses one shared object named BasicModel that you must instruct Parsley
    that you wish for it to manage it. This is accomplished with the ContextBuilder
    tag found below.  Parsley will ONLY manage objects that you instruct it to do.
    
    In this example there is one class, that has two instances.  Each instance will have
    the shared object injected into them, which means that if you updated the shared 
    object in one view, it will be udated in ALL views that share that same object.
-->    
    <mx:VBox width="95%" height="100%" horizontalCenter="0" horizontalAlign="center">
        <mx:Label text="Parsley Basic Example 1"   fontWeight="bold" fontSize="13"/>
        <mx:HBox x="0" y="0" width="100%">
            <views:ViewOne id="firstInstanceViewOne">
            </views:ViewOne>
            <views:ViewOne id="secondInstanceViewOne">
            </views:ViewOne>
        </mx:HBox>        
    </mx:VBox>
    
<!--    
    ContextBuilder is how you tell parsley to manage objects that are not Views.  If
    you wish to have Parsley manage a View, you do that through the Configure tag.  The 
    Configure Tag is being used in the ViewOne component.
    In this case I'm instructing Parsley to load the BasicExampleContextConfig file which
    has the "list" of objects you wish to have managed.
    In Parsley you can have nested Contextes, I will show that in another example project.
-->    
    <parsley:ContextBuilder config="BasicExampleContextConfig" />
    
</mx:Application>

Nothing really new Parsley related, just added two ViewOnes.

What happens is that any change done in one view is immediately copied on to the other view.

And here is the application running.  View source is enabled.



It's a very simple example well that doesn't do much more than simply illustrate some of the basic concepts.

You can also download the source code here.

As I have said before, it's fairly easy to take this application out of Parsley.  In the ViewOne all I would need to do is remove the <Configure /> tag.  The main application would look more like this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" 
    width="280" height="128" 
    xmlns:views="view.*" xmlns:parsley="http://www.spicefactory.org/parsley" viewSourceURL="srcview/index.html">
    
<!--    
    This is a very simple application which demonstrates how to set up
    Parsley's managed Dependency Injection.
    
    It uses one shared object named BasicModel that you must instruct Parsley
    that you wish for it to manage it. This is accomplished with the ContextBuilder
    tag found below.  Parsley will ONLY manage objects that you instruct it to do.
    
    In this example there is one class, that has two instances.  Each instance will have
    the shared object injected into them, which means that if you updated the shared 
    object in one view, it will be udated in ALL views that share that same object.
-->    
    <mx:VBox width="95%" height="100%" horizontalCenter="0" horizontalAlign="center">
        <mx:Label text="Parsley Basic Example 1"   fontWeight="bold" fontSize="13"/>
        <mx:HBox x="0" y="0" width="100%">
            <views:ViewOne id="firstInstanceViewOne" sharedBasicModel="{myBasicModel}">
            </views:ViewOne>
            <views:ViewOne id="secondInstanceViewOne" sharedBasicModel="{myBasicModel}">
            </views:ViewOne>
        </mx:HBox>        
    </mx:VBox>

<mx:Script>
    <![CDATA[
        import model.BasicModel;
        var myBasicModel:BasicModel = new BasicModel();
    ]]>
</mx:Script>
    
<!--    
    ContextBuilder is how you tell parsley to manage objects that are not Views.  If
    you wish to have Parsley manage a View, you do that through the Configure tag.  The 
    Configure Tag is being used in the ViewOne component.
    In this case I'm instructing Parsley to load the BasicExampleContextConfig file which
    has the "list" of objects you wish to have managed.
    In Parsley you can have nested Contextes, I will show that in another example project.
-->    

<!--   Removed for demonstrating a non Parsley implementation
    <parsley:ContextBuilder config="BasicExampleContextConfig" />
-->    
</mx:Application>

Notice that I commented out the <ContextBuilder />  tag and had to declare a variable (myBasicModel) that I had to inject manually into both views, but the underlying structure did not change.  The point I wanted to illustrate here is that to take advantage of Parsley you don't have to follow a specific patter or structure, Parsley just makes your life easier and it will adapt to any structure or patter you wish to implement.

Well, that's it for this example.  In the next example we will take a look at messaging.