The Publishing Project

At the top of the list you have the option to add new presets and customize existing ones. I’ve created one customization to the 3G preset by adding latency to, in my opinion, provide a better representation of network conditions outside urban areas.

Be aware that, while the Network Condition emulator is a good starting point for testing your design under different network conditions, it is not a replacement for testing using actual devices. There are things that a desktop machine cannot simulate including:

• Mobile device startup time
• How many low power cores are started versus how many high powered cores are started in a multi-core devices (not all cores in a multi-core mobile phone are made equally)
• How long it takes for a device to start the wifi receiver

  More information about network conditions available at the Google Developers site

  Related video about mobile performance from Alex Russell at the Chrome Developer Summit 2016.

After a while I discovered why my blog wasn’t highlighting code as I wanted it to. Plugins are too old and the Markdown plugin in Jetpack is not producing the correct HTML from the Markdown I’m writing.

I’ve spent the last few days trying to update plugins with a recent version of Prism that has the plugins I want to use and the languages I want to use are properly configured.

Instead of creating a plugin (which may be a future project) I’ve chosen to add this to my theme’s functions.php and evaluate how it works and then decide if and how to incorporate it to my production site.

The process takes 3 steps

1. Upload the Prism CSS and Javascript files to your server
2. Add the functions to the theme’s functions.php
3. Edit the content of your database to make the changes to how the languages are written in the HTML

We’ll cover these steps individually.

Upload the Prism files to your server

I won’t tell you how to upload your files. You can use (s)ftp, your control panel, whatever you choose is fine. The important thing is to put it inside your theme under the /prism/ path: /prism/css for style sheets and /prism/js for your stylesheets.

Once that’s done we can move to the next step: Adding the functions to load the script and stylesheet.

Add the functions to the theme’s functions.php

The fuction add_prism registers and enqueues the stylesheet and javascript files for Prism.

// Function to add prism.css and prism.js to the site
function add_prism() {
    wp_register_style('prismCSS', 
    get_stylesheet_uri() . '/prism/css/prism.css'
  );
  // Register prism.js file
  wp_register_script(
    'prismJS', // handle name for the script
    get_stylesheet_uri() . '/prism/js/prism.js'
  );

  // Enqueue the registered style and script files
  wp_enqueue_style( 'prismCSS');
  wp_enqueue_script( 'prismJS' );
}
add_action('wp_enqueue_scripts', 'add_prism');

The problem is that even after adding these functions we will not get the results I want. It turns out that Jetpack’s Markdown parser does not change the name of the code fence. When I write a Javascript fenced block like this (the closing of the fenced block has a backslash () on purpose, otherwise it will not display)

