Custom navigation types wrap a project’s content, allowing for unique headers, footers, social share icons, chapter lists, and more. Like custom blocks and title designs, navigation types are web components built with Polymer, consisting of markup, styles, a Polymer element definition, and some JSON that describes what aspects of the navigation type are configurable by users.

If you haven't built a custom block before, review the custom blocks and title designs getting started guide, which describes the core concepts involved in building a Polymer web component within Atavist.

Navigation types, unlike custom blocks or title designs, are components meant to accept DOM elements as children — namely, the content of your Atavist projects. That means that the principal difference between building a custom navigation type and building a custom block or title design is the markup of your component.

Web components built with Polymer have both a local DOM and a light DOM. The local DOM consists of elements that belong intrinsically to the component. A component that includes an image and a caption, for example, might have markup that looks like this...

<img src="my-image.jpg">
<p>This is my caption.</p>

...and yet the complete component, when placed on the page, might look like this:

<atavist-simple-image></atavist-simple-image>

The image and paragraph tags, which belong to the block's local DOM and are reused every time the block is used, are encapsulated within the component.

Other components, like navigation types, are designed to accommodate child elements. The same custom navigation type, after all, should work across projects, regardless of their content. That means markup that looks (roughly) like this:

<custom-navigation-12345>
    <article>
        <p>When in the course of human events...</p>
    </article>
</custom-navigation-12345>

or...

<custom-navigation-12345>
    <article>
        <p>A spectre is haunting Europe...</p>
    </article>
</custom-navigation-12345>

In these examples, the child elements — the <article> and <p> tags — fall within the component’s light DOM. It's up to the component to determine how elements that appear within the light DOM are treated.

When defining a Polymer element’s markup, a <content> tag can be used to mark an insertion point for any content that falls within the element’s light DOM. An optional select attribute, containing a selector, can specify which elements from the light DOM to include.

If, for example, you expect the light DOM to include an <h1> tag and a <p> tag…

<custom-component-12345>
    <h1>Heading!</h1>
    <p>Paragraph...</p>
</custom-component-12345>

...your component can insert all elements at once…

<div class="all-content-wrapper">
    <content></content>
</div>

...or it can insert the elements separately:

<div class="h1-wrapper">
    <content select="h1"></content>
</div>
<div class="p-wrapper">
    <content select="p"></content>
</div>

For more information, see “Dom Distribution,” from the Polymer docs.

When creating a navigation type, you'll need to account for the four different elements Atavist will insert in your navigation component’s local DOM:

• article — Contains the entirety of the project’s content, including the project title design. Articles can have one of two pagination styles, "Scroll" and "Paginate." You can choose to support one or both.
• .nav-story-title — A <div> containing the project's title, wrapped in a link that, when clicked, will take the user back to the project's title design.
• .nav-chapter-list — An <ol> element that lists the project’s sections. Each item is linked so that, when clicked, it will take the user to the selected section.
• .story-icons — A web component that includes the Atavist logo and any social sharing icons that apply to the current project.

These elements can be included via a <content> tag, as described above. To opt out of including any of these elements, use <content> tags with specific select attributes, so that only those elements you’d like to include are selected. Be sure to include, at minimum, the article element, via either a <content select="article"></content> tag or an all-inclusive <content></content> tag. If you don't, your projects will appear empty.

Atavist projects support two "pagination" types: Scroll and Paginate. Stories that scroll behave like most web pages, consisting of a single long document a user can scroll through from top to bottom. Paginated stories arrange their sections side by side, allowing users to page through stories from left to right. When creating a navigation type, you can choose to support one or both pagination options, using the toggles near the bottom of the page.