ez-ng

Getting Started

Install with Bower:

bower install ez-ng --save

Install with NPM:

npm install ez-ng --save

Include the module:

angular.module('myApp', ['ezNg']);

API Reference

Modules

Members

ezNg

A collection of very simple utilities that make developing AngularJS apps much easier.

Ngdoc: module

• ezNg
  • .ezComponentHelpers
    • .useTemplate()
    • .useTemplateUrl() ⇒ Promise
    • .useStyles()
    • .useStylesUrl() ⇒ Promise
  • .ezEventEmitter
    • instance
      • .create([name]) ⇒ EventEmitter
      • .mixin(object, [name]) ⇒ EventEmitter
      • .debug()
    • inner
      • ~EventEmitter
        • .on(events, handler)
        • .once(events, handler)
        • .off(events, handler)
        • .emit(eventName, ...arguments)
  • .ezLogger
    • instance
      • .create() ⇒ Logger
    • inner
      • ~Logger
        • .setFormat(format)
        • .setFormat(formatter)
        • .setFormat(level)
  • .ezFormatter
    • instance
      • .index() ⇒ formatFunction
      • .assoc() ⇒ formatFunction
    • inner
      • ~formatFunction(placeholders, replacements) ⇒ string
  • .ezLoggerLevel : LogLevel
  • .ezLoggerFormat : string
  • .ezLoggerDateTimeFormatter : function
  • .ezComponent(options)

ezNg.ezComponentHelpers

Provides a few functions that can be used with directives to provide easy access to templates and styles. Use in a directive's link function or component's controller. The factory function takes the same arguments as a link function.

Kind: static service of ezNg
Ngdoc: service
Example

//in a link function:
//...
link: function (scope, element, attrs, ctrl, transclude) {
    let ch = ezComponentHelpers.apply(null, arguments); //or just invoke directly like ezComponentHelpers(scope, element...)

    ch.useTemplate('<span>Hello, World!</span');
}
//...

