@codebakery/origami

Origami

Origami is the art of folding paper with angles to form beautiful creations.

Angular + Polymer

Summary

Angular and custom elements are BFFs. With Polymer, there are a few gaps that Origami fills. The library is divided into several modules that can be imported individually to address these gaps.

• Angular Form Support
• ShadyCSS Support
• Style Modules
• Polymer <template> Stamping
• Polyfill Utilities

To setup Origami, follow these steps:

• Install and import OrigamiModule
• Set up polyfills
• Prepare dependencies if targeting ES5
• Read the Usage Summary

Install

Upgrading from Origami v2? Follow this guide.

npm install @codebakery/origami

Import each module as described in the links above, or if you need all of the modules you can simply import OrigamiModule. Include CUSTOM_ELEMENTS_SCHEMA to enable custom elements in Angular templates.

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule } from '@angular/router';
// If @angular/router is not used, import modules individually
// and use IncludeStylesNoRouterModule instead of IncludeStylesModule.
import { OrigamiModule } from '@codebakery/origami';
import { AppComponent } from './app.component';

@NgModule({
  imports: [BrowserModule, FormsModule, RouterModule, OrigamiModule],
  declarations: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  bootstrap: [AppComponent]
})
export class AppModule {}

Polyfills

Polyfills are needed to support browsers that do not support all webcomponent features. To quickly set up polyfills, use the Origami CLI.

npm install @webcomponents/webcomponentsjs
./node_modules/.bin/origami polyfill

Wait for WebComponentsReady

Some imports (such as Polymer's TemplateStamp mixin) have side effects that require certain features to be immediately available. For example, TemplateStamp expects HTMLTemplateElement to be defined. These imports should be deferred until after webcomponentsReady() resolves.

import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { webcomponentsReady } from '@codebakery/origami/polyfills';

webcomponentsReady()
  .then(() => {
    // requires "module": "esnext" in tsconfig.json "compilerOptions" and
    // "angularCompilerOptions": {
    //   "entryModule": "app/app.module#AppModule"
    // }
    return import('./app/app.module');
  })
  .then(({ AppModule }) => {
    platformBrowserDynamic().bootstrapModule(AppModule);
  });

Prepare Dependencies (ES5 only)

Angular will not transpile node_modules/, and a common pattern among webcomponents is to be distributed as ES2015 classes. Use Origami's CLI to effeciently transpile dependencies to ES5 or back to ES2015 before building.

Example:

origami prepare es5 node_modules/{@polymer/*,@vaadin/*,@webcomponents/shadycss}

# to restore to ES2015
origami prepare es2015 node_modules/{@polymer/*,@vaadin/*,@webcomponents/shadycss}

# for more info
origami --help

Note that @webcomponents/webcomponentsjs should not be transpiled. However, @webcomponents/shadycss should be if it's used.

The CLI can also restore the previous ES2015 files for projects that compile to both targets.

It is recommended to add a script before ng build and ng serve tasks in package.json.

{
  "scripts": {
    "prepare:es5": "origami prepare es5 node_modules/{@polymer/*,@vaadin/*,@webcomponents/shadycss}",
    "prepare:es2015": "origami prepare es2015 node_modules/{@polymer/*,@vaadin/*,@webcomponents/shadycss}",
    "start": "npm run prepare:es5 && ng serve es5App",
    "start:es2015": "npm run prepare:es2015 && ng serve es2015App",
    "build": "npm run prepare:es5 && ng build es5App --prod",
    "build:es2015": "npm run prepare:es2015 && ng build es2015App --prod"
  }
}

Usage Summary

Angular Form Support

Add the origami attribute to any custom element using [ngModel], [formControl] or [formControlName].

Requires the @angular/forms module.

import { Component } from '@angular/core';
import '@polymer/paper-input/paper-input';

@Component({
  selector: 'app-component',
  template: `
    <div>Angular value: {{value}}</div>
    <paper-input [(ngModel)]="value" origami></paper-input>
  `
})
export class AppComponent {
  value: string;
}

ShadyCSS Support

Enables the use of CSS custom properties in Angular styles on browsers that do not support them via ShadyCSS, with some limitations.

import { Component } from '@angular/core';
import '@polymer/paper-button/paper-button';

@Component({
  selector: 'app-component',
  styles: [
    `
      paper-button {
        --paper-button-ink-color: blue;
      }
    `
  ],
  template: `
    <paper-button>Blue Ink!</paper-button>
  `
})
export class AppComponent {}

Style Modules

Allows for style modules defined in Polymer to be injected into Angular components.

Requires the @angular/router module. Use IncludeStylesNoRouterModule if @angular/router is not used.

import { Component } from '@angular/core';
import { IncludeStyles } from '@codebakery/origami/styles';
import '@polymer/iron-flex-layout/iron-flex-layout-classes';

@IncludeStyles('iron-flex')
@Component({
  selector: 'app-component',
  styles: [':host { display: block; }'], // See Limitations
  template: `
    <div class="layout horizontal">
      <div class="flex">Column 1</div>
      <div class="flex">Column 2</div>
    </div>
  `
})
export class AppComponent {}

Polymer <template> Stamping

Call polymerHost() and add it to the providers for a component that uses Polymer's data binding syntax in <template> elements. Add ngNonBindable to all <template> elements.

import { Component } from '@angular/core';
import { polymerHost } from '@codebakery/origami/templates';
import '@polymer/iron-list/iron-list';

@Component({
  selector: 'app-component',
  template: `
    <iron-list [items]="items">
      <template ngNonBindable>
        <div on-click="itemClicked">
          <div>[[getLabel(item)]]</div>
        </div>
      </template>
    </iron-list>
  `,
  providers: [polymerHost(AppComponent)]
})
export class AppComponent {
  items = [1, 2, 3];

  getLabel(item: number) {
    return `# ${item}`;
  }

  itemClicked(event: Event) {
    console.log(event);
  }
}

Changelog

3.2.0 (2020-04-07)

Features

• add Angular 9 and Ivy support #99 #101 (#102) (478057c)

<a name="3.1.2"></a>