polymerize 0.9.5

Polymerize - Polymer 2.0 Dart-DDC

Join the chat at https://gitter.im/dart-polymer/Lobby

This package is a community effort to bring support for Polymer 2 and latest HTML standards to Dart (DDC).

It features :

  • support for polymer 2.0.0 (web components 1.0)
  • using DDC to generate ES6 output code
  • leverages html5, a new html lib for Dart based on js interoperability only,
  • ~~using bazel as build system (see also rules )~~
  • NOW working with dart 1.24 + pub (ddc)
  • dynamic load of polymer components definitions through imd (require js implementation using html imports)
  • interoperability with other JS frameworks
  • Incremental build (dependencies are built only once, thanks to DDC modularity system and bazel build)
  • possibility to distribute ONLY the build result to thirdy party users and devs
  • simplified API
    • automatic getter and setter (no explicit notify for first level properties)
    • NO Annotations required to expose properties
    • NO Annotations required to expose methods
  • seamless integration with widely used js tools like bower

Disclaimer

Polymerize works on every platforms where DDC runs that's MacOS and Linux for now.

The upcoming version of pub will support DDC build and polymerize will support it too thus extending the platform where you can use it.

Browser compatibility

Polymerize uses DDC and Polymer-2, this means that it will only work on modern browsers. So far only chrome and firefox have been tested but Safari should work too along with latest IE11 builds.

Eventually some "transpiling" support can be added along with some optimizing post processing (like vulcanize or similar) could be added to the build chain to broaden the compatibility range.

UPDATE : after moving to PUB+DDC there's something broken with firefox , will fix soon. But I wanted to publish this release quickly after 1.24 was officially released.

Usage

Prepare a project

In order to build a project with polymerize you have to add the following transformer and dev dependencies to your pubspec:

dev_dependencies:
  - polymerize: ^0.9.0
transformers:
  - polymerize:
     entry-point: web/index.dart

The entry point is the main dart file. Your html file should look as this:

<html>
 <head>
     <script src="bower_components/webcomponentsjs/webcomponents-loader.js"></script>
     <script type="application/dart" src="index.dart"></script>
     <script src="polymerize_require/start.js"></script>
 </head>
 ...
</html>

See the demo todo project for more details.

Build a project

  1. pub build --web-compiler dartdevc (or add the necessary entries in the pubspec as well)

DISCLAIMER : When using dartdevc for production build you will loose al the optimizations that dart2js normally makes to your code. This means that you will have bigger fat code even if modular and loaded only on demand.

Developing with polymerize

Sample project

A sample project illustrating how to build polymer-2 components using polymerize can be found here :

See the README for more information.

Component definition

This is a sample component definition:

import 'package:polymer_element/polymer_element.dart';
import 'package:my_component/other_component.dart';

@PolymerRegister('my-tag',template:'my-tag.html')
abstract class MyTag extends PolymerElement {

  int count = 0;  // <- no need to annotate this !!!

  onClickIt(Event ev,details) {  // <- NO need to annotate this!!!!
    count = count + 1;    // <- no need to call `set` API , magical setter in action here
  }

  @Observe('count')
  void countChanged(val) {
    print("Count has changed : ${count}");
  }

  MyTag() { // <- Use a simple constructor for created callback !!!
    print("HELLO THERE !")
  }

  factory MyTag.tag() => Element.tag('my-tag'); // <- If you want to create it programmatically use this

  connectedCallback() {
    super.connectedCallback(); // <- super MUST BE CALLED if you override this callback (needed by webcomponents v1) !!!!
  }
}

The Html template is just the usual dom-module template without any JS code. The import dependencies will generate the appropriate html imports so there is no need to add them to the template.

The index.html should preload imd, webcomponents polyfill and polymer.html (see the demo).

Importing a Bower component

To import a bower component and use it in your project simply create a stub (that can created automatically, see below) for it and use the @BowerImport annotation along with @PolymerRegister with native=true, for instance:

@PolymerRegister('paper-button',native:true)
@BowerImport(ref:'PolymerElements/paper-button#2.0-preview',import:"paper-button/paper-button.html",name:'paper-button')
abstract class PaperButton extends PolymerElement implements imp0.PaperButtonBehavior {
  /**
   * If true, the button should be styled with a shadow.
   */
  external bool get raised;
  external set raised(bool value);

}

During the build phase polymerize will check any @BowerImport annotation on classes of dependencies, generate a bower.json file (using resolutions if you need to override something) and then runs bower install.

