@codebakery/origami
Advanced tools
Origami is the art of folding paper with sharp angles to form beautiful creations.
Angular + Polymer
Origami bridges gaps between the Angular framework and Polymer-built custom elements.
Check out the Quick Start for a quick overview of how to import and use Origami.
[( )] Databinding ✅<iron-list>) ✅Origami does not support Polymer 1.x or the v0 Custom Element spec. Check out angular-polymer for Angular 2.x and Polymer 1.x love.
Polymer is built off of WebComponents, which is comprised of
Polyfills are available and Origami supports the latest 2 versions of the following browsers:
Origami may work on older versions or different browsers (such as Opera), but they are not officially supported.
$ npm install --save @codebakery/origami
Polymer and most custom elements are installed with bower. Install bower globally and initialize the project. This will create a bower.json (similar to package.json).
$ npm install -g bower
$ bower init
Make sure bower components are installed to a directory that is included in the project's final build. For example, an Angular CLI-generated project includes src/assets/. Create a .bowerrc file to redirect bower installations to the correct folder.
{
"directory": "src/assets/bower_components"
}
Next install Polymer and any other custom elements.
$ bower install --save Polymer/polymer#^2.0.0-rc.7
$ bower install --save webcomponents/webcomponentsjs#^1.0.0-rc.11
Projects should add the bower_components/ directory to their .gitignore file.
When targeting browsers that do not natively support WebComponents, polyfills are required. The app must wait for the polyfills before bootstrapping.
Origami recommends using the webcomponents-loader.js polyfill. This script will check for native browser support before loading the required polyfills.
index.html
<html>
<head>
<title>Paper Crane</title>
<script src="assets/bower_components/webcomponentsjs/webcomponents-loader.js"></script>
</head>
<body>
<app-root>Loading...</app-root>
</body>
</html>
main.ts
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { webcomponentsReady } from '@codebakery/origami';
webcomponentsReady().then(() => {
platformBrowserDynamic().bootstrapModule(AppModule);
}).catch(error => {
// No WebComponent support and webcomponentsjs is not loaded
console.error(error);
});
Angular 4 consumes all <template> elements instead of letting Polymer use them. The app should set enableLegacyTemplate to false when bootstrapping to prevent this.
Angular 5+ defaults this value to false, so no additional steps are needed.
platformBrowserDynamic().bootstrapModule(AppModule, {
enableLegacyTemplate: false
});
Remember to use <ng-template> for Angular templates, and <template> for Polymer templates.
enableLegacyTemplate and <template> elements are not currently working in Angular 4.0.1. See https://github.com/angular/angular/issues/15555 and https://github.com/angular/angular/issues/15557.
Origami includes an ng-template[polymer] directive to compensate. Use it on an <ng-template> to convert it to a Polymer <template> at runtime.
<iron-list [items]="items">
<!-- This is the correct way that doesn't work
<template>
<div>[[item]]</div>
</template>
-->
<ng-template polymer>
<div>[[item]]</div>
</ng-template>
</iron-list>
ng-template[polymer] will be deprecated as soon as the above issues are fixed. Remember that anytime Origami's documentation mentions using a <template>, the app should use <ng-template polymer> instead.
Import the PolymerModule from Origami into the app's main module and enable custom element support. That's it!
Optionally, the app can also import selectors from Origami for Polymer's collections. This is highly recommended (+10 to sanity), but is not required.
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { PolymerModule } from '@codebakery/origami';
import { IronElementsModule, PaperElementsModule } from '@codebakery/origami/lib/collections'; // Optional
// There are many collections to import, such as iron, paper, and gold elements
@NgModule({
declarations: [
AppComponent
],
schemas: [CUSTOM_ELEMENTS_SCHEMA],
imports: [
FormsModule, // Required to connect elements to Angular forms
PolymerModule,
// Optional modules to help reduce markup complexity
IronElementsModule,
PaperElementsModule
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
For non-Polymer collection elements, the app will need to use the [emitChanges] and [ironControl] attributes.
Add the [emitChanges] directive to all custom elements using two-way data binding. Optionally add [ironControl] to control elements that should work in Angular forms.
<my-custom-checkbox [(checked)]="isChecked" emitChanges></my-custom-checkbox>
<form #ngForm="ngForm">
<paper-input label="Name" emitChanges ironControl required [(ngModel)]="name"></paper-input>
<!-- No two-way binding, [emitChanges] is not needed -->
<paper-button [disabled]="!ngForm.form.valid" (click)="onSubmit()">Submit</paper-button>
</form>
If the app imported PaperElementsModule, [emitChanges] and [ironControl] are not needed for paper elements. They are still required for elements that do not have a collections module.
<my-custom-checkbox [(checked)]="isChecked" emitChanges></my-custom-checkbox>
<form #ngForm="ngForm">
<paper-input label="Name" required [(ngModel)]="name"></paper-input>
<paper-button [disabled]="!ngForm.form.valid" (click)="onSubmit()">Submit</paper-button>
</form>
1.1.0 (2017-05-04)
webcomponentsjs 1.0.0-rc.11 added window.WebComponents to indicate whether or not polyfills are being loaded. To take advantage of this and reduce complexity, Origami provides webcomponentsReady(). Instead of adding listeners for WebComponentsReady, just bootstrap the app when the function resolves.
Before:
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
function bootstrap() {
platformBrowserDynamic().bootstrapModule(AppModule);
}
if (window.webcomponentsReady) {
bootstrap();
} else {
window.addEventListener('WebComponentsReady', bootstrap);
}
After:
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { webcomponentsReady } from '@codebakery/origami';
webcomponentsReady().then(() => {
platformBrowserDynamic().bootstrapModule(AppModule);
});
Make sure you update webcomponentsjs! Either explicitly install it, or remove bower_components and reinstall to get the latest version.
<a name="1.0.1"></a>
FAQs
Angular + Polymer
The npm package @codebakery/origami receives a total of 130 weekly downloads. As such, @codebakery/origami popularity was classified as not popular.
We found that @codebakery/origami demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.