Working with the MacroConfigurator

Introduction

The MacroConfigurator was introduced in Harfang 0.2. It provides a shortcut to map a Controller's methods to a Module. It makes use of Haxe's Metadata features. Since the MacroConfigurator depends on the "addURLMapping" method of the AbstractModule class, it will only work with an AbstractModule or a Module implementation that provides the same "addURLMapping" method.

Usage

Here is a sample controller with URL metadata:

/**
 * This is a sample controller that uses metadata
 */
class SampleController extends AbstractController {

    @URL("^/demo/1/$")
    public function handleRequestA() : Void {
        Lib.print("A!");
    }

    @URL("^/demo/2/([a-zA-Z]+)/$", "g")
    public function handleRequestB(param : String) : Void {
        Lib.print("Got this : " + param);
    }

    @URL("^/demo/3$prefix/([a-zA-Z]+)/$", "g", "$prefix")
    public function handleRequestC(param : String) : Void {
        Lib.print("Got that : " + param);
    }
}

handleRequestA has metadata with only a regular expression specified - it is the regular expression that is used for the URL mapping.

handleRequestB has metadata with two parameters - the first one is the regular expression and the second one, the parameters of the regular expression.

handleRequestC has metadata with three parameters - the last one is a prefix variable. In this case, it means "Replace all occurrences of $prefix in ^/demo/3$prefix/([a-zA-Z]+)/$ with a value from MacroConfigurator". As you will see in the following class, "bob" is being specified as the prefix. Thus, all occurrences of "$prefix" in the regular expression will be replaced by "bob".

Since there is metadata that describes the URL to which the methods belong, we can use the MacroConfigurator in our Module to map them:

/**
 * This is a sample module that uses MacroConfigurator
 */
class SampleModule extends AbstractModule {

    /**
     * Auto-configure using macros
     */
    public function new() {
        super();

        MacroConfigurator.mapController(this, SampleController, "URL", "bob");
    }

}

The first parameter of mapController is the module instance on which the controllers will be mapped. The second parameter is controller's class to map. The third parameter is the metadata tag to scan for (in our case, URL). The third (optional) parameter is a prefix that will be appended to each URL having a prefix parameter (see handleRequestC above).

After the macro is ran, all the "addURLMapping" calls will be generated from the given metadata, making configuration simpler.

The resulting URLs should work with the SampleController :

* /demo/1/ will lead to handleRequestA
* /demo/2/aa will lead to handleRequestB and send "aa" as a parameter
* /demo/3bob/abc will lead to handleRequestC and send "abc" as a parameter

version #13817, modified 2012-04-20 07:01:49 by njuneau