You can also automatically generate a stub from the HTML polymer component using polymerize generate_wrapper, for instance:

pub run polymerize:polymerize generate-wrapper --component-refs comps.yaml --dest-path out -p polymer_elements --bower-needs-map Polymer.IronFormElementBehavior=package:polymer_elements/iron_form_element_behavior.dart

(You have to add polymerize as a dev dependency of your project).

The generator uses a yaml file describing the components to analyze passed through the component-refs options (see gen/comps.yam in this repo for an example).

The project polymerize_elements is an example of wrappers generated using this tool for the polymer-elements components.

Output

After complilation everything will be found in the bazel output folder (bazel-bin), ready to be used.

TODO:

  • more polymer APIs
  • ~~support for mixins~~
  • ~~annotations for properties (computed props, etc.)~~
  • ~~support for external element wrappers~~
  • ~~support for auto gen HTML imports~~

0.9.5

  • fixes
  • better support for builders

0.9.4

  • added support for tests!!!

0.9.2

  • better detecting of bower
  • added support for dart stack trace mapping

0.9.1+1

  • fix for windows

0.9.1

  • require loading

0.9.0

  • moving to pub+ddc

0.8.5

  • support for autonotify behavior

0.8.4

  • added support for behaviors on behaviors
  • restored native element class
  • better performance (analyzer context recycled)
  • one action to build'em all (build_and_generate)
  • redux is now a normal behavior/mixin

0.8.3

  • max workers set to 2
  • fixed behaviors generation

0.8.2

  • fixed bad bower dependency calc

0.8.1

  • rewritten to keep most things in dart
  • changed bower strategy (now it is a workspace)
  • added support for bazel workers (still need some optimization)
  • support for latest polymer
  • using SDK ddc instead of extracted DDC package
  • changed module strategy : one file per module makes it possible to load only what is needed

0.7.2

  • upgrade to SDK v. 1.23.0
  • support for dart property getters and setters

0.7.1+1

  • locked analyzer version until we upgrade DDC library (https://github.com/polymer-dart/todo_ddc/issues/5)

0.7.1

  • updated to DDC-2017031301
  • added option to override JS name in generated wrapper

0.7.0+1

  • fixed rules version

0.7.0

  • support for mixin in dart

0.6.1

  • better error handling during setup phase

0.6.0+2

  • minor changes to readme

0.6.0+1

  • minor change to rules

0.6.0

  • changed module name convention - please update polymer_elements and html5 too

0.5.4

  • better error logging

0.5.3

  • added bower_resolutions.yaml optional ovverride for polymerize init

0.5.2

  • fixed bug on generator
  • support for embedded templates

0.5.1

  • changed urls and references

0.5.0

  • added support for mixins
  • better wrapper generation
  • updated polymer analyzer
  • support for REDUX!!!

0.4.5

  • update to latest DDC (dart 1.23-dev.x) - 2017 02 21

0.4.4

  • updated to latest DDC (dart 1.22-dev.x)

0.2.5

  • Updated libs

0.2.4

  • Added support for vanilla WebComponents
  • Fixed for .packages (dart 1.20)

0.2.3

  • Adding support for wrapping external elements (see paper_dialog.dart)
  • Adding support for dynamic load of dart packages
  • Adding support for OBSERVABLE proxy (see todo demo)
  • Cleanups and improvments

0.2.2

  • Rudimental support for custom events

0.2.1

  • changed name to polymerize
  • add commandline args
  • added no emit option (to build libraries apart)
  • copy all web assets (not only index.html)
  • added option for module format (even if ony amd is actually fully supported)
  • added centralized repository

0.1.2+1

  • reset options for compiler

0.1.2

  • repo for compilation
  • copying resources
  • templating

1. Depend on it

Add this to your package's pubspec.yaml file:

dependencies:
  polymerize: "^0.9.5"

2. Install it

You can install packages from the command line:

$ pub get

Alternatively, your editor might support 'pub get'. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use: 

import 'package:polymerize/polymerize.dart';

About

An Polymer 2.x support for Dart/DDC

Author

Email vittorio.ballestra@gmail.com Vittorio Ballestra

Homepage

dart-polymer.com

Documentation

www.dartdocs.org/documentation/polymerize/0.9.5/

Source code (hyperlinked)

www.crossdart.info/p/polymerize/0.9.5/

Uploader

vittorio.ballestra@drafintech.it

Published

Jul 24, 2017

Share