Foundation for Sites6.9.0 changelog
Component List

JavaScript Utilities

Our JavaScript Utility Libraries are easy to use and super helpful.

Installing

See our JavaScript and Installation pages on how to install our files in your project.

Box

js/foundation.util.box.js

One of the useful libraries is Foundation.Box, and it has a couple methods designed to make your life easier. You can pass either jQuery objects or plain JavaScript elements to both.


var dims = Foundation.Box.GetDimensions(element);

Will return an object that contains the dimensions of element. The object return looks like:


{
  height: 54,
  width: 521,
  offset: {
    left: 198,
    top: 1047
  },
  parentDims: {
    height: ... // parentDims and windowDims share the same format as the element dimensions.
  },
  windowDims: {
    height: ...
  }
}

Also included is the ImNotTouchingYou function. It returns a boolean based on whether the passed element is colliding with the edge of the window (default), or a parent element. The remaining two options are booleans for limiting collision detection to only one axis.


var clear = Foundation.Box.ImNotTouchingYou(element [, parent, leftAndRightOnly, topAndBottomOnly]);

Keyboard

js/foundation.util.keyboard.js

Another quite useful library, Foundation.Keyboard has several methods to make keyboard event interaction easier for all. Shout out to Marius Olbertz of Germany who conceived and coded this library.

Ever wanted a handy list of common keycodes and the keys they represent? Use Foundation.Keyboard.keys. This is an object containing key/value pairs of the most frequently used keys in our framework.

Want to manage your own keyboard inputs? No problem! Within your .on('key**') callback, call Foundation.Keyboard.parseKey(event) to get a string of what key was pressed, e.g. 'TAB' or 'ALT_X'. (You can also use this function outside of the Foundation components, in your own JavaScript code!)

What if you want to know if there's focusable elements somewhere on a page? Instead of writing your own function and selector from scratch, just use:

var focusable = Foundation.Keyboard.findFocusable($('#content'));

The Keyboard utility also provides functions to trap the keyboard focus inside a given element. This is quite useful for modals in terms of accessibility. When the focus is trapped, pressing tab while the last focusable element inside the given container is selected will focus the first element and vice versa.

// Trap focus to given element
Foundation.Keyboard.trapFocus($('#content'));

// Release focus from given element
Foundation.Keyboard.releaseFocus($('#content'));

The real gem of this library, however, is the handleKey function. Any plugin that is registered with the utility can call on this method to manage keyboard inputs.

Foundation.Keyboard.register('pluginName', {
  'TAB': 'next'
});
...//in event callback
Foundation.Keyboard.handleKey(event, 'pluginName', {
  next: function(){
    //do stuff
  }
});

There are also the functions handled and unhandled, where you can place any code that shall always be executed after the key event has been handled (or not).

If you want to use your own key bindings, simply call the Foundation.Keyboard.register function. It even works after Foundation has already initialized.

MediaQuery

js/foundation.util.mediaQuery.js

The media query library used by Foundation has two publicly accessible functions and two properties:


Foundation.MediaQuery.get('medium');
// returns the minimum pixel value for the `medium` breakpoint.
Foundation.MediaQuery.atLeast('large');
// returns a boolean if the current screen size is, you guessed it, at least `large`.
Foundation.MediaQuery.queries;
// an array of media queries Foundation uses for breakpoints.
Foundation.MediaQuery.current;
// a string of the current breakpoint size.

Also included is an event emitter for breakpoint changes. You can hook into this event with:


$(window).on('changed.zf.mediaquery', function(event, newSize, oldSize){});

Motion & Move

js/foundation.util.motion.js

Two handy utilities, one little file.

Foundation.Motion is the same JavaScript used by the Motion-UI library, and is included in Foundation 6. See the GitHub page for more details.

Foundation.Move is a simple helper function for utilizing browsers' requestAnimationFrame method for hardware acceleration. Invoke like so:

