angular-ui/ui-router — pull request #399 by nateabele (2013-09-10 04:25:52+00:00)
Title: Decorator API

This patch hooks the internal `stateBuilder` object to a public `$stateProvider` API, allowing developers to extend and modify, or overwrite the functions responsible for generating a state object's internal properties.

Among other things, this allows users to roll their own conventions (an oft-requested feature), such as the following:

```javascript
// Override the internal 'views' builder with a function that takes the state
// definition, and a reference to the internal function being overridden:
$stateProvider.decorator('views', function(state, parent) {
var result = {}, views = parent(state);

angular.forEach(views, function(config, name) {
var autoName = (state.name + "." + name).replace(".", "/");
config.templateUrl = config.templateUrl || "/partials/" + autoName + ".html";
result[name] = config;
});
return result;
});

$stateProvider.state("home", {
views: {
"contact.list": { controller: "ListController" },
"contact.item": { controller: "ItemController" }
}
});

// ...

$state.go("home");
// Auto-populates list and item views with /partials/home/contact/list.html,
// and /partials/home/contact/item.html, respectively.
```

In addition, users can attach custom decorators, which will generate new properties within the state's internal definition. There is currently no clear use-case for this beyond accessing internal states (i.e. `$state.$current`), however, I expect this to become increasingly relevant as we introduce additional meta-programming features.

Fire away with questions or comments. cc: @jeme @ProLoser @timkindberg @stu-salsbury @ksperling