Nuclear Potato Monster

    ng-custom-element

    2.0.3 • Public • Published

    ng-custom-element

    Legacy AngularJS bindings to modern Custom Elements

    Travis GitHub license NPM Version NPM Downloads Commitizen friendly semantic-release


    Background

    Custom elements are great. Angular Elements is a great way of making custom elements from Angular code. Angular Elements is therefore also a great upgrade strategy for AngularJS apps looking to upgrade to Angular.

    In AngularJS 1.7.3, some helpers were introduced for binding properties and events to custom elements from surrounding AngularJS code.

    For example:

    angular.module('app', ['']).controller('ExampleController', function() {
      this.controllerProp = {
        somObj: 'val'
      };
      this.onClick = function clickHandler($event) {
        console.log('was clicked', $event);
      };
    });
    <my-element ng-prop-my_prop="$ctrl.controllerProp" ng-on-click="$ctrl.onClick($event)"></my-element>

    ng-prop-* and ng-on-* are awesome, but not backwards compatible

    The changes introduced to facilitate the helpers for ng-prop-* and ng-on-* are not backwards compatible. This library therefore exposes a custom directive called ng-custom-element which allows you to emulate how it works!

    It has been tested in AngularJS versions as far back as 1.3, but it may even work in versions older than that.

    Assuming the exact controller code from above, let's compare the HTML from the AngularJS 1.7.3+ helpers and this library:

    AngularJS 1.7.3+

    <my-element ng-prop-my_prop="$ctrl.controllerProp" ng-on-click="$ctrl.onClick($event)"></my-element>

    ng-custom-element (AngularJS 1.3+)

    <my-element ng-custom-element ngce-prop-my_prop="$ctrl.controllerProp" ngce-on-click="$ctrl.onClick($event)"></my-element>

    Pretty sweet!

    Usage

    1. Install the library and add its angular.module as a dependency of your own:
    angular.module('yourAwesomeApp', ['ngCustomElement']);
    1. Apply the attribute directive ng-custom-element to any DOM element you want to bind properties or events to
    <my-element ng-custom-element></my-element>
    1. Use ngce-prop-* to bind properties (see the notes on casing below) to the element:
    <my-element ng-custom-element ngce-prop-my_prop="someAngularJSControllerProp"></my-element>
    1. Use ngce-event-* to bind events (see the notes on casing below) to the element:
    <my-element ng-custom-element ngce-on-click="someAngularJSControllerMethod($event)"></my-element>

    Notes on casing

    We need to pay special attention to casing.

    From the ngProp docs: https://docs.angularjs.org/api/ng/directive/ngProp

    Since HTML attributes are case-insensitive, camelCase properties like innerHTML must be escaped. AngularJS uses the underscore (_) in front of a character to indicate that it is uppercase, so innerHTML must be written as ng-prop-inner_h_t_m_l="expression" (Note that this is just an example, and for binding HTML ngBindHtml should be used).

    From the ngOn docs: https://docs.angularjs.org/api/ng/directive/ngOn

    Since HTML attributes are case-insensitive, camelCase properties like myEvent must be escaped. AngularJS uses the underscore (_) in front of a character to indicate that it is uppercase, so myEvent must be written as ng-on-my_event="expression".

    Keywords

    none

    Install

    npm i ng-custom-element

    DownloadsWeekly Downloads

    291

    Version

    2.0.3

    License

    MIT

    Unpacked Size

    31.5 kB

    Total Files

    15

    Last publish

    Collaborators

    • jameshenry