ActionScript Developer's Guide to Robotlegs

Table of contents

1. A Note Regarding Supplemental Files
2. Preface
   1. Robotlegs: Something a little bit special
   2. Who this book is for
   3. Who this book is not for
   4. Conventions used in this book
   5. Using code examples
   6. Safari® Books Online
   7. How to contact us
   8. Acknowledgments
3. 1. Robotlegs is a lightweight framework for ActionScript 3
   1. What does Robotlegs actually do?
      1. Robotlegs is a communication-and-cooperation framework
         1. Direct conversation
         2. Passing messages
         3. Robotlegs helps with direct conversations and message passing
      2. Robotlegs makes use of three object-oriented architectural patterns
   2. Do you need a framework at all?
      1. Reasons to use a framework
         1. Consistency
         2. Common understanding brings easier collaboration
         3. Peer-reviewed solutions
         4. A well-tested skeleton
         5. Less code to write
      2. Reasons not to use a framework
         1. Framework learning curve
         2. Terminology confusion
         3. Performance tradeoffs
         4. Framework coupling
         5. ‘Black box’ code is hard to debug
      3. Robotlegs aims to amp up the pros and minimize the cons
   3. Less boilerplate code is a good thing...
4. 2. The Robotlegs dream...
   1. 80% of the problems can be solved with 20% of the API
   2. Coding for Robotlegs shouldn’t tie you to the framework
   3. Robotlegs aims to enable and not dictate
   4. Most AS3 applications benefit from the MVCS approach
   5. Testing, testing! (We test, and we make it easy for you to test)
   6. Some final things every Robotlegs cadet should know
5. 3. Anatomy of a Robotlegs application
   1. Joel’s Personal Kanban
   2. Lindz’s Mosaic Design Tool
   3. How a Robotlegs application gets things done
      1. Architecture begins with Events and Commands
   4. Getting to grips with Robotlegs architecture
      1. The ‘context’ is the heart of your Robotlegs application
      2. Your models and services are ‘Actors’ in your app
      3. The MediatorMap provides a way to join your views to your app layer
      4. Robotlegs mediators are bridges, not view controllers
      5. The CommandMap makes things happen
      6. The shared event dispatcher joins everything together
         1. ... and it goes a little something like this (event flow)
   5. User stories as implemented in Robotlegs
      1. Personal Kanban example: Moving a task from ‘backlog’ to ‘doing’
      2. Mosaic Design Tool example: Saving a design
      3. The same but different
   6. All of this is possible because of the Robotlegs Injector
6. 4. Automated Dependency Injection
   1. So, what exactly is Automated Dependency Injection?
      1. A dependency is just a requirement to use another object
      2. You can fulfil a dependency in three different ways
   2. You already use Dependency Injection
   3. There are different ways to inject dependencies
      1. Statics and globals make code rigid, brittle, hard to test, and prone to memory leaks
      2. Locator patterns push extra responsibilities on your classes
   4. Automated DI gets around the need to ‘pass the parcel’, but keeps code flexible
   5. How does Robotlegs Injection work?
      1. Automated DI is a handshake
         1. You can specify an injection point in three ways
         2. And you also have to tell the injector what you would like it to do
      2. Robotlegs has different types of injection
         1. If you only want one instance, use mapSingleton
         2. mapSingletonOf keeps your code coupled only to interfaces
         3. What if my class has to be created elsewhere? (e.g. a factory)
         4. Named rules let you create multiple rules for each class (but they’re icky)
      3. You need to tell the compiler to include the injection metadata
         1. FlashBuilder/FlexBuilder solution
         2. Flash CS4/CS5 IDE Solution
         3. IntelliJ Solution
         4. Flex SDK Solution—command line compiling
         5. Flex SDK Solution—compiling with ant
      4. Automated Injection ‘Gotchas’
         1. If an object has an [Inject]ed dependency you have to create it using the Injector.
         2. You can map injection rules at runtime, but beware of race conditions.
         3. The injection point and rule have to be of exactly the same type
         4. If you override a method that has an [Inject] tag, you need to add it in the subclass
7. 5. The Robotlegs context in action
   1. Provide the context with a root-view
   2. Ask it to run startup()—immediately or when you’re ready
   3. Use startup() to provide your injection rules, map your mediators to views and commands to events
   4. Shutting down a Context
   5. Now you have some Context
