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="large-3 columns" data-sticky-container>
  <nav class="columns 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>
  </nav>
</div>

JavaScript Reference

Initializing

The file foundation.magellan.js must be included in your JavaScript to use this plugin, along with foundation.core.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`	`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-bar-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.