ng-classes

ES6, ES7 and TS base classes for AngularJS units
Homepage:
1 person uses it
Author: 12109873?v=3 ex-machine
Submitted by: 2905949?v=3 bisubus

ng-classes

Base classes for object-oriented Angular 1.x units, tailored with DI in mind.

Come in ES2015 (ES6), ES2016 (ES7) and TypeScript flavours.

Flavours

ES2015 (ES6)

import { NgBase } from 'ng-classes';

or

let ngClasses = require('ng-classes'); let NgBase = ngClasses.NgBase;

ES2016 (ES7)

import { NgBase } from 'ng-classes/es7';

TypeScript

import { NgBase } from 'ng-classes/ts';

Compatibility

NgProvider and NgDirective classes use ES5 getters/setters (IE9+) to substitute methods in children.

NgProvider uses Function.prototype.bind (IE9+) to supply its instance to NgProviderInstance.

ES2016/TS decorators call for ES5 getters/setters.

factory uses Object.getOwnPropertyNames and Object.getOwnPropertyDescriptor (IE9+), also Object.getPrototypeOf and Object.setPrototypeOf (IE11) for able-bodied support of static property inheritance.

Dependency injection

'@inject' decorator (ES2016/TS)

Can be used to annotate classes and class members.

import { inject, NgBase } from 'ng-classes';

@inject('$logProvider') class JoeProvider extends NgBase { constructor(...deps) { super(...deps);

}

'$inject' static property

class JoeProvider extends NgBase { static $inject = ['$logProvider']; … }

Class instantiation

'@factory' decorator (ES2016/TS)

Allows to feed classes to Angular units that expect factory functions. Unicontroller and service may benefit from this, too, in the case of instantiation problems (applicable to pre-1.5 Angular with native classes).

Replaces a class with wrapper function that instantiates it. Wrapper properties are prototypically inherited from class if Object.setPrototypeOf is supported, otherwise they are copied (all properties from the class and enumerable properties from its parents). This may cause inheritance issues in older JS engines, particularly if static properties are changed after class declaration, or parent classes have non-enumerable static properties.

All children classes of a decorated class will inherit from wrapper function, not a class itself.

Should be used in the first place, before @inject and other class decorators. The decorators are executed in reverse order of their appearance, a factory wrapper and not original class will be decorated otherwise.

import { factory, inject, NgBase, NgDirective } from 'ng-classes';

class JoeAbstractDirective extends NgDirective {}

Object.defineProperty(JoeAbstractDirective, 'nonEnumerableStaticProp', { value: 'May not be available as JoeDirective.nonEnumerableStaticProp' });

// Preferably a final class @factory @inject('$log') class JoeDirective extends JoeAbstractDirective { static staticProp = 'Available as JoeDirective.staticProp and this.constructor.staticProp';

}

// Commonly does not require a factory wrapper class JoeService extends NgBase { … }

angular.module('average', []) .service('JoeService', JoeService) .directive('joe', JoeDirective);

'factory' function

The same function can be also used as a helper but has no inherent side effects of @factory decorator.

… angular.module('average', []) .service('JoeService', JoeService) .directive(factory(JoeDirective));

'$factory' static method

Provides the same functionality for base classes as factory function.

… angular.module('average', []) .service('JoeService', JoeService) .directive(JoeDirective.$factory());

'ng-classified' extension

Base classes have $classify property and are compatible with ng-classified, no additional instantiation measures are necessary.

import { NgBase, NgDirective } from 'ng-classes'; import { ngClassifiedModule } from 'ng-classified';

class JoeService extends NgBase { … }

class JoeDirective extends NgDirective { … }

angular.module('average', [ngClassifiedModule]) .service('JoeService', JoeService) .directive('joe', JoeDirective);

Classes

ng-classes

ng-classes~NgBase

Base class for Angular units. Child classes are supposed to be supplied into most places that feature Angular DI - controllers, config and run blocks, factory and service services, etc.

Kind: inner class of ng-classes

new NgBase(...deps)

| Param | Type | Description | | --- | --- | --- | | ...deps | * | Injected dependencies |

NgBase.$inject : Array.<string>

Annotates class constructor for Angular injector.

Kind: static property of NgBase
Default: []
Access: public

NgBase.$classify

Provides support for ng-classified.

Kind: static constant of NgBase
Default: true
Access: public

NgBase.$factory() ⇒ function

Creates an annotated class wrapper which is supplied to Angular injector.

Kind: static method of NgBase
Returns: function - Factory function that returns a new class instance.
Access: public

ng-classes~NgProvider

Base class for Angular service providers. Accepts a child of NgProviderInstance class as $get value to be instantiated as service instance.

Kind: inner class of ng-classes

ngProvider.$get ⇒ function

$get getter/setter. Dispathes factory function from/to _$get.

Kind: instance property of NgProvider
Access: public

ng-classes~NgProviderInstance

