Usage

hy-push-state can be used in a variety of ways:

Web Component

The Web Component is the preferred way of using hy-push-state, but requires support in the browser or a polyfill. There are multiple ways of including it on your page:

Bundled ES6 Module

This is the version that is going to have native support across all major browsers the soonest.

<script type="module" href="https://unpkg.com/hy-push-state/dist/webcomponent/module"></script>

<hy-push-state replace-ids="main,aside" prefetch>
  <main id="main"><!-- ... --></main>
  <aside id="aside"><!-- ... --></aside>
</hy-push-state>

HTML Import

Some browsers have decided against implementing HTML Imports, but they are easily polyfilled.

<link rel="import" href="https://unpkg.com/hy-push-state/dist/webcomponent/hy-push-state.html">

<hy-push-state replace-ids="main,aside" prefetch>
  <main id="main"><!-- ... --></main>
  <aside id="aside"><!-- ... --></aside>
</hy-push-state>

Unbundled ES6 Module (experimental)

When loading the component form the unpkg CDN, you can import the source directly by appending the ?module query parameter.

<script type="module" src="https://unpkg.com/hy-push-state/src/webcomponent/module?module"></script>

<hy-push-state replace-ids="main,aside" prefetch>
  <main id="main"><!-- ... --></main>
  <aside id="aside"><!-- ... --></aside>
</hy-push-state>

Note that this approach will result in hundreds of separate HTTP requests (one for each module) and is intended for testing and prototypes only. Importing unbundled ES6 modules is much slower than bundled distributions and will remain so for the foreseeable future.

One advantage of this approach is that shared dependencies will not be included twice when using more than one component from the Hydejack component family. However, setting up webpack is a better solution in these cases:

Bundlers

You can use hy-push-state with a frontend bundler like webpack or rollup. Just install the component with npm or yarn and import the source in your code:

import 'hy-push-state/src/webcomponent/module';

If you want to have control over when the custom element gets defined, you can also import the HTMLElement like so:

import { HyPushStateElement } from 'hy-push-state/src/webcomponent';
// ...
customElements.define('hy-push-state', HyPushStateElement);

Note that all of hy-push-state’s dependencies are valid ES6 modules, so that they can be inlined with webpack’s ModuleConcatenationPlugin.

jQuery

The jQuery version follows jQuery conventions to the extent possible.

The plugin function is all lowercase and without the leading “hy”. Options can be passed via data-* attributes, or alternatively as an object to the plugin function. Methods are called like .pushstate('<name>', <arg1>, <arg2>, ...). Events are of the form <name>.hy.pushstate.

<div class="hy-push-state" data-replace-ids="main,aside">
  <main id="main"><!-- ... --></main>
  <aside id="aside"><!-- ... --></aside>
</div>

<script src="https://unpkg.com/jquery"></script>
<script src="https://unpkg.com/hy-push-state/dist/jquery"></script>
<script>
  $('.hy-push-state').pushstate({
    prefetch: true
  })
</script>

Note that you are responsible for calling the disconnectComponent function on the component when removing it from the DOM.

Vanilla

<div id="push-state-el">
  <main id="main"><!-- ... --></main>
  <aside id="aside"><!-- ... --></aside>
</div>

<script src="https://unpkg.com/hy-push-state/dist/vanilla"></script>
<script>
  var HyPushState = window.hyPushState.HyPushState;
  var pushState = new HyPushState(document.getElementById('push-state-el'), {
    replaceIds: ['main', 'aside'],
    prefetch: true,
  });
</script>

Note that you are responsible for calling the disconnectComponent function on the component when removing it from the DOM.


© 2018 Florian Klampfer

Powered by Hydejack v8.1.0