@robotlegsjs/core

RobotlegsJS

RobotlegsJS is a architecture-based IoC framework for JavaScript/TypeScript. This version is a direct port from the ActionScript 3.0 codebase. See the motivation behind it.

Right now, this framework have extensions for pixi.js v4 and phaser-ce v2.8.

Features

• Dependency injection (through InversifyJS)
• Command management
• View management

Extensions

• RobotlegsJS-Macrobot: extends commands, adding support to async and macro commands.
• RobotlegsJS-SignalCommandMap: maps SignalsJS to commands.
• RobotlegsJS-Pixi: integrate RobotlegsJS with PixiJS.
• RobotlegsJS-Pixi-Palidor: a view manager extension for RobotlegsJS-Pixi.
• RobotlegsJS-Pixi-SignalMediator: a port of Robotlegs SignalMediator Extension to TypeScript.
• RobotlegsJS-Phaser: integrate RobotlegsJS with Phaser.
• RobotlegsJS-Phaser-SignalCommandMap: maps Phaser.Signal to commands.

Installation

You can get the latest release and the type definitions using npm:

npm install @robotlegsjs/core reflect-metadata --save

RobotlegsJS requires TypeScript 2.0 and the experimentalDecorators, emitDecoratorMetadata, types and lib compilation options in your tsconfig.json file:

{
    "compilerOptions": {
        "target": "es5",
        "lib": ["es6", "dom"],
        "types": ["reflect-metadata"],
        "module": "commonjs",
        "moduleResolution": "node",
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Quickstart

Creating A Context

To create a Robotlegs application or module you need to instantiate a Context. A context won't do much without some configuration.

let renderer = PIXI.autoDetectRenderer(800, 600, {});
let context = new Context()
        .install(MVCSBundle)
        .configure(MyAppConfig, SomeOtherConfig)
        .configure(new ContextView((<any>this.renderer).plugins.interaction));

We install the MVCSBundle, which in turn installs a number of commonly used Extensions. We then add some custom application configurations.

We pass the instance "this" through as the "contextView" which is required by many of the view related extensions. It must be installed after the bundle or it won't be processed. Also, it should always be added as the final configuration as it may trigger context initialization.

Note: You must hold on to the context instance or it will be garbage collected.

See Framework docs.

Context Initialization

If a ContextView is provided the Context is automatically initialized when the supplied view lands on stage. Be sure to install the ContextView last, as it may trigger context initialization.

If a ContextView is not supplied then the Context must be manually initialized.

let context = new Context()
        .install(MyCompanyBundle)
        .configure(MyAppConfig, SomeOtherConfig)
        .initialize();

Note: This does not apply to Flex MXML configuration as the ContextView is automatically determined and initialization will be automatic.

See ContextView docs.

Application & Module Configuration

A simple application configuration file might look something like this:

import {
   IConfig,
   IInjector,
   IMediatorMap,
   IEventCommandMap,
   ContextView,
   inject
} from "@robotlegsjs/core";

public class MyAppConfig implements IConfig
{

    @inject(IInjector)
    injector: IInjector;

    @inject(IMediatorMap)
    mediatorMap: IMediatorMap;

    @inject(IEventCommandMap)
    commandMap: IEventCommandMap;

    @inject(IContextView)
    contextView: IEventCommandMap;

    public function configure(): void
    {
        // Map UserModel as a context enforced singleton
        this.injector.bind(UserModel).toSelf().inSingletonScope();

        // Create a UserProfileMediator for each UserProfileView
        // that lands inside of the Context View
        this.mediatorMap.map(UserProfileView).toMediator(UserProfileMediator);

        // Execute UserSignInCommand when UserEvent.SIGN_IN
        // is dispatched on the context's Event Dispatcher
        this.commandMap.map(UserEvent.SIGN_IN).toCommand(UserSignInCommand);

        // The "view" property is a DisplayObjectContainer reference.
        this.contextView.view.addChild(new MainView());
    }
}

The configuration file above implements IConfig. An instance of this class will be created automatically when the context initializes.

We Inject the utilities that we want to configure, and add our Main View to the Context View.

See Framework documentation

An Example Mediator

The mediator we mapped above might look like this:

import { inject, IEventMap, IEventDispatcher, Mediator } from "@robotlegsjs/core";
import { UserProfileView } from "./UserProfileView";

public class UserProfileMediator extends Mediator<UserProfileView>
{
    public function initialize():void
    {
        // Redispatch an event from the view to the framework
        this.addViewListener(UserEvent.SIGN_IN, dispatch);
    }
}

The view that caused this mediator to be created is available for Injection.

MediatorMap

An Example Command

The command we mapped above might look like this:

import { Command, inject } from "@robotlegsjs/core";

public class UserSignInCommand extends Command
{
    @inject(UserEvent)
    event: UserEvent;

    @inject(UserModel)
    model: UserModel;

    public function execute(): void
    {
        if (event.username == "bob")
            model.signedIn = true;
    }
}

The event that triggered this command is available for Injection.

See EventCommandMap docs.

Motivation

There is plenty of frameworks and patterns out there that helps you to write DOM-based applications. There is no scalable solution yet to architecture a canvas-based application though.

Robotlegs has proven itself of being a mature solution from the ActionScript community for interactive experiences.

License

MIT