Errai: The browser as a platform

Tuesday, October 21, 2014

Using Polymer's Web Components with Errai

Web Components is an emerging web technology that allows web developers to use custom HTML elements and encapsulation in their applications. Currently, Polymer is the leading web framework that implements this technology. A few members of the Errai community have expressed interest in using Polymer elements in their web apps, hence we spent some time creating an early prototype at Errai Tutorial - Web Components. In this blog post, I will outline the steps needed to use Polymer components with Errai UI in your web application.

Downloading Polymer Elements

Download Polymer and the relevant Polymer components, and place them under src/main/webapp. The Polymer elements and code used in our prototype are located in the components/ directory under src/main/webapp/. Detailed instructions on how to download and update Polymer's libraries and components can be found here.

Using Polymer Elements in Errai HTML Templates

In order to use Polymer elements in your web page with Errai UI, you can create an HTML layout using any combination of Polymer elements and regular HTML elements. For example, this template was created using Polymer's <paper-input> and <paper-button> elements in a <form> element:

The above example will also work with Errai Data Binding. You can further create your own custom element and use it in your HTML template. For information on how to create your own Polymer-based element, see Creating elements - Polymer.

Note: When importing Polymer elements into your app, the polyfill support script (platform.js) as well as the HTML imports required to use each element must be included in your GWT host page.

Integration with GWT

To use Polymer's elements (or your own custom elements) with GWT, we need to create Elements and Widgets, similar to the ones for HTML elements that currently exist in GWT. You can create an Element class for the Polymer element by extending com.google.gwt.dom.client.Element or one of its subclasses. The purpose of this class is to provide Java methods for the Polymer element, by wrapping calls to Polymer's methods and attributes in JSNI code. This Element class represents the Polymer element's DOM implementation.

GWT uses Widget classes that wrap Elements, to provide user interaction capabilities. Thus for all UI-based elements, we need to create a Widget class that extends com.google.gwt.user.client.ui.Widget or one of its subclasses. This Widget class should contain methods to handle user interaction with the Polymer element. Refer to the tutorial and to existing GWT Elements and Widgets for examples on how to create your own custom GWT widgets. Here is an example of how to use the Element class and Widget class to interact with the user and with other widgets in your app. The Polymer element used in this example is the <paper-button>. The example shows how to use the PaperButton Element and Widget classes to add an Enter key handler to the ComplaintForm.

The PaperButtonElement class provides JSNI methods to access the Polymer element's click() method:
The PaperButtonWidget class creates a UI wrapper around the PaperButtonElement:
Finally, the ComplaintForm allows the user to submit the form by pressing Enter, which then calls the methods defined in the PaperButton classes above:

Using Polymer Elements in your web app

As the example in the previous section illustrates, once you have the requisite Element and Widget classes, you can now use the Polymer element as a regular GWT widget in your web page, using @Inject or manual construction. All of Polymer's functionality should be accessible through the Element class, and you can now use the Widget class to make the element interact with the rest of your web app as needed.

Styling Polymer Elements

An important feature of web components is that they provide style encapsulation from the rest of the document. You can take advantage of this feature to style your web components in Errai web apps as well, by using Polymer's style descriptors such as /deep/ and ::shadow (see this link about Polymer styling for more information).

While Polymer's default styling works out of the box, custom styles applied externally to Polymer elements do not. In order to use these styles, you need to add the attribute shim-shadowdom to your style tag. In this tutorial, the shim-shadowdom tag has been added to application.css in the index.html file, to enable external Polymer styling to work.

Note: Currently, while Polymer can prevent styles from leaking out of the element's shadow DOM, styles can still leak into the custom elements' shadow trees. Currently only Google Chrome offers complete style encapsulation. For other browsers, you may need to use custom identifiers to style elements outside of Polymer elements.


The purpose of this Errai Web Components prototype is to illustrate how to use Polymer elements in your Errai web app. This is an early attempt to investigate how Errai can integrate web components into GWT apps. We welcome community feedback, so please feel free to contact us with questions, comments and suggestions regarding the use of Polymer and web components with Errai. 

8 comments:

  1. Thx for this article! I discovered Errai looking up "Polymer and GWT".

    ReplyDelete
  2. This comment has been removed by the author.

    ReplyDelete
  3. I prefer to read the quality content. I like it.

    Nora

    ReplyDelete
  4. Hi,

    Thanks for sharing a very interesting article about Using Polymer's Web Components with Errai. This is very useful information for online blog review readers. Keep it up such a great posting like this.

    Regards,
    WondersMind,
    Web Design Company Bangalore

    ReplyDelete
  5. I'm very happy being Herpes free now. It was a sad incident that was announced to me after the check up in the hospital and I was diagnosed of HSV 2. I thank God now for using Dr.odey Abang to cure my virus. I'm not ashamed to say this because no virus of such can be detected in me. I'm Charlotte from Columbia. I thought about it many Times when I heard about this Herbal cures for Herpes. I was really happy when I came across blogs of comments of Doctors who run cures sicknesses and was comfortable to try Dr. Abang from patients testimony I came across here on my online page. I knew now they are real Africa herbalists who run cures for Herpes. There's every opportunity to be cure with natural herbs, because all medical prescriptions are derived from herbs and roots. Its really hard time living with Herpes on drugs which can't get you cure. I tried this and I can boost of myself now as a woman. I need to be loved not to lost, get your instant cure to all sicknesses from Dr, Odey Abang.
    He cures HSV,HPV,Cancer,low spam count and much more from the evidence I saw 💯 % sure no site effects with active immune booster

    Email him for you cure
    Odeyabangherbalhome@gmail.com
    WhatsApp/calls
    +2349015049094

    ReplyDelete
  6. Nothing is not possible in this word.
    Herpes I cried out for 8moths had a cure and was making use of the Medication that never wanted a life living on drugs, I applied Antibiotics, he prescribed for me the acyclovir(Zovirax), famciclovir (Famvir), andvalacyclovir (Valtrex).
    They never get me cured.
    My God keep blessing you and your Family. Dr
    ODEY ABANG, your a powerful Herbalist fir your work in my life
    I wish you know how I feel inside me when I was making use of does tablets that never could there get me cured. I had to search about some of my favourite blogs when I thought about Dr Odey abang from the testimonies of patients and I remember a friend who told me I should try Dr. Odey Abang herbal medicine. He told me the man can cure me,but was shy and feel its dirty taking in herbs made with African herbalists.
    You need to know I would have been cured before now since I knew him then, but still interested in letting you that was my punishment.
    Thanks reading my article, feel good and not make my mistake, I love testimonies and explanations of the new beginning is all I hope for
    Think about your live and use herbs to get you cured of your challenge on
    HIV/Aids
    SYPHILIS
    DIABETES
    CANCER
    ALL CAN BE CURED WITH MANY OTHERS BY DR. ODEY ABANG
    His email is for you so you speak to him

    Odeyabangherbalhome@gmail.com
    WhatsApp number +2349015049094

    ReplyDelete