angular-custom-elements


Angular 1.x directive to hold all yr Custom Element bindings together 😁

note: This is still experimental so use at your own risk

Install

``
npm install --save angular-custom-elements
`

Usage

- Include the dist/ce-bind.(min).js script in your page.
- Add robdodson.ce-bind as a module dependency to your app.
- For interpolated/two-way bindings: Add the ce-interpolated directive to
any Custom Element or Polymer Element to keep your interpolated bindings in sync.

`html



`

- For one-way bindings: Add the ce-one-way directive to any Custom
Element or Polymer Element, to keep its one-way bindings in sync.

`js
app.component('fooComponent', {
template:

Angular string is: {{$ctrl.str}}

on-message-changed="$ctrl.onMessageChanged($event)"
ce-one-way>


`

How does it work?

$3

Polymer's two-way binding system is event based. Anytime a bindable property
changes it fires an event named: [property]-changed. For example, a two-way
bindable property named foo would fire a foo-changed event.

This means we can listen for the *-changed events coming off of an element,
and take the new value and pass it into our scope using $evalAsync.

This also means you could write your own Custom Elements that didn't use Polymer
and so long as they fired a [property]-changed event, and the
event.detail.value contained the new value, it would also work.

$3

For Angular 1.5 style one-way bindings, we look at the Input, e.g.
friend="$ctrl.person", set the property on the Custom Element using the value
from $ctrl.person, and create a watcher to update the Custom Element anytime
the $ctrl.person property changes.

For Outputs, we look for any attribute starting with on- and create an event
listener which triggers the corresponding handler in our Angular controller.
E.g. on-person-changed="$ctrl.updatePerson($event)" will listen for the
person-changed event and call the controller's updatePerson method,
passing the event object to it. The controller can then take the value of
event.detail and choose what to do with it. Because Custom Elements typically
communicate to the outside world using Events, this binding will only create
event listeners. This means you cannot use the Angular 1.5 approach of creating
a callback with named arguments:

`
// This will NOT work. The argument will be ignored and the handler
// will always be called with the event object
on-person-changed="$ctrl.updatePerson({name: 'Bob'})"
`

Instead, treat these as regular event listeners and use the value(s) passed
via event.detail.

How is this different from other Polymer + Angular adapters?

The two adapters I've found are
angular-bind-polymer and
ng-polymer-elements. Both are
very cool but they have limitations which this project (hopefully) fixes.

angular-bind-polymer relies on Mutation Observers to notify the scope when an
element's attributes change. This only works if the element chooses to serialize
its internal state back to strings and reflect them to attributes. Most Polymer
elements do not do this, meaning they can't be used with angular-bind-polymer.

ng-polymer-elements attempts to create directives for specific attributes
exposed by Polymer elements but this becomes a bit of an arms race as every time
an element creates a new attribute/property then ng-polymer-elements needs to
be updated. It also relies on Object.observe` which has been removed from the
platform, so an additional polyfill is required.