Base class for Angular provider service instances

Kind: inner class of ng-classes

new NgProviderInstance(provider, ...deps)

| Param | Type | Description | | --- | --- | --- | | provider | NgProvider | Provider class instance. | | ...deps | * | Injected dependencies. |

ng-classes~NgDirective

Base class for Angular directives

Kind: inner class of ng-classes

ngDirective.restrict : string

Restricts directive declaration, forces the defaults in Angular 1.2.x for consistency.

Kind: instance property of NgDirective
Default: "EA"
Access: public

ngDirective.compile ⇒ function

compile getter/setter. Puts original function to '_compileFn' and returns _compile wrapper.

Kind: instance property of NgDirective
Access: public

ngDirective._compile() ⇒ function

compile function wrapper. Runs original function and allows compile, preLink and link functions to co-exist on DDO.

Kind: instance method of NgDirective
Access: public

ng-classes~NgTemplate

Base class for Angular component templates

Kind: inner class of ng-classes

ngTemplate.toString() ⇒ string

Shadows Object.prototype.toString method. Affects object conversion when a string is expected (DOM assignments, String.prototype methods).

Kind: instance method of NgTemplate
Access: public

ngTemplate.valueOf() ⇒ string

Shadows Object.prototype.valueOf method. Affects type conversion (string operators, non-strict equality).

Kind: instance method of NgTemplate
Access: public

Usage

As shown in this demo app,

Directive can be DI-powered class Component's template function can be DI-powered class as well


bootstrap.js

import 'angular'; import appModule from './app';

angular.bootstrap(document.body, [appModule]);


app.js

import joeDirectiveModule from './joe-directive'; import joeComponentModule from './joe-component';

export default angular.module('average', [joeDirectiveModule, joeComponentModule]) .name;


joe-provider-complex.js

import { factory, inject, NgProvider, NgProviderInstance } from 'ng-classes';

// Decorators are executed in reverse order of their appearance. // @factory should come first. @factory @inject('$logProvider') export class JoeProviderComplex extends NgProvider { debug(flag) { return this.$.$logProvider.debugEnabled(flag); }

$get = JoeProviderComplexInstance; }

@inject('$log') export class JoeProviderComplexInstance extends NgProviderInstance { logOnly(flag) { // Provider object, passed to constructor and available as this.$provider this.$provider.debug(!flag);

} }

export default angular.module('average.joeProviderComplex', []) .provider('joeProviderComplex', JoeProviderComplex) .name;


joe-provider-basic.js

import { factory, inject, NgBase } from 'ng-classes';

// Provider can be defined with NgBase instead of NgProvider/NgProviderInstance export class JoeProviderBasic extends NgBase { log(logService) { logService.log('basic provider log'); }

// and having a single class for provider and instance can be tedious @inject('$log') $get($log) { this.log($log);

}; }

export default angular.module('average.joeProviderBasic', []) // 'factory' helper function is the alternative to '@factory' decorator. .provider('joeProviderBasic', factory(JoeProviderBasic)) .name;


joe-controller.js

import { factory, inject, NgBase } from 'ng-classes'; import joeProviderComplexModule from './joe-provider-complex'; import joeProviderBasicModule from './joe-provider-basic';

// No @factory is necessary for instantiated units. @inject('joeProviderComplex', 'joeProviderBasic') export class JoeController extends NgBase { constructor(...deps) { super(...deps);

} }

export default angular.module('average.joeController', [joeProviderComplexModule, joeProviderBasicModule]) .controller('JoeController', JoeController) .name;


joe-directive.js

import { factory, inject, NgDirective } from 'ng-classes'; import joeControllerModule from './joe-controller';

export class JoeDirective extends NgDirective { template = <div> <h1>joe-directive</h1> <h2 ng-transclude></h2> <p></p> <p></p> </div> ;

transclude = true;

controller = 'JoeController';

controllerAs = 'vm';

compile = (element) => { this.messageCompile = 'compile'; }

preLink = (scope, element, attrs, ctrl) => { ctrl.messagePreLink = 'pre-link'; }

link = (scope, element, attrs, ctrl) => { ctrl.messagePostLink = 'post-link';

} }

export default angular.module('average.joeDirective', [joeControllerModule]) // $factory() method does the same job as '@factory' decorator and 'factory' helper function .directive('joeDirective', JoeDirective.$factory()) .name;


joe-component.js

import { factory, inject, NgBase, NgTemplate } from 'ng-classes';

export class JoeComponent { template = JoeComponentTemplate.$factory(); }

@inject('$element') export class JoeComponentTemplate extends NgTemplate { constructor(...deps) { super(...deps);


joe-component ${text} `; } }

export default angular.module('average.joeComponent', []) // Components don't do DI, the class can be just 'new'ed. .component('joeComponent', new JoeComponent) .name;

comments powered by Disqus
This page was last updated over 1 year ago.