Designing a simple Polymer Web Component: Part 1 – Setup

I thought I’d go through my design process for a web component. There are three pieces to a web component. The HTML markup, the styling and the Javascript to implement it. My side project needs several widgets that I will implement in web components. Getting a good handle on the design process will assist when it comes to that.

Step 1: Have a good idea on what you want to do

It seems silly, but do you know what you want the end product to look like? My top level page is going to be the cast of characters that I have access to. Each one can be a member of a party and/or shared with other people. I would like it to have a picture, the characters name and indicators for whether it is a member of a party or shared. My first attempt is to borrow images from the Internet to design where things are going:


This was done with PowerPoint – I had it handy. However, you can use any tool you care to. Got gimp? An excellent choice. How about Another excellent choice. Just use what you know and have access to.

The idea is that the left hand top icon indicates that the character is a member of a party. The right hand top icon indicates that it is shared. The picture in the middle will either be a default one based on the characters race and class or I will allow the user to upload one. One of the friends I game with draws characters for each of us. Finally, the name of the character is at the bottom. I should be able to click on the whole thing and get the same action – the character sheet is opened. If I roll over the two icons at the top I should be able to see that it is shared (and with whom) and who else is in the party.

Decide on a rough layout

Now that I have the vision in my head, it is time to lay it out. Well, almost. The next step is to take all the imagery out of the equation and decide what blocks go where. I do this in PowerPoint as well, just to get it fixed in my mind. It helps when I am doing the style sheet. Here is what I drew up for my character grid component:


I’ve got a square block which will be dependent on the size of the screen – I’m a fan of responsive design. The icons will be 20% of the size of the block, the character will be 60% of the size. At the bottom is a section for the name of the character.

Decide how to lay out the HTML

When I include this character on the grid I want to specify whether it has the icons, the location of the picture and the name of the character. Something like this:

<dnd-gridcharacter party shared>
    <img src="/avatars/standard/dwarf/cleric.png">

This layout provides everything I could potentially want from the component.

Produce the Template

The next step is to start lay down the template. I’m not going to worry about styling or interactivity at this stage – I just want to start producing the HTML. First of all, I create a directory under my src/elements directory for the element. Then I produce the dnd-gridcharacter.html file:

<dom-module id="dnd-gridcharacter">
    <link rel="stylesheet" href="dnd-gridcharacter.css">
        <div class="content-wrapper">
            <div class="party-icon"></div>
            <div class="share-icon"></div>
            <div class="character-picture"><content select="img"></content></div>
            <div class="character-name"><content select="h1"></content></div>

<script src="dnd-gridcharacter.js"></script>

Here I just used the outline I prepared for the polymer-helloworld.html file and inserted what I think will be my content. Everything is wrapped into a content-wrapper and then I have my four DIV areas to hold the four things I am interested in positioning.

I also need to add in a dnd-gridcharacter.js file that instantiates the web component:

    is: "dnd-gridcharacter",

    properties: {
        party: {
            type: Boolean,
            value: false,
            observer: "party-observer"
        shared: {
            type: Boolean,
            value: false,
            observer: "shared-observer"

You saw the is: property in the Polymer initialization object when I was showing off the polymer-helloworld web component. However you may not have seen the properties. This has changed since the Polymer 0.5 days. In the prior version you could declare properties in the polymer-element element in the HTML file. Properties are now explicitly defined in the Javascript, along with their type and default value.

I also get to decide what type of data-binding I want. Inbound data-binding is implemented by using an observer. The string is the method to be called when a change is noticed. Outbound data-binding is implemented by using notify. In this case, an event is fired when the value of the property changes. You can also do two-way data-binding. Just implement both the observer and notify.

For this application I’m only interested in the inbound data-binding. I won’t be changing the state of party or shared myself. In order to implement the inbound binding, I’ll need to define two functions:

    partyObserver: function (newValue, oldValue) {
        // ... change the party icon according to newValue

    sharedObserver: function (newValue, oldValue) {
        // ... change the shared icon according to newValue

These are defined inside the Polymer object just like is and properties.

Initial Styling

I also want to implement some initial styling based on my PowerPoint. It won’t be right the first go around but it will be something I can play with. I’ll put the stylesheet in dnd-gridcharacter.less:

.content-wrapper {
    display: block;
    position: relative;
    width: 100%;
    height: 100%;
    border: 1px dotted goldenrod;
    padding: 20px;
    background-color: teal;

    .party-icon, .shared-icon {
        position: absolute;
        top: 0;
        width: 20%;
        height: 20%;
        border: 1px dotted red;
        z-index: 5;
        background-color: white;

    .party-icon {
        left: 10%;

    .shared-icon {
        right: 10%;

    .character-picture {
        position: absolute;
        top: 10%;
        left: 20%;
        width: 60%;
        height: 60%;
        z-index: 3;
        border: 1px dotted green;

        img {
            width: 100%;
            height: 100%;

    .character-name {
        position: absolute;
        top: 70%;
        left: 0;
        width: 100%;
        height: 30%;
        text-align: center;
        vertical-align: middle;
        background-color: beige;

        h1 {
            font-size: 36px;
            font-family: 'Segoe Script', cursive;
            color: #33;

This is most definitely the wrong CSS to be using. I’ve given each element a border color and a background. None of the icons or pictures are “there”. I’m hoping the positioning is somewhat good to go. What this does is give me a mechanism by which I can begin to alter the CSS within the browser so I can get it right.

A better designer than I would probably do this process differently. I’ve found I am terrible at understanding what CSS properties affect positioning and how they work when in a responsive display.

Checking it out

I’ve changed my Areas/Main/Views/Index.cshtml file to bring in an example of the work:

@{ ViewBag.Title = "Home Page"; }

<h1>Home Controller</h1>

<div style="width: 500px; height: 500px; position: relative">
    <dnd-gridcharacter party shared>
        <img src="">
@section htmlelements {
    <link rel="import" href="/jspm_packages/github/Polymer/polymer@0.8.0/dist/polymer.html">
    <link rel="import" href="~/elements/dnd-gridcharacter.html">

Note that I’m using a placeholder image site to load an example image. I’ll replace that at a later data – it just isn’t important for me right now. Here is what the initial version looks like:


The good news is that it isn’t terrible. There are some things that are certainly wrong with it. Aside from the borders and colors (that I knew were going to be wrong) the image is the wrong size and in the wrong place, the text is the wrong size and the shared icon area is just not there – probably overlapping the party icon area.

Some things live to see another day. Tomorrow I’ll take a look at the debugging tools for CSS available in Chrome, add in some code to make multiple versions of the grid character so I can see how it scales and generally finish off the component.