Custom components upgrade guide

Why should you upgrade your custom components?

As of July 2021, Google Web Designer no longer supports v0 custom components. You should upgrade any outdated custom components so that they follow the custom elements v1 specification.

Is my custom component outdated?

Google Web Designer warns you when opening a document which contains an outdated custom component. Additionally, a warning indicator appears in the Components panel next to the component name, and a different icon indicates outdated custom components on the stage.

You can also check the component's source files. In the following example, we use the outdated version of the QR code custom component.

manifest.json

New custom components have a field named customElementsVersion in their manifests. This field indicates which version of the custom elements specification the component is written for:

{
  ...
  "customElementsVersion": 1,
  ...
}

Outdated custom component manifests don't have this field at all.

myqrcode.js

Outdated components use the document.registerElement() method during registration.

Outdated (Custom Elements v0)

document.registerElement('my-qrcode', {prototype: proto});

Updated components use the customElements.define() method instead.

Current (Custom Elements v1)

customElements.define('my-qrcode', MyQrcode);

If your component file contains the term document.registerElement, it is outdated. You can update your component by following the steps below.

Upgrade steps

1. Update the component manifest

Update the component's manifest to include the new customElementsVersion field. Also, increment the version number so that Google Web Designer recognises that the component has changed.

manifest.json

{
  "name": "QR Code",
  "type": "my-qrcode",
  "tagName": "my-qrcode",
  "customElementsVersion": 1,
  "version": 2,
  "description": "Generates a QR code image for the specified data.",
  "files": {
    "js": [
      "qr.js",
      "myqrcode.js"
    ]
  },
  "attributes": [
   {
    "name": "data",
    "label": "Data",
    "type": "string",
    "required": true,
    "description": "The data to encode in the QR code image"
   }
  ],
  "events": [
  ],
  "methods": [
  ],
  "nestable": false
}

2. Update the component JavaScript code

The JavaScript for new components must be written using ES2015 class syntax.

The JavaScript API has changed in the custom elements v1 specification. Fortunately, the old v0 API methods map nicely to the new v1 methods.

v0 method	v1 method
document.registerElement()	customElements.define()
createdCallback()	constructor()
attachedCallback()	connectedCallback()
detachedCallback()	disconnectedCallback()
attributeChangedCallback()	attributeChangedCallback() (requires observedAttributes)

Here is a working example of the updated my-qrcode component:

myqrcode.js

/** @fileoverview Implementation of the my-qrcode component. */
if (window.customElements && window.customElements.define) {
  class MyQrcode extends HTMLElement {
    constructor() {
      super();
      this.img = null;
    }

    connectedCallback() {
      this.generateImage();
    }

    static get observedAttributes() {
      return ['data'];
    }

    attributeChangedCallback(attributeName) {
      if (!this.img) {
        return;
      }
      switch (attributeName) {
        case 'data':
          this.generateImage();
          break;
      }
    }

    generateImage() {
      const data = this.getAttribute('data');
      if (data) {
        if (!this.img) {
          this.img = document.createElement('img');
          this.img.style.height = '100%';
          this.appendChild(this.img);
        }
        this.img.setAttribute('src', QRCode.generatePNG(data));
      } 
    }
  }

  customElements.define('my-qrcode', MyQrcode);
}

Things to note:

• The new component must extend HTMLElement.
• super() must be called in the constructor.
• The attributeChangedCallback will not be triggered unless the attribute is listed under observedAttributes.

Learn more about the new Custom Elements v1 specification and authoring custom elements.

3. Transpile the JavaScript code to ES5 (recommended)

The updated QR code component above works in Google Chrome and other browsers which support the ES2015 (ES6) class syntax. Older browsers do not recognise this new JavaScript syntax and require transpilation. For your custom component to work correctly across all browsers, we strongly recommend using a transpiler to convert the JavaScript code in section 2 down to ES5.

Babel is a popular transpiler at babeljs.io which can be run on any operating system. There's also a web app version available online at babeljs.io/repl.

When using the Babel web app, make sure that the es2015 preset is ticked.

Include the transpiled code within your component package in place of your original JavaScript code.

4. Install the updated component

In Google Web Designer, remove the outdated component from the Components panel by using the Delete button, then install the ZIP file of the updated version by using the Add custom component button.