Bower integration with Polymerize

In this post we will see how to use a native polymer 2.0 component (a vaadin-grid in this example) in a polymerize project in few seconds.

The long story

Say you’re writing a gorgeous app with dart and polymerize. You are really enjoying how easy is to write new components and assembling them together.

You suddenly realize that you need a table.

You then decide to visit webcomponents.org and look up for some usefull component.

Mmh… let’s see… vaadin-grid … wonderfull! I want it! It has dynamic columns, configurable renderer for both header, footer and cell, easy styling … well documented … and it’s from vaadin! I want it! NOW!

Let’s see how you can do this in a few lines of code.

The project

We start with a bare simple startup project :

git clone https://github.com/polymer-dart/tutorial1.git
cd tutorial1
pub get
pub serve &
atom .

This will clone the repo, and launch pub server and an editor on it.

Then open your browser and point to http://localhost:8080 after a few seconds you will see the bare project page:

bare page

The startup project can be used as a starting point for any polymerize project and it has :

Now let’s see how to add a vaadin grid to the startup project.

Importing the element.

First of all we visit the vaadin-grid page to figure out what its bower reference is:

Than we create a new class in lib/vaadin_grid.dart that maps the native element to a dart class:

    import 'package:polymer_element/polymer_element.dart';

    @PolymerRegister('vaadin-grid',native:true)
    @BowerImport(name:'vaadin-grid',ref:'vaadin/vaadin-grid#v3.0.0',import:'vaadin-grid/vaadin-grid.html')
    abstract class VaadinGrid extends PolymerElement {
    }

Then we add an import directive in my_component.dart :

    // ignore: UNUSED_IMPORT
    import 'package:tutorial1/vaadin_grid.dart';

Finally use the <vaadin-grid> tag inside the my-component :

    <dom-module id='my-component'>
     <template>

       ...

      <vaadin-grid></vaadin-grid>
     </template>
    </dom-module>

Now reload the browser page et voila! The vaadin-grid is served.

If you take a look at the pub serve logs you may see some lines like these :

serve logs

That’s the sign that polymerize noticed a change in the bower dependencies and downloaded the new component for you inside the project.

And that’s it! We got our nice vaadin-grid !

NOTICE : You don’t even have to stop and restart the pub serve, just reload the browser page and you’re done.

Next step : some columns

Ok we got a table, but we need some columns too. No problem! Add a mapping for <vaadin-grid-column> too in vaadin_grid.dart (you’re not forced to create a new file for it if you don’t want) and use it:

@PolymerRegister('vaadin-grid-column',native:true)
@BowerImport(name:'vaadin-grid',ref:'vaadin/vaadin-grid#v3.0.0',import:'vaadin-grid/vaadin-grid-column.html')
abstract class VaadinGridColumn extends PolymerElement {}

Now you can use the <vaadin-grid-column> tag to add columns to the grid (you already imported lib/vaadin_grid.dart):

<vaadin-grid>
    <vaadin-grid-column>
      <template class='header'>First Column</template>
      <template>[[item.col1]]</template>
    </vaadin-grid-column>
    <vaadin-grid-column>
      <template class='header'>Second Column</template>
      <template>[[item.col2]]</template>
    </vaadin-grid-column>
  </vaadin-grid>

Reload the page and here comes the columns!

You can checkout the branch vaadin-integration and see it in action if you don’t want to apply the changes yourself:

git checkout vaadin-integration

(again you don’t even have to stop and start pub serve just reload the page).

Then add some data and here’s the final result :

tut1

Some more details

In order to map a dart class to a native polymer component and import its definition with bower you have to :

If you need to map other properties just use the js-interop pattern (example declare a external List get items for the vaadin-grid items properties).

Polymer Elements

For many of the standard polymer elements there’s a library that you can import in your project polymerize_elements with a git dependency:

polymer_elements:
  git:
   url: https://github.com/polymer-dart/polymerize_elements.git
   ref: v0.4.3

(because we choose to keep the same name of the old polymer_elements library in order to let people migrate easily from dart-polymer projects it won’t be published yet to pub.dartlang.org)

The library is not complete but new components are added constantly.

Conclusions

Consuming native polymer components in polymerize is very easy and effective.

It unleashes the full webcomponents.org potential inside polymerized apps, just try it!