```jvascript
// code goes here 
\```

Jetpack produces the following HTML:

<pre><code class="javascript">
// code goes here
</code></pre>

which is not what I expect to see, I expect to see something that will work with a syntax highlighter like the code below.

<pre><code class="language-javascript">
// code goes here
</code></pre>

I’ve contacted Jetpack support and I hope for a quick resolution moving forward but there is likely no easy way to fix existing posts (over 100 of them) other than editing the database.

Edit the content of your database

There are two ways of updating content in your database.

The first one is to open phpMyAdmin, clicking on your WordPress database, selecting the SQL tab and running the following command where text to find correspond to the existing values column and text to replace with is the new value.

update wp_posts set post_content =
replace(post_content,'Text to find','text to replace with');

I tried this way and screwed up my development system so I quickly retored from my phpMyAdmin backup and wwent to the drawing board.

Through one of the tutorias I read to figure out how to do this I found a WordPress plugin, Better Search Replace, that will let me do this from within WordPress and hopefully it’ll save me from myself and my own stupidity.

I installed and activated the plugin in my development system and tested it… It worked perfectly.

I did the same thing in production and it worked just as fine 🙂

The table below shows the languages that I searched for and (left column) and what I replaced with (right side). I probably missed some. If you find any code block that is not highlighted, please let me know.

Conclusion

Working with WordPress is not always easy but you can usually get a working solution if you’re willing to put in the work.

Jetpack support got back to me and confirmed that the issue is a bug on their Markdown parser and suggested a solution. When the parser is fixed the solution will stop working, I think, but now I know how to fix these problems 🙂

Finally, these are the two resources I used to create the solution:

• How to Find and Replace Text with One Click in your WordPress Database
• How To Implement Prism.js Syntax Highlighting Into Your WordPress Site

I’ve been playing with web components for a few years. Until not too long ago the biggest drawback was that only one browser supported the original (v0) family of Web Component specifications. Things are looking better now.

V1 of most web component specifications, Templates, shadow DOM and Custom Elements, are supported in most major browsers with HTML Imports being the only part of Web Components where vendors have not agreed on implementation and are waiting for ES6 modules to become more widely adopted before deciding where the future of this specification lies.

What are Web Components

For those of you who are not familiar with them. Web Components is a set of four specifications being worked on at W3C and WHATWG. The specs are:

• Custom Elements
• shadow DOM
• Templates
• HTML Imports

On their own each of these technologies enhance web development.

Custom Elements allow developers to create new HTML elements and integrate them into existing web content.

shadow DOM allows for encapsulation. The content you create is hidden from end user’s scripts and stylesheets. The styles in your element cannot style elements outside and vice versa.

Templates give us the possibility of creating inert HTML that will only become live when the custom element the template is attached to the live DOM on the browser.

HTML Imports are a declarative way to include external resources in our pages. There is very little interest from browser vendors other than Google to implement HTML Imports. Because of this we need to wait until an alternative proposal like [HTML Modules](HTML Imports and ES Modules), a reformulation of HTML Imports based on ES2015 modules. Until then remember, polyfills are your friends.

We’ll explore how to combine these 4 technologies (as currently implemented and polyfilled) to create composable and reusable content that makes it easier to create book-like resources.

Assumptions

Before diving into what we’re building I want to touch on some of the assumptions I’m making.

Because web components must have a - character as part of the name and must start with a lowercase character (see the spec, I’ve chosen to use wcp- for all the web components I’m building as part of this project.

All styles, content and scripts will be hidden inside the component’s shadow DOM. It’s not 100% foolproof but it will hide the element’s styles and scripts from most casual scans and, I hope, that will be enough to discourage overrides as the overrides will become more complicated if they have to pierce the shadow boundary, it’s possible but I wonder if it’ll be worth the effort.

Web components should be fully interoperable so we can look at the catalog at webcomponents.org to look for additional components to test the hypothesis with.

I’m particularly interested in the Google elements that provide declarative access to Google APIs and resources.

Because we’re working with modern web technologies we must polyfill depending on the browser we use, not all browsers support all the Web Components specifications. See below
for the polyfills’ complete browser support matrix:

*Indicates the current version of the browser

Making the case for web components in publishing

Let’s think of web components as patterns: reusable pieces of code that we can use in different pages and contexts.

We can also come to an agreement on how we build those components and how much we choose to override them as content creators, publishers and tool creators.

An example of this is Google’s Accelerated Mobile Pages (AMP) project. They’ve subset HTML, provided their own set of custom elements (AMP HTML) and Javascript to handle ads and other potential performance bottlenecks. While AMP is geared towards mobile performance, the proposed set of components seeks to provide a starting point for common development and a unified user interface where vendors don’t feel the need to override all properties.

Because we encapsulate the components inside a shadow DOM we protect the content from outside misuse. This is similar but not identical to what browser vendors themselves use to compose elements like <video> and <select>. We can provide minimal styles that are encapsulated to the element, the styles will not bleed out and that styles of the host document will not bleed in. Furthermore we can use CSS variables to create themes for our elements and use attributes in the element to indicate the theme and javascript to toggle it when needed.

We can work on best of breed components. Because these components are reusable they live beyond the developer or team that created them and beyond the framework the team uses for the server portion of the application. If we’re creating static content such as books then we can use interoperable components from our own libraries, libraries from other publishers and libraries from vendors like Polymer, X-Tags, Bosonic, Skate, Aurelia and others that may become available in the future.

Faster development cycle and high reuse potential means that developers will spend time in each book and be able to deliver faster turnaround at lower costs for each project.

The components

The first question to ask is what components should we build. I’ll take some components that I had originally developed as Polymer 0.5 and 1.0 components and some new ideas for layout and composition. I will create the components as bare metal V1 components. These components include:

• Local video player (DASH video)
• Local video player (locally hosted content)
• Youtube video player
• Markdown parsed content
• Table of contents
• Content layout
• Masthead

If you have more ideas of what components we should build let me know via twitter or email.

The second question is whether we want to build our publications as Progressive Web Applications.

The best example I found is Resilient Web Design by Jeremy Keith. It gives us a lot of the functionality that we get from epub readers but it’s all web based and it gives access to several features that will enrich our content.

Building a barebones component

For this section I’ll build a basic hello-world type element that I’ll name wcp-hello-world. I created a directory to hold all the experiments, wcp-demo:

mkdir wcp-demo
cd wcp-demo

Inside wcp-demo I initialize an NPM package.json and will accept all defaults automatically. The second command will create a bower.json file and ask you to answer a set of questions… Either of these files can be manually edited later.

npm init --yes
bower init

Now I’m ready to start coding. All V1 custom elements, the basis for our web components, must be written as ES6 classes. I’ve covered ES6 classes in my blog (Babel and You: Exploring the new Javascript) so I’ll only gloss over them and just discuss their application to custom elements and web components.

Example 1 shows a minimal custom element.

The HelloWorld class extends HTMLElement, the parent class for all elements in a web page.We create the constructor and, inside the constructor, we call super() which will call the parent’s (HTMLElement) constructor. Custom elements must call super as the first item in their own constructors.

Outside the class we define the custom element using customElements.define with two attributes: the name of the element as we’ll use it and the name of the class that actually defines the element.

<!DOCTYPE html>
<html>
  <head>
    <title>custom element demo</title>
    <style></styles>
  </head>
  <body>
  <script>
    // Example 1: Basic Empty Custom Element
    class HelloWorld extends HTMLElement {
      constructor() {
      super();
    }
  }
  customElements.define('wcp-hello-world', HelloWorld);
  </script>
  </body>
</html>

Example 1 will not give you an error but will not produce results either. Before we jump into adding content to the element we have to decide when we want to do so. Enter the lifecycle callbacks. Each reaction happens in response to a given event as discussed in the table below.

For this particular case I don’t want to add the content until the element is added to the DOM so I’ll use the connectedCallback reaction to add my content. In Example 2 I will add the content directly on the connectedCallback event.

< !DOCTYPE html>
<html>
  <head>
    <title>custom element demo</title>
    <style>
  </style></head>
  <body>
  // Example 2: adding content on connectedCallback
  class HelloWorld extends HTMLElement {

    constructor() {
      super();
    }

    connectedCallback() {
      this.innerHTML = `<h1>Hello World</h1>`;
    }
  }
  customElements.define('wcp-hello-world', HelloWorld);

  </body>
</html>

So now, whenever we add an instance of wcp-hello-world to a page (and we’ll cover how to do that later on) we’ll see the string <h1>Hello World< \h1> string. But we’ll see the same string every single time. To fix this we’ll take a three step approach:

• We’ll create a template for wcp-hello-world
• We’ll modify the template by adding slots to it
• We’ll attach the template to the custom element’s shadow DOM

Creating the template

The template element is part of the HTML specification so, in theory, it could be used anywhere in our web pages. When used in web components what we’re doing is creating the basic structure for our element by providing default styles and content.

I’ve given the template an ID to make it easier to use from Javascript later when we attach it to the shadow DOM.

<template id="wcp-template">
  <style>
    h1 {
      color: rebeccapurple;
    }
  </style>
  <h1>Hey</h1>
</template>

Adding slots

This works in giving the custom element structure but it will return the same content every time we add the element to the page. We need a way to customize the content of the element.

The <slot> element takes care of this. We can create generic slots or, like I’ve done in this example, provide names that will be associated with the content we add in the host element. It also provides a default value when the host page provides no content.

<template id="wcp-template">
  <style>
    h1 {
      color: rebeccapurple;
    }
  </style>
  <h1><slot name="greeting">Hey</slot></h1>
</template>

Creating the shadow DOM and attaching the template

So far all our custom elements can be modified at will. In Javascript we could do something like this to modify the content of our custom element:

let myEl = document.getElementById('wcp-hello.world');
myEl.innerHTML = "New content";

This may not be what we want; we may want to hide the details of our custom element from the outside world and that’s where the shadow DOM comes in. shadow DOM provides encapsulation for our CSS, and HTML content… this is what make it possible to keep our CSS from bleeding out and external content from bleeding into our element.

To use shadow DOM we need to do the following:

1. Create a variable to hold our imported document path using document.currentScript.ownerDocument
2. Capture our template into a variable
3. Create a shadow root (the entry point to an element’s shadow DOM) using attachShadow
4. Append the template to the shadow root.

<script>
  var importedDoc = document.currentScript.ownerDocument; // 1
  class HelloWorld extends HTMLElement {
    constructor() {
      super();

      const template = importedDoc.querySelector('#wcp-template').content; // 2

      const shadowRoot = this.attachShadow({mode: 'open'}); // 3
      shadowRoot.appendChild(template.cloneNode(true)); // 4
    }
  }

  customElements.define('wcp-hello-world', HelloWorld);
</script>

Some things to consider:

An element (custom or otherwise) can only have one shadow root. The browser will report an error if you try to create more than one.

You can add elements to the template programmatically.

The complete element

So we’ve seen how to create custom elements, how to create templates and attach them to a shadow root. The full element using all the techniques we’ve covered so far looks like this

<!-- wcp-hello-world.html -->
<template id="wcp-template">
  <style>
    h1 {
      color: rebeccapurple;
    }
  </style>
  <h1><slot name="greeting">Hey</slot></h1>
</template>

<script>
class HelloWorld extends HTMLElement {
  constructor() {
    super();

    var template = document
      .getElementById('wcp-template')
      .content;

    const shadowRoot = this.attachShadow({mode: 'open'})
      .appendChild(template.cloneNode(true));
    }

  connectedCallback() {}
}

customElements.define('wcp-hello-world', HelloWorld);
</script>

Testing the element

To add components to a page we need to make sure that it’ll work in as many browsers as possible. To do that we’ll use the web components polyfills from webcomponents.org. We gave to go with the Github distribution since the page at webcomponents.org references old polyfills that will not work with this project.

We’ll use Bower to install the polyfills:

bower install --save webcomponents/webcomponentsjs

When we create the page that will host our component we need to make sure that we can use them. We’ll use conditional loading to only load the polyfills where the APIs are not supported. if we support custom elements, HTML Imports and Templates then we just log to console that we’re good to go, we don’t need to load the polyfills.

If the APIs are not supported then we create a script element, attach the polyfill script as the source of the script and then append it to the head of the page.

// Feature detection for web components
(function() {
  if ('customElements' in window)  
    && 'import' in document.createElement('link')
    && 'content' in document.createElement('template')) {
    // platform is good!
    console.log('we\'re good to go');
  } else {
    // polyfill the platform!
    console.log('we need to polyfill');
    var e = document.createElement('script');
    e.src = '/bower_components/webcomponentsjs/webcomponents-lite.min.js';
    document.body.appendChild(e);
  }
})();

Now that we’ve covered the polyfill we can create a page to test the wcp-hello-world element we’ve been playing with.

<!DOCTYPE html>
<html>
  <head>
    <title>slot example</title>
    <meta charset="UTF-8">
    <style></style>
    <link rel="import" href="wcp-hello-world.html">
    <script>
      (function() {
        if (('customElements' in window)
            && ('import' in document.createElement('link'))
            && ('content' in document.createElement('template'))) {
          // platform is good!
          console.log('Polyfills not needed');
        } else {
          // polyfill the platform!
          console.log('we need to polyfill');
          const scriptEl = document.createElement('script');
          scriptEl.src = './bower_components/webcomponentsjs/webcomponents-lite.js';
          document.head.appendChild(scriptEl);
          console.log('script appended');
        }
      })();
    </script>
  </head>
  <body>
    <wcp-hello-world></wcp-hello-world>
    <!-- produced the default Hello World -->
    <wcp-hello-world>
      <span slot="greeting">What's up?</span>
    </wcp-hello-world>
    <!-- produces What's up -->
  </body>
</html>

We’ll then have a full example using three of the four specifications from the Web Components family: custom elements, templates and shadow DOM. From here we can import multiple components into our HTML host page, nested element imports, continue experimenting with both structural styles and event based propagation but the basics are there. If we choose to create components to build layouts the techniques are not much different than what we’ve covered so far.

We’ll discuss more of this later when we talk about different composition strategies and again when we discuss creating a build process for our components.

Observed Attributes and Changing Those Values

Attributes are a good way to provide initial state and values for our elements. For example, we can add a name attribute to a <greeting -element> to tell the browser who the greeting is for:

<greeting-element name="Arwen"></greeting-element>

The script uses the static get observedAttributes() method to tell the browser what elements will be observed for changes. This means that if there are other attributes in our greeting-element component they will not trigger the attributeChangedCallback reaction for our component.

Because we can monitor multiple attributes, attributeChangedCallback uses an if statement to test which element changed. We could use a switch statement rather than if, it’s your preference.

class GreetingElement extends HTMLElement {
  // Monitor the 'name' attribute for changes.
  static get observedAttributes() {return ['name']; }

  // Respond to attribute changes.
  attributeChangedCallback(attr, oldValue, newValue) {
    if (attr == 'name') {
      this.textContent = `Hello, ${newValue}`;
    }
  }
}

// Define the new element
customElements.define('greeting-element', GreetingElement);

We can also use the attributeChangedCallback reaction to add or modify accessibility attributes like aria-*, visibility attributes or anything that we do to keep our content accessible, even if it’s not visible from the host document.

Styles and Overrides

One of the things that attracted me to web components and Polymer is the ability to hide the details of our elements’ implementations and APIs behind a shadow DOM, the same way that browser vendors have built elements like video and select.

What advantages do we get when we use shadow DOM?

• Isolated DOM: A component’s DOM is self-contained (e.g. document.querySelector() won’t return nodes in the component’s shadow DOM)
• Scoped CSS: CSS defined inside shadow DOM is scoped to it. Style rules don’t leak out and page styles don’t bleed in
• Composition: Design a declarative, markup-based API for your component
• Simplifies CSS – Scoped DOM means you can use simple CSS selectors, more generic id/class names, and not worry about naming conflicts

So we get the best of both worlds. We get smaller components that are reusable and have styles that will not bleed out to the host page, however, a rule in the host page will always win against a CSS rule in the scoped styles of the shadow DOM so I would only add styles to setup the structure of a component and let the host page style for typography or any other non-structural elements. This may also help with fallback options

This is where collaboration and agreement is important. We can choose to encapsulate all our styles so that each component renders the same regardless of what browser we use to view it or we can just provide layout CSS and let the host page dictate the styles for typography and other requirements and let the CSS cascade do its work.

Composition strategies

As a developer it’s always easier to give my customers a read-made solution that will involve a minimum amount of work (and the possibility of them breaking things) on their end. Web components introduce different concepts for composition:

1. Slotted type composition where we mix light (host page) and shadow (web component) DOM. This is what we did in the wcp-hello-world example. We created a slot and we populated in the host document
2. We can nest components. In one component declaration we can import and nest other components in as granular fashion as we want. We can choose how small we want to go with components or how big we want to be
3. We can mix and match the first two approaches to best suit our needs. Some components can use slots to let authors generate their content and can also be nested inside larger portions of our applications

One of the first decisions

How well does it fail? Aiming or accessible components

One thing that I’ve been debating is whether polyfilling is absolutely necessary or whether we should provide a complete alternative for our components. This stems from my fear for when Javascript doesn’t load or is slow enough that it’ll make people leave the application. This is no different than my criticism of other frameworks that wrap all the content on Javascript and provide no fallback or accessibility options.

If a component is not upgraded and it uses slots as composition tools we can still style the content in the host page and, in theory, we should still get the content. Given that no browser will support HTML Imports, and the ones that do are beginning the removal process for the feature, we should start looking at alternatives.

From a strict accessibility point, we have a few options:

We can extend subclasses of HTMLElement and gain all the accessibility benefits of the built-in element and not have to reinvent the wheel.

In this example we create a customized button called plastic-button using ES6 classes.

The first difference is that instead of extending HTMLElement we extend one of HTMLElement’s children elements, HTMLButtonElement.

The second change is how we define the custom element. When we define the element (in customElements.define) we add the extends keyword indicating the element that we are extending.

class PlasticButton extends HTMLButtonElement {
  constructor() {
    super();

    this.addEventListener("click", () => {
      // Add custom behavior for the click event
      // Maybe an animation?
    });
  }
}

customElements.define("plastic-button", PlasticButton, { extends: "button" });

The final change is how we use the element. We use the is attribute to indicate what kind of button it is. The value of is must match the name of t he element we defined.

<button is="plastic-button">Click Me!</button>

Unfortunately, Apple has all but killed this option as they have repeatedly said that WebKit will not implement this type of custom elements.

The other, definitely less appealing, option is to code accessibility into our elements. The example below, taken from the Custom Elements specification (Section 2.1.3: Drawbacks of autonomous custom elements) shows how much work we have to do to make the content accessible, something we get for free when use native elements.

class TacoButton extends HTMLElement {
  static get observedAttributes() {
    return ["disabled"];
  }

  constructor() {
    super();

    this.addEventListener("keydown", e => {
      if (e.keyCode === 32 || e.keyCode === 13) {
        this.dispatchEvent(new MouseEvent("click", {
          bubbles: true,
          cancelable: true
        }));
      }
    });

    this.addEventListener("click", e => {
      if (this.disabled) {
        e.preventDefault();
        e.stopPropagation();
      }
    });

    this._observer = new MutationObserver(() => {
      this.setAttribute("aria-label", this.textContent);
    });
  }

  connectedCallback() {
    this.setAttribute("role", "button");
    this.setAttribute("tabindex", "0");

    this._observer.observe(this, {
      childList: true,
      characterData: true,
      subtree: true
    });
  }

  disconnectedCallback() {
    this._observer.disconnect();
  }

  get disabled() {
    return this.hasAttribute("disabled");
  }

  set disabled(v) {
    if (v) {
      this.setAttribute("disabled", "");
    } else {
      this.removeAttribute("disabled");
    }
  }

  attributeChangedCallback() {
    // only is called for the disabled attribute due to observedAttributes
    if (this.disabled) {
      this.removeAttribute("tabindex");
      this.setAttribute("aria-disabled", "true");
    } else {
      this.setAttribute("tabindex", "0");
      this.setAttribute("aria-disabled", "false");
    }
  }
}

I will continue working with the first option as it will reduce the workload and it’s easier to rationalize through the workflow. I believe the is keyword is essential for accessibility and it shouldn’t be removed from the spec at all, despite what Apple and Webkit want.

Only time will tell.

Build System for Web Components

One of the most complicated things (from my perspective) is how to create a good tooling set for web components. The way we build vanilla components (components built using plain CSS and Javascript) is tedious and error prone so we need to figure out what the best toolchain is.

Polymer CLI provides a Node-based to to scaffold your web components. It also provides build and serving tools for your components.

Even though the tools are created by the Polymer team and have a definite Polymer bent they also provide scaffolding for vanilla custom elements with only Javascript.

We’ll cover these aspects of the Polymer CLI tool:

• Generating new pure Javascript custom elements
• Building and running tests for the elements
• Bundling our elements and getting them ready for production
• Serving our content during development
• Generating a service worker for the code we create

Before we begin: install polymer-cli

Polymer-cli is a node module. Install it globally on your system running:

npm install -g polymer-cli

This will make the polymer command available on your terminal. This is what we’ll use to interact with the CLI tools. To get an idea of what we can do with the tool, type polymer --help on your terminal; you should get output similar to this:

Usage: `polymer <command /> [options ...]`

Available Commands

  analyze   Writes analysis metadata in JSON format to standard out
  build     Builds an application-style project
  help      Shows this help message, or help for a specific command
  init      Initializes a Polymer project
  install   installs Bower dependencies, optionally installing "variants"
  lint      Identifies potential errors in your code.
  serve     Runs the polyserve development server
  test      Runs web-component-tester

Global Options

  --env type                      The environment to use to specialize certain commands, like build
  --entrypoint                    The main HTML file that will be requested for all routes.
  --shell string                  The app shell HTML import
  --fragment string[]             HTML imports that are loaded on-demand.
  --root string                   The root directory of your project. Defaults to the current working
                                  directory.
  --sources string[]              Glob(s) that match your project source files. Defaults to `src/**/*`.
  --extra-dependencies string[]   Glob(s) that match any additional dependencies not caught by the  
                                  analyzer to include with your build.
  -v, --verbose                   turn on debugging output
  -h, --help                      print out helpful usage information
  -q, --quiet                     silence output

Run `polymer help <command />` for help with a specific command.

Generating new custom elements

We can create many types of custom elements using Polymer-cli’s init command. Run the following commands to generate a new vanilla element.

mkdir wcp-masthead #1
cd wcp-masthead #2
polymer init #3

These commands will perform the following actions:

1. Create a directory for the wcp-masthead element
2. Change to the directory we created in step 1
3. Initialize an element using Polymer-cli

Polymer-cli will present you a menu of options; you can navigate the menu using up and down arrow keys. The options are shown below.

? Which starter template would you like to use? (Use arrow keys)
❯ polymer-1-element - A simple Polymer 1.0 element template
  polymer-2-element - A simple Polymer 2.0 element template
  polymer-1-application - A simple Polymer 1.0 application template
  polymer-2-application - A simple Polymer 2.0 application
  polymer-1-starter-kit - A Polymer 1.x starter application template, with navigation and "PRPL pattern" loading
  polymer-2-starter-kit - A Polymer 2.x starter application template, with navigation and "PRPL pattern" loading
  shop - The "Shop" Progressive Web App demo
  polymer-starter-kit-custom-build - A starting point for Polymer 1.0 custom build apps
  vanilla-web-component - A starting point for building a vanilla web component element

For this example we’ll use the last option: vanilla-web-component.

Running the init command will ask you a few questions, create the component and then run Bower to install the element’s dependencies. The result will be a tree like the one below.

├── README.md
├── bower.json
├── bower_components
│   ├── accessibility-developer-tools
│   ├── async
│   ├── chai
│   ├── font-roboto
│   ├── iron-demo-helpers
│   ├── iron-flex-layout
│   ├── iron-location
│   ├── lodash
│   ├── marked
│   ├── marked-element
│   ├── mocha
│   ├── polymer
│   ├── prism
│   ├── prism-element
│   ├── shadycss
│   ├── sinon-chai
│   ├── sinonjs
│   ├── stacky
│   ├── test-fixture
│   ├── web-component-tester
│   └── webcomponentsjs
├── demo
│   └── index.html
├── index.html
├── package.json
├── test
│   ├── index.html
│   └── wcp-masthead.html
└── wcp-masthead.html

This may look like a lot but it’s about as much as we need to work on creating a successful element. We’ll cover other areas of interest as we move through the different CLI options.

Building and running tests for the elements

The Polymer team create Web Component Tester as a wrapper for testing libraries to work with web components. We create the element’s tests in Javascript in a script attached to an HTML document (created by the cli’s init task) where suite indicates a collection of tests and test indicates individual tests to run against the element.

<script>
  suite('wcp-masthead', function() {

    test('instantiating the element with default properties works', function() {
      var element = fixture('BasicTestFixture');
      assert.equal(element.prop1, 'wcp-masthead');
      var elementShadowRoot = element.shadowRoot;
      var elementHeader = elementShadowRoot.querySelector('h2');
      assert.equal(elementHeader.textContent, 'Hello wcp-masthead!');
    });

    test('setting a property on the element works', function() {
      var element = fixture('ChangedPropertyTestFixture');
      assert.equal(element.prop1, 'new-prop1');
      var elementShadowRoot = element.shadowRoot;
      var elementHeader = elementShadowRoot.querySelector('h2');
      assert.equal(elementHeader.textContent, 'Hello new-prop1!');
    });

  });
</script>

A good tutorial is Test your elements with Web-Component-Tester (Polymer)! and, because it wraps around existing libraries such as Mocha and Chai you can google for tutorials on those libraries.

Bundling Applications and preparing for deployment

Once you have your elements ready for production we can use Polymer-CLI (and Polymer Build under the hood) to bundle your content and prepare for delivery both as a bundled application for HTTP 1.x servers and an unbundled version for HTTP/2, both versions are ready to upload when you’re done.

The build process gives you a service worker as part of the build process. You no longer have to worry about the elements that will go into the shell and what can be lazy loaded.

Polymer Build also allows you to customize the build process and to use the tool outside the CLI and directly in Gulp. For more details see Polymer Build’s README on Github.

Serving our content during development

The last important task is to serve our components and applications. Polymer provides a development server to test elements and applications.

To use the server run the following command:

polymer serve

To view the demo, point your browser to one of the following URLs.

Element project demo:

http://localhost:8080/components/my-el/demo/

Element project API reference:

localhost:8080/components/my-el/

App project demo:

http://localhost:8080

Alternatives

So far I’ve concentrated on Vanilla components because I don’t want to tie the ideas in this article to any one framework. It is worth considering other alternatives for creating components and applications.

My favorite library for creating web components is Polymer 2.0. The library extends vanilla elements and provides a layer of sugaring to make it easier to work with components.

Other libraries like X-Tags, Bosonic, Skate, Aurelia provide abstractions and different levels of sugaring… Since most of these libraries use the same polyfills they should theoretically be interoperable and components from all these libraries (as well as vanilla components) should be able to coexist in the same page.

This is where future research should happen 🙂

Links

• Web Components v1 – the next generation
• Custom Elements v1: Reusable Web Components
• Shadow DOM v1: Self-Contained Web Components
• The case for custom elements, part 1
• The case for custom elements, part 2
• Custom Elements That Work Anywhere
• Bringing componentization to the web: An overview of Web Components
• Microsoft Edge and Web Components
• Extensible web components
• Web Components and progressive enhancement
• Polymer CLI package
• Polymer CLI Docs
• Polymer Build

There is a suggested change to Babel that may change the way you write your configurations, builder tasks and other aspects of your Babel configuration.

In the blog post Upgrade to Babel 7 (WIP) the Babel maintainers give information on how upcoming changes will affect Babel installations.

The one I’m concerned about is how to use yearly plugins. The posts states that:

Instead of any yearly preset, we suggest that you use the newly created babel-preset-env which uses the correct plugins based on your environment.

When configuring Babel you’d normally use the following:

{
  "presets": ["es2015", "es2016", "es2017"]
}

My configuration file looks like this

gulp.task('babel', () => {
  return gulp.src('src/es6/**/*.js')
    .pipe($.sourcemaps.init())
    .pipe($.babel({
      presets: ['es2015', 'es2016', 'es2017']
    }))
    .pipe($.sourcemaps.write('.'))
    .pipe(gulp.dest('src/js/'))
    .pipe($.size({
      pretty: true,
      title: 'Babel'
    }));
});

The idea is that both of the examples above use the presets directly and, regardless of the level for ES6, 7, or 8 in your browser, it’ll load all the presets needed for each yearly plugin.

Instead the new recommended way to go is use the babel-preset-env plugin that will only load the transformations that you need for your target browsers.

Used in combination with stage-1, stage-2 and stage-3 presets we can get fuller coverage of what we want on Javascript.

Leaving the targets attribute blank makes preset-env equivalent to preset-latest in terms of functionality.

If we want to use preset-env and all the stages plugins we can do something like this in the babelrc.json configuration.

{
  "presets": ["env","stage-1","stage-2","stage-3"]
}

If we want to specify what versions of browsers we want to support then we can specify the targets parameter and provide a list in the same way we do for Autoprefixer. The following example uses the last two versions of browsers and Safari 7+

{
  "presets": [
    ["env", {
      "targets": {
        "browsers": [
          "last 2 versions", 
          "safari >= 7"
        ]
      }
    }, 
    "stage-1",
    "stage-2",
    "stage-3"
    ]
  ]
}

an equivalent Gulp task would look like this

gulp.task('babel', () => {
  return gulp.src('src/es6/**/*.js')
    .pipe($.sourcemaps.init())
    .pipe($.babel({
       presets: [
         ["env", {
           "targets": {
             "browsers": [
               "last 2 versions", 
               "safari >= 7"
              ]
            }
        }, 
        "stage-1",
        "stage-2",
        "stage-3"
        ]
      ]
    }))
    .pipe($.sourcemaps.write('.'))
    .pipe(gulp.dest('src/js/'))
    .pipe($.size({
      pretty: true,
      title: 'Babel'
    }));
});

When we last discussed encoding DASH adaptive streaming we saw that Shaka Packager creates the master file and a series of segments. We left them in the browser’s cache which may force downloads and will not work when offline or with poor connectivity.

Using a service worker we can create a cache for media segments so they can be stored locally for offline use. For this to work we need to do some modifications to our standard service worker to acommodate the special requirements of DASH chunked video.

The first step is to create a variable to hold the name of the cache. We then create a function to determine if we should cache the resource… for this particular case we want to cache files ending in mp4 and m4s (MP4 files and MP4 segments)

var CACHE_NAME = 'segment-cache-v1';

function shouldCache(url) {
  return url.endsWith('.mp4') || url.endsWith('.m4s');
}

the loadFromCacheOrFetch function is the core of this service worker. It will open the specified cache and try to match the request.

If the request matches an item in the cache then it will return that item. The fragment will have an additional header that we add when we cache the item.

If the request doesn’t match then we take a clone of the request and fetch it. This is where another peculiarity of working with DASH video comes in. A service worker cannot cache partial responses (HTTP 206) so we have to check if the response is ok, did not return a status code 206 and is one of the items we should cache. Only if the three conditions are met we fetch the resource and store it in the cache using the cacheResponse function.

function loadFromCacheOrFetch(request) {
  return caches.open(CACHE_NAME)
  .then(cache => {
    return cache.match(request)
    .then(response => {
      if (response) {
        console.log('Handling cached request', request.url);
        return response;
      }

      return fetch(request.clone())
      .then(response => {
        if (
          response.ok && 
          response.status != 206 && 
          shouldCache(request.url)) {
          console.log('Caching MP4 segment', request.url);
          cacheResponse(cache, request, response);
        }

        return response;
      });
    });
  })
}

The cacheResponse function modifiess the response object before putting it in the cache. Because the response is read onl we have to recreate it if we’ll make any changes.

We create an array of the data we want to pass to the response object when we actually cache it, that’s why the response has uses two parameters, an arrayBuffer and the array that we creted with response data and header.

Response objects are single use. This means we need to call clone() so we can both store the ArrayBuffer and give the response to the page.

function cacheResponse(cache, request, response) {
  var init = {
    status: response.status,
    statusText: response.statusText,
    headers: {'X-Shaka-From-Cache': true}
  };

  response.headers.forEach((value, key) => {
    init.headers[key] = value;
  });

  return response.clone().arrayBuffer()
  .then(ab => {
    cache.put(request, new Response(ab, init));
  });
}

The final piece is the fetch event itself which responds using the loadFromCacheOrFetch function.

self.addEventListener('fetch', (event) => {
  event.respondWith(loadFromCacheOrFetch(event.request));
});

In a larger service worker we could use a different

self.addEventListener('fetch', (event) => {
  if (event.request.url.endsWith('.mp4') || event.request.url.endsWith('.m4s')) {
    event.respondWith(loadFromCacheOrFetch(event.request));
  }
});