Foundation.Move(durationInMS, $element, function(){
  //animation logic
});

When the animation is complete, your jQuery element will fire finished.zf.animate.

Timer

js/foundation.util.timer.js


var timer = new Foundation.Timer($element, {duration: ms, infinite: bool}, callback);
// includes: timer.start(), timer.pause(), timer.restart()

Similar to setInterval, except you can pause and resume where you left off.

ImageLoader

js/foundation.util.imageLoader.js

Foundation.onImagesLoaded($images, callback);

This will execute your callback function after all the images in your jQuery collection have loaded.

Touch

js/foundation.util.touch.js

Allows you to add swipe* and pseudo-drag events to elements.

$('selector').addTouch().on('mousemove', handleDrag);
// Binds elements to touch events. Used in the Slider plugin for mobile devices.
$('selector').on('swipeleft', handleLeftSwipe);
// Binds elements to swipe events. Used in the Orbit plugin for mobile devices.

Triggers

js/foundation.util.triggers.js

Provides a number of event listeners and triggers your script can hook into. Most are self-explanatory, and used in many Foundation plugins.

<button data-open="someId">I open something!</button>
<button data-close="someId">I close something!</button>
<button data-toggle="someId">I toggle something!</button>
// Add the data-open/close/toggle="idOfElement" tag to your markup.
// When a click event is triggered on that element, these are the non-bubbling events directed at your element.
// If you don't use an `id` selector, an event will be triggered that bubbles up to window.
$('selector').on('open.zf.trigger', handleOpen);
$('selector').on('close.zf.trigger', handleClose);
$('selector').on('toggle.zf.trigger', handleToggle);

Besides these useful click triggers, there are also other listeners for you to tap into. Need to know when the window has been resized, but only when it's done resizing? How about a debounced scroll event? Add this markup and JavaScript and you're good to go!

<div data-scroll="someId">...</div>
<div data-resize="someId">...</div>
$('#someId').on('scrollme.zf.trigger', handleScroll);
$('#someId').on('resizeme.zf.trigger', handleResize);

Throttle

js/foundation.core.js

Many times when you create a callback, it's advantageous to add a delay in order to prevent it from being triggered multiple times. Foundation includes one type of callback delay: throttle.

Throttle prevents a function from being executed more than once every n milliseconds. Throttling is often used in cases where it's disadvantageous to trigger a callback every time an event is triggered (during a continuous action), but you still want to trigger a reaction while the event is occurring. Examples of this would be reacting to the browser window being resized, or animating an element.

Without Delay

// Button click handler
$('.button').on('click', function(e){
  // Handle Click
});

// Resize function
$(window).on('resize', function(e){
  // Do responsive stuff
});

With Delay

// Throttled resize function
$(window).on('resize', Foundation.util.throttle(function(e){
  // Do responsive stuff
}, 300));

Method Signature

// Arguments:
//    Func (Function): Function to be throttled.
//
//    Delay (Integer): Function execution threshold in milliseconds.
//
// Returns:
//    Lazy_function (Function): Function with throttling applied.

throttle(func, delay) { ... }

Miscellaneous

Foundation includes a couple useful features in the core library that are used in many places, that you can tap into.

Foundation.GetYoDigits([number, namespace]) returns a base-36, pseudo-random string with a hyphenated namespace (if you include one). Both arguments are optional; by default, it will return a string six characters long.

Foundation.getFnName(fn) returns a string representation of a named function. Seems small, but believe us—it's useful.

Foundation.transitionend() is a function that returns the string of the properly vendor-prefixed version of transitionend events. Most browsers don't require a prefix these days, but for those that do, we've got you covered. But IE 9 doesn't support transitions?? Quite right you are! In that case, our plugins that use transitions will simply snap to whatever location or visibility state they were headed to, and this function will fire a transitionend event manually on the element you passed. It still gives the desired results, and allows Motion-UI to work in IE 9.