//in a controller:
//...
controller: ['$scope', '$element', '$attrs', '$transclude', function ($scope, $element, $attrs, $transclude) {
    let ch = ezComponentHelpers($scope, $element, $attrs, this, $transclude);

    ch.useTemplate('<span>Hello, World!</span');
}
//...

• .ezComponentHelpers
  • .useTemplate()
  • .useTemplateUrl() ⇒ Promise
  • .useStyles()
  • .useStylesUrl() ⇒ Promise

ezComponentHelpers.useTemplate()

Takes a HTML template string and replaces the contents of element with a compiled and linked DOM tree

Kind: instance method of ezComponentHelpers
Ngdoc: method
Example

let ch = ezComponentHelpers.apply(null, arguments);

ch.useTemplate('<span>Hello, World!</span>');

<!-- Result: -->
<my-component>
    <span>Hello, World!</span>
</my-component>

ezComponentHelpers.useTemplateUrl() ⇒ Promise

Takes a URL that resolves to a HTML template string and replaces the contents of element with a compiled and linked DOM tree. The result is the same as using useTemplate but does not require and inline template.

Kind: instance method of ezComponentHelpers
Returns: Promise - Resolves after contents have been compile, linked, and appended to the element
Ngdoc: method
Example

let ch = ezComponentHelpers.apply(null, arguments);

ch.useTemplateUrl('/components/my-component/template.html'); //<span>Hello, World!</span>

<!-- Result: -->
<my-component>
    <span>Hello, World!</span>
</my-component>

ezComponentHelpers.useStyles()

Takes a string of CSS styles and adds them to the element. The styles become scoped to the element thanks to a fantastic script by Thomas Park (https://github.com/thomaspark/scoper). Note that the element itself will also be affected by the scoped styles. Styles are applied after a browser event cycle.

Kind: instance method of ezComponentHelpers
Ngdoc: method
Example

let ch = ezComponentHelpers.apply(null, arguments);

ch.useStyles('.my-class { color: red; }');

<!-- Result: -->
<span class="my-class">This text is black</span>
<my-component>
    <span class="my-class">This text is red</span>
</my-component>

ezComponentHelpers.useStylesUrl() ⇒ Promise

Takes a URL that resolves to CSS styles and adds them to the element. The results are the same as useStyles.

Kind: instance method of ezComponentHelpers
Returns: Promise - resolves after styles have been added but before they have been applied
Ngdoc: method
Example

let ch = ezComponentHelpers.apply(null, arguments);

ch.useStylesUrl('/components/my-component/styles.css'); //.my-class { color: red; }

<!-- Result: -->
<span class="my-class">This text is black</span>
<my-component>
    <span class="my-class">This text is red</span>
</my-component>

ezNg.ezEventEmitter

Provides a simple event emitter that is not hooked into the Scope digest cycle.

Kind: static service of ezNg
Ngdoc: service

• .ezEventEmitter
  • instance
    • .create([name]) ⇒ EventEmitter
    • .mixin(object, [name]) ⇒ EventEmitter
    • .debug()
  • inner
    • ~EventEmitter
      • .on(events, handler)
      • .once(events, handler)
      • .off(events, handler)
      • .emit(eventName, ...arguments)

ezEventEmitter.create([name]) ⇒ EventEmitter

Returns a new event emitter with the provided name

Kind: instance method of ezEventEmitter
Ngdoc: method

| Param | Type | Description | | --- | --- | --- | | [name] | string | Optional name for debugging purposes |

Example

let emitter = ezEventEmitter.create('myEmitter');

ezEventEmitter.mixin(object, [name]) ⇒ EventEmitter

Returns a new event emitter with the provided name

Kind: instance method of ezEventEmitter
Ngdoc: method

| Param | Type | Description | | --- | --- | --- | | object | Object | Object to extend with EventEmitter characteristics | | [name] | string | Optional name for debugging purposes |

Example

let myObject = {},
    emitter = ezEventEmitter.mixin(myObject, 'myEmitter');

myObject.on('myEvent', function () {});
myObject.emit('myEvent');

ezEventEmitter.debug()

Put ezEventEmitter into debug mode. This will cause all actions to be logged to the console for easy debugging.

Kind: instance method of ezEventEmitter
Ngdoc: method
Example

let emitter = ezEventEmitter.create('myEmitter');
ezEventEmitter.debug();

emitter.emit('hello'); //"Emitted event hello with emitter myEmitter. Invoked 0 handlers."

ezEventEmitter~EventEmitter

Describes a simple event emitter

Kind: inner interface of ezEventEmitter

• ~EventEmitter
  • .on(events, handler)
  • .once(events, handler)
  • .off(events, handler)
  • .emit(eventName, ...arguments)

eventEmitter.on(events, handler)

Registers a listener for a specific event or multiple events

Kind: instance method of EventEmitter

| Param | Type | Description | | --- | --- | --- | | events | string | Space-separated of events to listen for | | handler | function | Function to invoke when event is triggered |

Example

let emitter = ezEventEmitter.create();

emitter.on('someEvent', function (arg1, arg2) {
    console.log(arg1); //hello
    console.log(arg2); //world
});

emitter.emit('someEvent', 'hello', 'world');

eventEmitter.once(events, handler)

Registers a listener for a specific event or multiple events, and immediately cancels the listener after it is invoked the first time

Kind: instance method of EventEmitter

| Param | Type | Description | | --- | --- | --- | | events | string | Space-separated of events to listen for | | handler | function | Function to invoke when event is triggered for the first time |

Example

let emitter = ezEventEmitter.create(),
    count = 0;

emitter.once('inc', function () {
    console.log('Current count: ' + (++count));
});

emitter.emit('inc'); // Current count: 1
emitter.emit('inc'); //

eventEmitter.off(events, handler)

Cancels listeners for specified event(s)

Kind: instance method of EventEmitter

| Param | Type | Description | | --- | --- | --- | | events | string | Space-separated of events to remove listeners for | | handler | function | Reference to listener to cancel |

Example

let emitter = ezEventEmitter.create(),
    count = 0,
    increment = function () {
       console.log('Current count: ' + (++count));
    };

emitter.on('inc', increment);

emitter.emit('inc'); // Current count: 1
emitter.emit('inc'); // Current count: 2
emitter.off('inc', increment);
emitter.emit('inc'); //

eventEmitter.emit(eventName, ...arguments)

Triggers specified event with provided arguments

Kind: instance method of EventEmitter

| Param | Type | Description | | --- | --- | --- | | eventName | string | Name of event to trigger | | ...arguments | any | Arguments to pass to handlers |

Example

let emitter = ezEventEmitter.create();

emitter.on('someEvent', function (arg1, arg2) {
    console.log(arg1); //hello
    console.log(arg2); //world
});

emitter.emit('someEvent', 'hello', 'world');

ezNg.ezLogger

Provides a simple abstraction of $log that provides output formatting and level thresholds

Kind: static service of ezNg
Ngdoc: service

• .ezLogger
  • instance
    • .create() ⇒ Logger
  • inner
    • ~Logger
      • .setFormat(format)
      • .setFormat(formatter)
      • .setFormat(level)

ezLogger.create() ⇒ Logger

Factory function for creating a new logger with an optional name

Kind: instance method of ezLogger
Ngdoc: method

ezLogger~Logger

Kind: inner property of ezLogger

• ~Logger
  • .setFormat(format)
  • .setFormat(formatter)
  • .setFormat(level)

logger.setFormat(format)

Sets the log message format for this logger. See ezLoggerLevel

Kind: instance method of Logger

| Param | Type | Description | | --- | --- | --- | | format | string | String containing placeholders for log message properties |

logger.setFormat(formatter)

Sets the output format of date and time for this logger. See ezLoggerDateTimeFormatter

Kind: instance method of Logger

| Param | Type | Description | | --- | --- | --- | | formatter | function | Function takes the current date (new Date()) and returns a string. |

logger.setFormat(level)

Sets the log level for this logger.

Kind: instance method of Logger

| Param | Type | Description | | --- | --- | --- | | level | LogLevel | Threshold log level. See ezLoggerLevel |

ezNg.ezFormatter

Provides a simple, easy-to-use string formatter to avoid long string concatenations.

There are two types of formatters: associative and indexed.

Kind: static service of ezNg
Ngdoc: service

• .ezFormatter
  • instance
    • .index() ⇒ formatFunction
    • .assoc() ⇒ formatFunction
  • inner
    • ~formatFunction(placeholders, replacements) ⇒ string

ezFormatter.index() ⇒ formatFunction

Factory function to return an indexed formatter.

The indexed formatter takes a string with unnamed placeholders, and an array whose elements replace each unnamed placeholder in the order that they occur.

Kind: instance method of ezFormatter
Returns: formatFunction - Formatter
Ngdoc: method
Example

let format = ezFormatter.index(),
    placeholder = '{} on {}: {} star(s)!';

console.log(format(placeholder, ['Narcos', 'Netflix', 5])); //Narcos on Netflix: 5 star(s)!

ezFormatter.assoc() ⇒ formatFunction

Factory function to return an associative formatter.

The associative formatter takes a string with named placeholders, and an object whose keys are the names of the placeholders and value are the replacement values.

Kind: instance method of ezFormatter
Returns: formatFunction - Formatter
Ngdoc: method
Example

let format = ezFormatter.assoc(),
    placeholder = '{title} on {channel}: {rating} star(s)!';

console.log(format(placeholder, {title: 'Narcos', channel: 'Netflix', rating: 5})); //Narcos on Netflix: 5 star(s)!

ezFormatter~formatFunction(placeholders, replacements) ⇒ string

Kind: inner method of ezFormatter
Returns: string - Formatted string with placeholders replaced.

| Param | Type | Description | | --- | --- | --- | | placeholders | string | A string containing placeholders to replace | | replacements | array | object | An array for indexed formatters, object for associative formatters containing replacement values for placeholders |

ezNg.ezLoggerLevel : LogLevel

Sets the log level for ezLogger

Kind: static property of ezNg
Default: 'DEBUG'
Ngdoc: value

ezNg.ezLoggerFormat : string

Sets the output format of log statements

Kind: static property of ezNg
Default: "'{dateTime}\t{name}\t{level}\t{message}'"
Ngdoc: value

ezNg.ezLoggerDateTimeFormatter : function

Sets the output format of date and time. Function takes the current date (new Date()) and returns a string.

Kind: static property of ezNg
Default: date.toString();
Ngdoc: value

ezNg.ezComponent(options)

Shim for angular 1.5's component service (copied from AngularJs source) https://github.com/angular/angular.js/blob/master/src/ng/compile.js

See Angular's Component documentation for all options.

Additionally provides styles and stylesUrl options for injecting "scoped" styles. See component-helpers.js

Does not support the one-way binding operator ('<') in versions < 1.5

Kind: static method of ezNg
Ngdoc: service

| Param | Type | Description | | --- | --- | --- | | options | object | Options to pass into directive definition |

Example

module.directive('myComponent', ['ezComponent', function (ezComponent) {

    return ezComponent({
        bindings: {
            watched: '=',
            input: '@',
            output: '&'
        },
        styles: '.my-component { color: red; }',
        //OR
        stylesUrl: 'components/my-component/my-component.css'
    });

}]);

LogLevel : enum

Kind: global enum
Properties

| Name | | --- | | TRACE | | DEBUG | | INFO | | WARN | | ERROR | | FATAL |

License

(The MIT License)

Copyright (c) 2015

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.