You can download this Quick Start as a [Flash Builder FXP|^swiz_quickstart.fxp] or [Zip file|^swiz_quickstart.zip].
h4. A Lightning Look at Configuration
Configuring Swiz in your Flex or AIR application is very straightforward: declare {{Swiz}}, define the {{beanProviders}} and {{config}} properties, and optionally define one or more {{loggingTargets}} to view debugging messages. Here is an example:
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_main.xml"></script>{html}
\\
Non-visual components that you want Swiz to manage are defined in a {{BeanProvider}} tag. Any beans that you define within the {{BeanProvider}} are processed by Swiz for dependency injection and the creation of event mediatorshandlers. In the following example, a {{UserService}} and a {{UserController}} are created:
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_beans.xml"></script>{html}
h4. The "Big Three": Dependency Injection, Event Handling, and Server Interaction
The three most commonly used features of Swiz are its dependency injection capabilities, its event handling features, and its server interaction utilities. Let's look at how each of these work.
h4. Adding Dependency Injection
Dependencies are injected by using {{\[Inject\]}} metadata. In this example, the {{UserService}} is injected into the {{UserController}}:
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_usercontroller.java"></script>{html}
\\
In addition to injecting a bean, you can inject individual bean properties. In this example, the {{currentUser}} property of the {{UserController}} is injected into a {{UserForm}} visual component. Note that it is not necessary for the {{UserForm}} to be declared as a bean in the {{BeanProviders}} tag. When visual components are added to the display list, Swiz automatically inspects them and processes any metadata tags that are found.
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_userform.xml"></script>{html}
h4. Dispatching and Handling Events
When using Swiz, you dispatch standard Flex events. In this example, we've expanded the {{UserForm}} to create and dispatch an event when the form button is clicked. Swiz listens for events being dispatched within the display list and handles them automatically.
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_userform2.xml"></script>{html}
\\
A look at the {{UserEvent}} confirms that this is just a simple, standard event. The only thing to note here is that the event has {{bubbles}} set to {{true}}. This allows the event to bubble up the display list so that it can be handled by Swiz:
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_userevent.java"></script>{html}
\\
We've seen how to dispatch events from the display list, but how do we handle the events? Swiz provides a {{\[MediateEventHandler\]}} metadata tag to do this. In the example below, we have expanded the {{UserController}} to add an aevent mediatedhandler method. In this case, when Swiz encounters an event of type {{UserEvent.SAVE_USER_REQUESTED}}, it will automatically invoke the {{saveUser}} method in the {{UserController}}. By specifying a value of "user" for the {{properties}} attribute, Swiz will locate the {{user}} property in the {{UserEvent}} and pass this as a parameter to the mediatedhandler method:
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_usercontroller2.java"></script>{html}
\\
One last feature to note regarding event dispatching. We've seen how an event dispatched from the display list will bubble up until it is processed by Swiz. But what about dispatching events from non-visual components like controllers and services? Swiz offers the {{\[Dispatcher\]}} metadata tag to meet this need. In the {{UserService}} shown below, Swiz will automatically inject an event dispatcher into the {{dispatcher}} property. Any events dispatched though this dispatcher will also be processed by Swiz and trigger any event mediatedhandler methods associated with the event:
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_userservice.java"></script>{html}
h4. Talking to the Server
Our {{UserController}} can now respond when a save user event is dispatched. The final piece of the puzzle is having the application make a call to the server to actually save the user in a database. Typically, Flex requries you to manually create {{Responder}} objects to attach to {{AsyncTokens}} that will handle {{ResultEvent}} and {{FaultEvent}}. Swiz offers some helpful features to sidestep these manual processes. Below, you see the final version of our {{UserController}}. Because it has the Swiz helper object {{ServiceHelper}} injected, we can use its {{executeServiceCall()}} method. This method will automatically obtain the {{AsyncToken}} for the RPC call and create {{Responder}} objects. In this case, we call {{userService.saveUser()}}, and specify {{handleSaveUserResult}} to handle the successful response from the server. Although it is not shown here, we can also specify a method to use as the fault handler.
{html}<script src="http://gist.github.com/383055.js?file=quickswiz_usercontroller3.java"></script>{html}
\\
h4. There's More Where That Came From
This quick tour has shown how easy it is to configure Swiz and use its core features. But Swiz offers much more than this! Please read the [User Guide], [Best Practices], and [Advanced Topics] to learn more.
|