polycod


Polycod is a shim library that exposes an API similiar to angular2 to write components for angular 1.x applications. Polycod also supports Typescript annotations like angular 2 does.

The purpose of this library is to seamlessly migrate existing angular1 applications to angular2.

Polycod is heavily inspired by ngsham. Kudos to Jason Grier.

Naming: The company I work for uses animal names for their weekly sprints. Last week was the week of 'cod'. A combination of 'polyfill' and 'cod' then resulted into 'polycod'. It sounds a bit like 'polyglot', which I like in this context. Native speakers may have a different opinion :)

Setup

$3

npm install polycod

$3

bower install polycod

$3

Make sure polycod is loaded into the browser after angular. Do it the way you want.

Usage

$3

``javascript
Polycod.component({
module: 'demo',
selector: 'js-cmp',
template: '

HELLO

',
class: function() {}
});

`

$3

`typescript
// declare or reference policod.d.ts first
declare var Polycod;

@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
template: '

HELLO

',
})
class TsCmp {
}

Polycod.bootstrap(TsCmp);
`

A View decorator is also available:

`typescript
// declare or reference policod.d.ts first
declare var Polycod;

@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp'
})
@Polycod.Decorators.View({
template: '

HELLO

'
})
class TsCmp {
}

Polycod.bootstrap(TsCmp);
`

Features

$3

__CAVEATS__

* HTML is case-insensitive. thus will not work
* Dashes will be converted to underscores: is the same as


Polycod allows you to bind to your controllers directly.

Example:

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
template: '

HELLO {{ name }}

'
})
class TsCmp {
name = 'joe';
}
`

.. will display: HELLO joe

$3

Polycod also supports two-way bindings.

Example:

`javascript
var scope = $rootScope.$new()
scope.userName = 'jane';
`

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
template: '

HELLO {{ name }}

'
})
class TsCmp {
}
`

`html

`

.. will display: HELLO joe. Any change to name will also be applied to the source (the scope's userName in this case).

$3

If your component exposes an ngOnChanges function that one will be called whenever any of the properties change.

Example:

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
template: '

HELLO {{ name }}

'
})
class TsCmp {
ngOnChanges(changes) {
console.log(changes.name.currentValue);
};
}
`

$3

It is easily possible to setup events emitted by your components.
Let's assume the context of your new component is some old angular 1 scope like this:

`javascript
var scope = $rootScope.$new()
scope.onSubmitted = function ($event) {
console.log($event.data);
};
`

This is your component emitting the event when the submit function is called:

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
events: ['submitted'],
template: '

HELLO

'
})
class TsCmp {
submit() {
this.submitted('yay');
}
}
`

The HTML that does the connection:

`html

`

$3

You can catch events on your DOM host element like this:

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
host: { 'click': 'onClick()' }
template: '

HELLO

'
})
class TsCmp {
onClick() {
console.log('ts-cmp has been clicked!')
}
}
`

$3

This makes a local variable available as property in your component (on the component controller). Any change will be propagated.

`html

`

$3

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
providers: ['$q', '$timeout', 'UserService'],
template: '

HELLO

'
})
class TsCmp {
constructor($q, $timeout, UserService) {
// use $q, $timeout, UserService here
}
}
`

$3

Polycod has a custom transclusion mechanism that is not quite as nice as what angular2 provides you, but it comes close.

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
transclude: true,
template:

HELLO


})
class TsCmp {
}
`

Usage:

`html

INFO1
INFO2

`

Renders:

`html


HELLO


INFO1
INFO2
`

Since transclude is angular 1 specific you may want to seperate the annotation which is possible as well:

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
template:

HELLO


})
@Polycod.Decorators.Ng1({
transclude: true
})
class TsCmp {
}
`

$3

Expose a function called ngAfterViewInit on your controller class. It is called once an instance of your component got rendered (linked in angular 1 lingo).
Also a lifecycle hook for ngOnDestroy is available.

`typescript
@Polycod.Decorators.Component({
module: 'demo',
selector: 'ts-cmp',
template: '

HELLO

',
})
class TsCmp {
ngAfterViewInit() {
console.log('rendered');
}
ngOnDestroy() {
console.log('destroyed');
}
}

Polycod.bootstrap(TsCmp);
`

$3

The inner HTML of your templates will be converted to support angular2 style syntax. This is the list of supported keywords that will be converted to angular1 style syntax:

ng-for
* [hidden]
* [(ng-model)]
* (click)
* (dbl-click)
* (mousedown)
* (mouseup)
* (mouseenter)
* (mouseleave)
* (mouseover)
* (keydown)
* (keyup)
* (keypress)
* (change)

Todo

Things I would like to see in polycod:

* Support AMD/CommonJS module strategies

Development

$3

`bash
npm install
npm install -g testem
npm install -g browserify
npm install -g typescript
`

$3

testem

$3

./bin/build

$3

./bin/demo`

> Serves a local server on port 8000.