Magellan

JavaScript

Magellan allows you to create navigation that tracks the active section of a page your user is in. Pair it with our Sticky plugin to create a fixed navigation element.

Setup

You can use Magellan with any navigation element, like our Menu or your own custom component. Just add the attribute data-magellan to the container, and links to specific sections of your page. Each section needs a unique ID.

Watch this part in video

<!-- Add a Menu -->
<ul class="menu expanded" data-magellan>
  <li><a href="#first">First Arrival</a></li>
  <li><a href="#second">Second Arrival</a></li>
  <li><a href="#third">Third Arrival</a></li>
</ul>

<!-- Add content where magellan will be linked -->
<div class="sections">
  <section id="first" data-magellan-target="first">First Section</section>
  <section id="second" data-magellan-target="second">Second Section</section>
  <section id="third" data-magellan-target="third">Third Section</section>
</div>

You can use Magellan with our Sticky plugin to create a persistent navigation header or sidebar.

<!-- Add a Sticky Menu -->
<div data-sticky-container>
  <div class="top-bar" data-sticky data-margin-top="0" id="example-menu">
    <div class="top-bar-left">
      <ul class="menu">
        <li class="menu-text">Site Title</li>
      </ul>
    </div>
    <div class="top-bar-right">
      <ul class="menu" data-magellan>
        <li><a href="#first">One</a></li>
        <li><a href="#second">Two</a></li>
        <li><a href="#third">Three</a></li>
      </ul>
    </div>
  </div>
</div>

<!-- Add content where magellan will be linked -->
<div class="sections">
  <section id="first" data-magellan-target="first">First Section</section>
  <section id="second" data-magellan-target="second">Second Section</section>
  <section id="third" data-magellan-target="third">Third Section</section>
</div>

This below example is a simplified version of the table of contents on the right side of this page.

<div class="cell large-3">
  <nav class="sticky-container" data-sticky-container>
    <div class="sticky" data-sticky data-anchor="exampleId" data-sticky-on="large">
      <ul class="vertical menu" data-magellan>
        <li><a href="#first">First Arrival</a></li>
        <li><a href="#second">Second Arrival</a></li>
        <li><a href="#third">Third Arrival</a></li>
      </ul>
    </div>
  </nav>
</div>

Browser History

When the data-deep-link option is set to true, the active section of Magellan is recorded by adding a hash with the active Magellan section ID to the browser URL. By default, Magellan replaces the browser history (using history.replaceState()).

Modify this behavior by using the attribute data-update-history="true" to append to the browser history (using history.pushState()). In the latter case, the browser's back button will track each section Magellan has gone through (in most case, this is not recommended).

JavaScript Reference

Initializing

The following files must be included in your JavaScript to use this plugin:

foundation.core.js
foundation.magellan.js
- With utility library foundation.smoothScroll.js
- With utility library foundation.util.triggers.js

Foundation.Magellan

Creates a new instance of Magellan.

var elem = new Foundation.Magellan(element, options);

Fires these events: Magellan#event:init

Name	Type	Description
`element`	Object	jQuery object to add the trigger to.
`options`	Object	Overrides to the default plugin settings.

Plugin Options

Use these options to customize an instance of Magellan. Plugin options can be set as individual data attributes, one combined data-options attribute, or as an object passed to the plugin's constructor. Learn more about how JavaScript plugins are initialized.

Name	Type	Default	Description
`data-animation-duration`	`number`	`500`	Amount of time, in ms, the animated scrolling should take between locations.
`data-animation-easing`	`string`	`linear`	Animation style to use when scrolling between locations. Can be `'swing'` or `'linear'`.
`data-threshold`	`number`	`50`	Number of pixels to use as a marker for location changes.
`data-active-class`	`string`	`is-active`	Class applied to the active locations link on the magellan container.
`data-deep-linking`	`boolean`	`false`	Allows the script to manipulate the url of the current page, and if supported, alter the history.
`data-update-history`	`boolean`	`false`	Update the browser history with the active link, if deep linking is enabled.
`data-offset`	`number`	`0`	Number of pixels to offset the scroll of the page on item click if using a sticky nav bar.

Events

These events will fire from any element with a Magellan plugin attached.

Name	Description
`update.zf.magellan`	Fires when magellan is finished updating to the new active element.

Methods

calcPoints

$('#element').foundation('calcPoints');

Calculates an array of pixel values that are the demarcation lines between locations on the page. Can be invoked if new elements are added or the size of a location changes.

scrollToLoc

$('#element').foundation('scrollToLoc', loc);

Function to scroll to a given location on the page.

Name	Type	Description
`loc`	String	a properly formatted jQuery id selector. Example: '#foo'

reflow

$('#element').foundation('reflow');

Calls necessary functions to update Magellan upon DOM change

_destroy

$('#element').foundation('_destroy');

Destroys an instance of Magellan and resets the url of the window.