https://github.com/jameshenry/ng-custom-element

:sparkles: Legacy AngularJS (1.3+) bindings to modern Custom Elements
https://github.com/jameshenry/ng-custom-element

Last synced: 19 days ago
JSON representation

:sparkles: Legacy AngularJS (1.3+) bindings to modern Custom Elements

• Host: GitHub
• URL: https://github.com/jameshenry/ng-custom-element
• Owner: JamesHenry
• License: mit
• Created: 2018-09-03T18:55:38.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2022-12-08T18:36:59.000Z (almost 2 years ago)
• Last Synced: 2024-10-04T13:26:57.507Z (about 2 months ago)
• Language: TypeScript
• Homepage: https://jameshenry.blog
• Size: 2.35 MB
• Stars: 19
• Watchers: 6
• Forks: 5
• Open Issues: 23
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
ng-custom-element


Legacy AngularJS bindings to modern Custom Elements




    

    

    

    

    

    






## 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:

```js

angular.module('app', ['']).controller('ExampleController', function() {

  this.controllerProp = {

    somObj: 'val'

  };

  this.onClick = function clickHandler($event) {

    console.log('was clicked', $event);

  };

});

```

```html

```

## 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+**

```html

```

**ng-custom-element (AngularJS 1.3+)**

```html

```

Pretty sweet!

## Usage

1. Install the library and add its angular.module as a dependency of your own:

```js

angular.module('yourAwesomeApp', ['ngCustomElement']);

```

2. Apply the attribute directive `ng-custom-element` to any DOM element you want to bind properties or events to

```html

```

3. Use `ngce-prop-*` to bind properties (**see the notes on casing below**) to the element:

```html

```

4. Use `ngce-event-*` to bind events (**see the notes on casing below**) to the element:

```html

```

## 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".