Get started

Core

The core of Highway called Highway.Core works as a bridge to relate pages to renderers and transitions.
It has to be called once to enable Highway and it takes an <Object> of options.

// File: main.js
// Import Highway
import Highway from '@dogstudio/highway';

// Call Highway.Core once.
// Store it in a variable to use events
const H = new Highway.Core({[...]});

HTML Structure

Highway requires a data-router-wrapper and a data-router-view element.
The data-router-view has to be the only child element of the data-router-wrapper.

Highway will look inside the data-router-wrapper for a data-router-view to update the content.
Everything outside the data-router-wrapper will stay the same on navigation.

Finally the data-router-view can be labelled to relate the page to a renderer or to a transition.

<!-- File: index.html -->
<!-- [...] -->
<body>
  <!-- [...] -->
  <main data-router-wrapper>
    <article data-router-view="name">
      <!-- [...] -->
    </article>
  </main>
  <!-- [...] -->
</body>

The renderers work like capsules where all the Javascript related to a single page is put. Each page can have its custom renderer which will extend the built-in and default Highway.Renderer. A page that doesn't need specific Javascript doesn't need a renderer as well so the built-in Highway.Renderer will be used instead.

The Javascript inside a renderer will be run everytime the page it's related to is either displayed or hidden on navigation. A number of hooks/methods are available to structure the renderer and call specific pieces of Javascript at key moments on navigation.

onEnter: This method is run when the data-router-view is added to the DOM Tree.
onLeave: This method is run when the transition to hide the data-router-view runs.
onEnterCompleted: This method is run when the transition to display the data-router-view is done.
onLeaveCompleted: This method is run when the data-router-view is removed from the DOM Tree.

Finally, built-in variables are available through the extension of the Highway.Renderer:

this.wrap: The data-router-wrapper of the page the renderer is related to.
this.properties: A set of properties related to the renderer (page, view, slug, transition,...).

// File: custom-renderer.js
// Import Highway
import Highway from '@dogstudio/highway';

class CustomRenderer extends Highway.Renderer {
  // Hooks/methods
  onEnter() { [...] }
  onLeave() { [...] }
  onEnterCompleted() { [...] }
  onLeaveCompleted() { [...] }
}

// Don`t forget to export your renderer
export default CustomRenderer;

The renderer can be related to a page in the Highway.Core options with the label of the data-router-view that lives inside the said page. A renderer that is not related to a page in the Highway.Core options will be ignored by Highway.

// File: main.js
// Import Highway
import Highway from '@dogstudio/highway';

// Import Renderers
import CustomRenderer from 'path/to/custom-renderer.js';

// Call Highway.Core once.
// Relate renderers to pages with the label of the `data-router-view`.
const H = new Highway.Core({
  renderers: {
    name: CustomRenderer
  }
});

Transitions

The transitions are the managers of the animations to display or hide a page. Each page can have its custom transition which will extend the built-in and default Highway.Transition. A page that doesn't have a transition related to it won't be animated.

The Javascript inside a transition will be run everytime a page it's related to is either displayed or hidden on navigation. A number of hooks/methods are available to manage which animations should be run to display a page and which one should be run to hide a page.

in: This method should contain the animation to display a data-router-view.
out: This method should contain the animation to hide a data-router-view.

These hooks/methods get an Object as a parameter with datas that can be used to animate pages and run everything smoothly:

to: The data-router-view to display.
from: The data-router-view to hide.
done: The required callback method that has to be called once the animation is done.
trigger: The triggered link, popstate or script.

// File: custom-transition.js
// Import Highway
import Highway from '@dogstudio/highway';

class CustomTransition extends Highway.Transition {
  // Built-in methods
  in({ from, to, trigger, done }) {
    // [...]
  }

  out({ from, trigger, done }) {
    // [...]
  }
}

// Don`t forget to export your transition
export default CustomTransition;

The transition can be related to a page in the Highway.Core options with the label of the data-router-view that lives inside the said page. A transition that is not related to a page in the Highway.Core options will be ignored by Highway and the page won't be animated on navigation.

// File: main.js
// Import Highway
import Highway from '@dogstudio/highway';

// Import Renderers
import CustomRenderer from 'path/to/custom-renderer.js';

// Import Transitions
import CustomTransition from 'path/to/custom-transition.js';

// Call Highway.Core once.
// Relate transitions to pages with the label of the `data-router-view`.
const H = new Highway.Core({
  renderers: {
    name: CustomRenderer
  },
  transitions: {
    name: CustomTransition
  }
});

Default Transition

Each page might not need a specific transition but instead multiple pages might need a shared transition. The default key can be used in the Highway.Core options to tell Highway to use a default transition for all pages that don't have a transition related to them.

// File: main.js
// Import Highway
import Highway from '@dogstudio/highway';

// Import Renderers
import CustomRenderer from 'path/to/custom-renderer.js';

// Import Transitions
import OtherTransition from 'path/to/other-transition.js';
import CustomTransition from 'path/to/custom-transition.js';

// Call Highway.Core once
// The custom transition will be used for the page labelled by `name`.
// The other transition will be used by default for all pages with no specific transition related to them.
const H = new Highway.Core({
  renderers: {
    name: CustomRenderer
  },
  transitions: {
    name: CustomTransition,
    default: OtherTransition
  }
});

Contextual Transitions

Some links on a page might need a specific transition depending on their context that is different from the transition related to the said page. A contextual transition can be attached to links with the data-transition attribute that takes the name given to the transition in Highway.Core as value.

// File: main.js
// Import Highway
import Highway from '@dogstudio/highway';

// Import Renderers
import CustomRenderer from 'path/to/custom-renderer.js';

// Import Transitions
import CustomTransition from 'path/to/custom-transition.js';
import ContextualTransition from 'path/to/contextual-transition.js';

// Call Highway.Core once
// The custom transition will be used for the page labelled by `name`.
// The contextual transition will be used by all links it's attached to with the `data-transition` attribute.
const H = new Highway.Core({
  renderers: {
    name: CustomRenderer
  },
  transitions: {
    name: CustomTransition,
    contextual: {
      foo: ContextualTransition
    }
  }
});

<!-- File: index.html -->
<!-- [...] -->
<body>
  <!-- [...] -->
  <main data-router-wrapper>
    <article data-router-view="name">
      <!-- This link will call the transition named `foo` in `Highway.Core` -->
      <a href="path/to/page" data-transition="foo"></a>
    </article>
  </main>
  <!-- [...] -->
</body>

API Reference