Using class Metadata to generate URL Mappings 1.0

WARNING This document is work in progress.

In the previous tutorial, Your first Harfang Controller, we learned to map URL to controllers using the API. There is an alternate way to perform roughly the same tasks using class metadata.

Annotating your controller

The first step is to annotate your controller so that the URLs point to controller method, just as you would do with the Module API:

package ;

import harfang.controller.AbstractController;

class MyController extends AbstractController {

    @Method("GET")
    @URL("^/$prefix/method/([a-zA-Z0-9]+)/([a-zA-Z0-9]+)/$", "g", "$prefix")
    public function controllerMethod(paramA : String, paramB : String) : Void {
        php.Lib.println("Param A : " + paramA);
        php.Lib.println("Param B : " + paramB);
    }

}

The first parameter of the URL tag is the regular expression itself. The second parameter, optional, consists of the regular expression options. The last parameter, also optional, is a string that will be replaced in the regular expression when the mapping is created. Hence, the "$prefix" part of the regular expression will be replaced with a prefix specified in the module.

Mapping the controller

Then, in your module, you would map the controller in the following way:

package ;

import harfang.module.AbstractModule;
import harfang.url.ERegURLMappingFactory;
import MyController;

class MyModule extends AbstractModule {

    public function new() {
        super();

        ERegURLMappingFactory.mapHttpController(this, MyController, "URL", "Method", "WOW");
    }
}

The first parameter given to the factory is the module instance which will hold the mapping. The second parameter is the controller Class that will be mapped. The third parameter is the name of the metadata tag that holds the mapping information. The last two parameters are optional and represent, in order:

1. The name of the metadata tag containing the HTTP method to use for the mapping (in our controller example, this would be "GET")
2. The string that will take the place of "$prefix" in the regular expression. Since the value given here is "WOW", the resulting regular expression would be "^/WOW/method/([a-zA-Z0-9]+)/(a-zA-Z[0-9]+)/$"

It is important to note that Metadata usage is optional : everything done using Metadata can be done with the API. The URL mapping factories are, in fact, generating calls to the public Harfang API. No dark magic here.