Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hotforfeature/origami

Angular + Polymer
https://github.com/hotforfeature/origami

angular angular2 material-design polymer polymer2 webcomponents

Last synced: 2 days ago
JSON representation

Angular + Polymer

Awesome Lists containing this project

README 

        
# Origami



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



Angular + Polymer



[![NPM Package](https://badge.fury.io/js/%40codebakery%2Forigami.svg)](https://www.npmjs.com/package/@codebakery/origami)



[![Test Status](https://saucelabs.com/browser-matrix/codebakery-origami.svg)](https://saucelabs.com/open_sauce/user/codebakery-origami)



## Summary



[Angular and custom elements are BFFs](https://custom-elements-everywhere.com/). 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](forms/README.md)

- [ShadyCSS Support](styles/README.md#shadycss)

- [Style Modules](styles/README.md#style-modules)

- [Polymer `` Stamping](templates/README.md)

- [Polyfill Utilities](polyfills/README.md)



To setup Origami, follow these steps:



1. [Install and import](#install) `OrigamiModule`

2. Set up [polyfills](#polyfills)

3. [Prepare dependencies](#prepare-dependencies-es5-only) if targeting ES5

4. Read the [Usage Summary](#usage-summary)



## Install



> Upgrading from Origami v2? Follow [this guide](UPGRADE.md).



```sh

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.



```ts

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](polyfills/README.md) are needed to support browsers that do not support all webcomponent features. To quickly set up polyfills, use the Origami CLI.



```sh

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.



```ts

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:



```sh

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`.



```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](forms/README.md)



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



> Requires the `@angular/forms` module.



```ts

import { Component } from '@angular/core';

import '@polymer/paper-input/paper-input';



@Component({

  selector: 'app-component',

  template: `

    
Angular value: {{value}}


    

  `

})

export class AppComponent {

  value: string;

}

```



### [ShadyCSS Support](styles/README.md#shadycss)



Enables the use of CSS custom properties in Angular styles on browsers that do not support them via [ShadyCSS](https://github.com/webcomponents/shadycss), with some [limitations](styles/README.md#limitations).



```ts

import { Component } from '@angular/core';

import '@polymer/paper-button/paper-button';



@Component({

  selector: 'app-component',

  styles: [

    `

      paper-button {

        --paper-button-ink-color: blue;

      }

    `

  ],

  template: `

    Blue Ink!

  `

})

export class AppComponent {}

```



### [Style Modules](styles/README.md#style-modules)



Allows for [style modules](https://www.polymer-project.org/3.0/docs/devguide/style-shadow-dom#style-modules) defined in Polymer to be injected into Angular components.



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



```ts

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

    


      
Column 1


      
Column 2


    


  `

})

export class AppComponent {}

```



### [Polymer `` Stamping](templates/README.md)



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



```ts

import { Component } from '@angular/core';

import { polymerHost } from '@codebakery/origami/templates';

import '@polymer/iron-list/iron-list';



@Component({

  selector: 'app-component',

  template: `

    

      

        


          
[[getLabel(item)]]


        


      

    

  `,

  providers: [polymerHost(AppComponent)]

})

export class AppComponent {

  items = [1, 2, 3];



  getLabel(item: number) {

    return `# ${item}`;

  }



  itemClicked(event: Event) {

    console.log(event);

  }

}

```