8. 6. The CommandMap in action
   1. A Command is a concise single-purpose controller object
   2. Commands are triggered by events
   3. Commands can be any class with an ‘execute’ method
   4. Commands should do their thing and then die
   5. Commands rely on their injections to be useful
      1. You can inject the event that triggered the command
   6. Commands know about the injector, command map, mediator map and context view
   7. Commands can also dispatch events
   8. Great command names pay dividends
   9. Use helper classes for shared logic
   10. Detain and release when you need your command to hang around
9. 7. Models and services: How are they different?
   1. Models and Services usually extend Actor
   2. They don’t listen, they only talk
   3. Use your API through a Command
   4. Distinguishing Models from Services
   5. Classes that don’t dispatch events to the shared event dispatcher don’t need to extend Actor
   6. Configuring services
      1. Configuring services using a command
      2. Configuring services by injecting the configuration
   7. Working with non-Actor models and services (including third party code)
      1. Wrap them in an Actor
      2. Use the command that acts upon them to dispatch the events
   8. Model design tips for Robotlegs
      1. Keep those responsibilities separated
      2. Use strong-typed wrappers for collections
      3. Never create mutually dependent models
   9. Managing the relationships between models and services
10. 8. Connecting views with Mediators
    1. Introducing the MediatorMap
       1. Wiring views with the MediatorMap
    2. Mediating your view components
       1. Mediators are created when your view hits the stage
       2. Mediator Structure
       3. Avoid logic in your Mediators
       4. Do your wiring in onRegister()
       5. Using the EventMap
          1. Use the ‘eventClass’ parameter to make mappings that are type safe
       6. You can do manual clean-up in onRemove
    3. Why can’t Mediators be injected into other objects?
    4. Working with complex composite views
    5. Using the same mediator with more than one view
    6. A good Mediator is just a mailman
       1. Signs that you need another mediator
       2. Never put view logic into the mediator.
11. 9. Working with Robotlegs: Rich Examples
    1. Feature implementation walk-through: Mosaic Tool
       1. Challenge 1: Keeping things on a need-to-know basis
       2. Challenge 2: Keeping the view snappy
       3. Keeping the models in line with the visual design
          1. The crucial Robotlegs mappings that tie it all together
          2. The tile color update again, but this time with code
    2. Feature implementation walk-through: Personal Kanban App
       1. How new tasks are entered
          1. The crucial Robotlegs mappings that make this sequence work
          2. Adding a new task again, but this time with code
    3. Wait, I want more examples!
12. 10. Testing your Robotlegs application
    1. Your test provides the injections
    2. Testing models
    3. Testing services
    4. Testing commands
    5. Testing mediators
       1. Testing that an event dispatched by the view results in the correct event being dispatched on the shared event dispatcher
       2. Testing that an event received on the shared event dispatcher results in an action on the view
13. 11. Power-ups
    1. Bootstraps can break up fat contexts
    2. The ContextEvents help keep control
    3. Tag methods with [PostConstruct] to run them after injection is complete
    4. Use Signals between complex views and their mediators
    5. Modular and multiple-context Robotlegs
       1. ModuleEventDispatcher and child injectors make it work
    6. Extend Robotlegs with utilities and add-ons
    7. ViewMap—injection for your views
    8. Mediator map performance
14. A. Troubleshooting tips
    1. Problem: Injection doesn’t occur
       1. Broken injection point declaration
       2. Metadata is being stripped by the compiler
       3. Instantiating an object with injected dependencies using new
       4. Injected properties are null in constructor
    2. Problem: Things work for a while and then mysteriously stop
    3. Problem: Event dispatch does not work as expected
    4. Problem: Mediator isn’t running onRegister
       1. Make mediator mappings from the inside out
    5. Problem: Handlers in the mediator are running repeatedly
    6. Error: Injector missing rule for X
       1. Missing injection mapping
       2. Inconsistent injection mapping
    7. Warning: Duplicate mapping in the injector
    8. Error: Call to a possibly undefined method X
    9. Where to get more help
15. B. Swiftsuspenders: The power behind the Robotlegs Injector
    1. What does Swiftsuspenders actually do?
    2. We think limited metadata is a good thing
16. About the Authors
17. Colophon
18. Copyright