Skip to content

Custom Layouts

Jump to bottom
Ryan Johnson edited this page Feb 7, 2018 · 5 revisions

NOTE: Building custom layouts should be the exception, not the norm.

  • If you think that HelixUI is missing a useful layout, please reach out to us in the #helix channel on Slack.
  • Please reference the Layouts Component for more information about supported layouts.

TL;DR

If you're not interested in the detailed explanations below, copy and paste this code snippet into your application's index page.

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Head stuff goes here -->

    <link rel="stylesheet" href="node_modules/helix-ui/dist/styles/helix-ui.css" />

    <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
    <!-- polyfills injected here (if needed) -->
  </head>
  <body>
    <!-- Application markup goes here -->

    <!-- intelligently load ES5 Adapter (if needed) -->
    <span id="ce-es5-adapter">
      <script>
        if (!window.customElements) {
          var elAdapter = document.querySelector('#ce-es5-adapter');
          elAdapter.parentElement.removeChild(elAdapter);
        }
      </script>
      <script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
    </span>

    <script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>
    <script src="node_modules/helix-ui/dist/helix-ui.browser.js"></script>

    <!-- FIXME: Update with the correct path to your application behavior -->
    <script src="path/to/your/app.js"></script>
  </body>
</html>

Polyfills

HelixUI requires two polyfills to ensure maximum browser compatibility.

1. polyfill.io

The first polyfill is an online service that uses browser detection to serve the smallest set of polyfills needed to accommodate missing functionality (polyfill.io).

Load the script before HelixUI and any application logic.

<body>
  ...

  <script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>

  <!-- HelixUI custom element definitions go here -->

  <!-- Application logic goes here -->
</body>

2. webcomponentsjs

The second polyfill uses two scripts to add support for web component technologies.

Web Components Polyfill Loader

NOTE: Currently, the loader only supports being loaded in the <head> of an HTML document.

The loader performs feature detection on the current browser to dynamically inject the smallest polyfill needed to patch missing browser functionality. Any polyfill added this way will be inserted at the end of the document

. 
<head>
  ...

  <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
  <!-- polyfills injected here (if needed) -->
</head>

Once the polyfills are loaded, the "WebComponentsReady" event fires on the document object to announce the availability of Web Component functionality.

Custom Elements ES5 Adapter

The Custom Elements v1 spec requires that constructor classes be defined using ES6 class syntax. The ES6 class syntax requirement can be problematic, though. To support legacy browsers such as Internet Explorer that do not support ES6, HelixUI is compiled to ES5 syntax.

The ES5 Adapter corrects the problem by converting ES5 classes to ES6 syntax so that modern browsers can load custom element definitions. Because the adapter is written in a clever mix of ES5 and ES6 syntax, it raises an exception in browsers that do not support ES6 (i.e., Internet Explorer).

To avoid the exception, use the following strategy to wrap the injection of the ES5 adapter in an element that can be dynamically removed if it isn't needed.

<body>
  ...

  <!-- intelligently load ES5 Adapter (if needed) -->
  <span id="ce-es5-adapter">
    <script>
      if (!window.customElements) {
        var elAdapter = document.querySelector('#ce-es5-adapter');
        elAdapter.parentElement.removeChild(elAdapter);
      }
    </script>
    <script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
  </span>

  ...
</body>
Clone this wiki locally