6. Create mediators

Create a mediator

A mediator class has a relation one-to-one to a view. Its unique purpose is to connect a single view to the framework without having the view to know about it.

Mediators can be created with or without using injection.

Because Mediator is extending Wire, it will have all the connections to the framework that a wire can have.

The main difference is that its creation and removal is automated and handled by the framework.

Using mediator is very powerful, it is simple and quick to manage views regardless of the depth and structure of your views. That also means that an application can be built and the mediators added at a later point if needed, very flexible.

package {
	import com.soma.core.interfaces.IMediator;
	import com.soma.core.mediator.Mediator;

	public class MySpriteMediator extends Mediator implements IMediator {
		
		override public function initialize():void {
                        // called when the mediator has been registered to the framework
			trace("my view", viewComponent);
		}

		override public function dispose():void {
			// called when the mediator has been removed from the framework
		}
		
	}
}

Map a view to a mediator

To allow the framework to create a mediator for a type of view, you must map the view to a mediator class, this can be done in four places:

• in the framework instance
• in a wire instance
• in a mediator instance
• in a command instance

In either place, a view can be mapped this way:

mediators.mapView(MySprite, MySpriteMediator);

Test if a view instance has a mediator

Using an instance of a view, you can test if a mediator class has been created for this specific view.

if (mediators.hasMediator(mySprite)) {
    // do something
}

Test if a view has been mapped to a mediator

You can also test is a type of view has been mapped to a mediator

if (mediators.isMapped(MySprite)) {
    // do something
}

Unmap a view

To stop the framework from creating a mediator for a view, you can remove this mapping. Note that it will throw an error if the mapping doesn’t exist.

mediators.removeMapping(MySprite);

How and when is a mediator created?

The creation of the mediator is triggered when the view mapped to this mediator is added to a display list.

To repeat the steps, the first is to map the view to a mediator class:

mediators.mapView(MySprite, MySpriteMediator);

And the second step is to create and add the view to a display list, in any DisplayObjectContainer:

addChild(new MySprite());

At this moment, three actions will happen in this precise order:
1. the mediator instance is created
2. the view is registered to the viewComponent property of the mediator
3. the initialize method of the mediator is called

package {
	import com.soma.core.interfaces.IMediator;
	import com.soma.core.mediator.Mediator;

	public class MySpriteMediator extends Mediator implements IMediator {
		
		override public function initialize():void {
                        // called when the mediator has been registered to the framework
			trace("my view", viewComponent);
		}

		override public function dispose():void {
			// called when the mediator has been removed from the framework
		}
		
	}
}

How and when is a mediator removed?

The removal of the mediator is triggered when the view mapped to this mediator is removed from a display list.

removeChild(mySprite);

At this moment, three actions will happen in this precise order:
1. the dispose method of the mediator is called
2. the internal properties of the mediator are destroyed (such as the property viewComponent)
3. the mediator is destroyed

Retrieve a mediator instance

If needed, you can also retrieve a mediator using its corresponding view from another place.

var mediator:IMediator = mediator.getMediatorByView(mySprite);

Using injection

Using injection or not is pretty similar for the mediator mechanic itself. The main difference is that you can inject the view yourself so you don’t have to cast the viewComponent property, and inject other framework elements.

And remember, as in a wire, you can still listen to events in your mediator to update you view.

Here is an example taken from the Hello World demo, the MessageEvent.READY event is dispatched from a model. The mediator can listen to this event and update its view accordingly. This would work the same way, without adding code, even if you create a hundred of views.

package com.soma.core.demo.helloworld.mediators {
	import com.soma.core.demo.helloworld.controller.events.MessageEvent;
	import com.soma.core.demo.helloworld.views.MessageView;
	import com.soma.core.interfaces.IMediator;
	import com.soma.core.mediator.Mediator;

	public class MessageViewMediator extends Mediator implements IMediator {
		
		[Inject]
		public var view:MessageView;
		
		override public function initialize():void {
			addEventListener(MessageEvent.READY, messageReady);
		}

		private function messageReady(event:MessageEvent):void {
			view.updateMessage(event.message);
		}
		
		override public function dispose():void {
			removeEventListener(MessageEvent.READY, messageReady);
		}

	}
}