angular-decorators
angular-decorators is a library of ES7 decorators for writing Angular 2 style code in AngularJS.
Installation via npm
npm install angular-decorators --save
Installation via jspm
jspm install angular-decorators
Modules
The standard angular.module
does not understand the metadata attached to your classes from this library's decorators. Use the provided Module function to create decorator-friendly Angular modules:
; // Create a new module:let myModule = ; // Reference a pre-existing module:let otherModule = ;
All decorated classes are added to the module using add
:
; @ ;
If you need the raw angular.module
, use the publish
function:
let angularModule = myModule;
Modules alias config
and run
blocks to the internal angular-module
:
;
Module Dependencies
You do not need to publish a module to add it as a dependency to another module:
let myModule = ;let otherModule = ;
This works for vanilla AngularJS modules as well:
let otherModule = angular;let myModule = ;let lastModule = angular;
Decorators
The decorators provided in this package follow this proposal. They work by adding metadata to your classes under the $ng-decs
namespace using the reflect-metadata polyfill.
Inject
The @Inject
decorator lets you specify dependencies:
@ { }
When inheriting from a decorated class, child dependencies are specified before parent dependencies letting you capture parent dependencies using a rest parameter:
@ { } @ { super...parentDependencies; }
Component
The @Component
decorator lets you create components in AngularJS by wrapping the directive API and setting you up with sensible defaults:
; @@ { ... } 'my-component-module' ;
The directive definition object generated for the above component is:
controller: '$q' MyComponentCtrl controllerAs: 'myComponent' bindToController: true scope: {} restrict: 'E'
Binding Element Attributes to the Controller
Supply an array of properties key of your config object using Angular 2 property syntax:
@
This becomes:
For information on attribute binding, view the AngularJS docs on scopes.
Note: the above uses the new bindToController
syntax introduced in AngularJS 1.4. For AngularJS 1.3, use bind
in your @Component
config instead of properties
:
; @ ...
controllerAs
Renaming By default, the controllerAs
property is a camelCased version of your selector (i.e. my-own-component
's controllerAs
would be myOwnComponent
'). You can override this by specifying a new name in the @Component
config object:
@
Changing Scope
By default, components create new, isolate scopes but this can be manually set in the component config object:
@
Setting the Template
Templates are added with the @View
decorator. Pass in a config object with either an inline template
or a templateUrl
:
; @@ ... @@ ...
Requiring Other Directives
Use the @Require
decorator to require directive controllers and access them using the static link function:
; @@ static { let parent self = controllers; selfparent = parent; }
Transclusion
Use the @Transclude
decorator to setup transclusion for your component:
; @@Transclude ...
Directive
Unlike @Component
, @Directive
does not create a new isolate scope by default nor does it expose your directive's controller on the scope. It can only be used for directives that you want to restrict to a class name or attribute:
; @ { } @ { }
Filter
The @Filter
decorator lets you write class-based filters similar to Angular 2's Pipes:
; @ // Implementing a supports function is encouraged but optional { return typeof input === 'string'; } { return input; } 'trim-filter' ;
The supports
function is an optional test against the input. If the supports
function returns false the generated filter will throw an error instead of applying the transform.
Service
The @Service
decorator turns your class into a service:
; @@ { this$q = $q; } 'my-service' ;
Factory
The @Factory
decorator is a complex decorator that assumes you have a class that requires more parameters on instantiation than what will be provided by AngularJS's injector. For example, if you had a class that looked like this:
@ { }
and you wanted to make a factory that created a new Post
with a parameters for title and content, you would use @Factory
:
; @@ { } 'post-factory' ;
When injected elsewhere use the factory like this:
;; @@ { let post = ; } 'some-service' PostFactory;
You can override the default factory function by implementing a static create function:
; @@ { } static { return ...dependencies postid comment; } 'comment-factory' ;
Providers
Create raw providers using the @Provider
decorator. For easily injecting dependencies to the $get
function, enable ES7 property initializers in your compiler:
; @ { thisgreeting = 'hello'; } { thisgreeting = newGreeting; } $get = '$timeout' ; 'some-service-provider' ;
Animation
Create animations using the @Animation
decorator. Requires ngAnimate
to be included in your module:
;; @@ { this$q = $q; } { return this; } 'my-animation' ngAnimate;
Extending angular-decrators
Adding Your Own Providers
You can register your own providers using Module.addProvider
. For instance, if you want to add a new decorator called @RouteableComponent
that hooked up a component to the upcoming router, you would start by creating a decorator that set a provider name and type on a class:
; const RouteableComponent = { providerWriter; providerWriter;}
Then you'll need to register your custom parser:
; Module;
Your parser will be called each time a provider is added to a Module
that has the provider type you've specified.
Extending the Directive Parser
The directive definiton object is derived from all key/value pairs set with the componentWriter
. Here is an example of creating a priority decorator that sets a directive's priority:
; const Priority = componentWriter;
No other configuration is required. Simply using @Priority
in tandem with @Component
or @Directive
will work.