JavaScript Utilities

Foundation includes a handful of helpful JavaScript utilities to help you add common functionalities to your apps and plugins.

Using the JavaScript Utilities

There are two ways to use the Foundation utilities: by calling them within the Foundation.utils namespace and by inheriting them into an object.

Foundation.utils

As long as foundation.js has been loaded into the page, you can access any of the Foundation utilities by calling Foundation.utils.{function_name}.

For example, if you type the following into the JavaScript console it will return a 6-digit alphanumeric string.

// Generates a random string of length n
Foundation.utils.random_str(6);

Method Inheritance

If you have any plain ole’ JavaScript object (a POJO), then you can inherit any of the Foundation JavaScript utilities by calling the Foundation.inherit method. To use the inherit method, pass in the object you want to inherit the methods, followed by a space separated string of methods that you want to inherit.

// Simple example
var user = {};
Foundation.inherit(user, 'random_str data_options');

// Advanced Example
Person = function() {
  this.init = function() {
    Foundation.inherit(this, 'random_str data_options');
  }
};

var user = new Person();
user.init();

Selector Engine

While jQuery’s selector engine is quite versatile, it can sometimes be a bit slow. Foundation’s “Big S” selector leverages the native browser API by using querySelectorAll(), making it up to 20% faster.

“Big S” can be used as a drop-in replacement for the jQuery $ selector in most cases.

// A simple selector
$('.class #id');

// A bracket selector
$('label[for="input1"]');

// A scoped selector
$('dd > .content', '#accordion');

// A simple selector
Foundation.utils.S('.class #id');

// A bracket selector
Foundation.utils.S('label[for="input1"]');

// A scoped selector
Foundation.utils.S('dd > .content', '#accordion');

Method Signature

// Arguments:
//    Selector (String): CSS selector describing the element(s) to be
//    returned as a jQuery object.
//
//    Scope (String): CSS selector describing the area to be searched. Default
//    is document.
//
// Returns:
//    Element (jQuery Object): jQuery object containing elements matching the
//    selector within the scope.

S(selector, scope) { ... }

Throttle & Debounce

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 two types of callback delays: throttle and debounce.

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.

Debounce prevents a function from being executed until it stops being invoked for n milliseconds. Debouncing is often used to prevent an action from being performed twice, such as double clicking a submit button, or to delay an event from occurring accidentally, such as an event triggered by hover.

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

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

// Debounced button click handler
$('.button').on('click', Foundation.utils.debounce(function(e){
  // Handle Click
}, 300, true));

// Throttled resize function
$(window).on('resize', Foundation.utils.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) { ... }

// Arguments:
//    Func (Function): Function to be debounced.
//
//    Delay (Integer): Function execution threshold in milliseconds.
//
//    Immediate (Bool): Whether the function should be called at the beginning
//    of the delay instead of the end. Default is false.
//
// Returns:
//    Lazy_function (Function): Function with debouncing applied.

debounce(func, delay, immediate) { ... }

Data Options

The data_options method parses a semicolon delimited set of values in the selected element’s data-options HTML attribute. It’s useful for allowing settings to be passed into a script or plugin from the markup.

<div id="target" data-options="delay:4;color:red;animal:unicorn"></div>

var settings = Foundation.utils.data_options($('#target'));

Method Signature

// Arguments:
//    el (jQuery Object): Element to be parsed.
//    data_attr_name (string): Optional name of the data attribute containing the options string (defaults to 'options').
//
// Returns:
//    Options (Javascript Object): Contents of the element's data-options
//    attribute.

data_options(el, data_attr_name) { ... }

Media Queries

Media queries are the backbone of most responsive CSS techniques, though they can be a bit unwieldy to deal with. To make them easier to deal with, we’ve included two helper methods (register_media and add_custom_rule), as well as polyfilled the native function matchMedia to work with all the browsers Foundation supports.

Register Media is used to add a new media query to Foundation’s list of JavaScript-accessible media queries. These can be found by calling Foundation.media_queries. The method works by appending a meta tag to the head of the document and checking the font-family of the element’s computed styles for the media query string.

Add Custom Rules is a method to add a custom CSS rule as a string to the document. If a media query is passed in the method will apply the style within that media query, otherwise it will be applied globally.

Match Media can be used to check if the browser currently matches the media query passed in as a string. To use the function, call matchMedia() with the media query as an argument, and check the matches property (see example below).

In addition to this, you can also check the default Foundation media queries. The available methods are:

// Small queries
Foundation.utils.is_small_only();
Foundation.utils.is_small_up();

// Medium queries
Foundation.utils.is_medium_only();
Foundation.utils.is_medium_up();

// Large queries
Foundation.utils.is_large_only();
Foundation.utils.is_large_up();

// XLarge queries
Foundation.utils.is_xlarge_only();
Foundation.utils.is_xlarge_up();

// XXLarge queries
Foundation.utils.is_xxlarge_only();
Foundation.utils.is_xxlarge_up();

/
 Note: The media query string in the font-family property has to be surrounded
 by slashes to be recognized by Phantom.js

 Note: Instead of being defined in the CSS, the following style rule could also
 be added to the document using Foundation.utils.add_custom_rule().
*/
meta.my-mq-custom {
  font-family: "/only screen and (min-width: 40em)/";
  width: 40em;
}

// Register custom media query
Foundation.utils.register_media('custom', 'my-mq-custom');

// Check if the media query is activated
if (matchMedia(Foundation.media_queries['custom']).matches){
  ...
};

// Apply a custom CSS rule to the media query
Foundation.utils.add_custom_rule('.js-generated-element { padding-top: ' + element.data('height') + 'px }', 'custom');

Method Signature

// Arguments:
//    Media (String): Key string for the media query to be stored as in
//    Foundation.media_queries
//
//    Class (String): Class name for the generated <meta> tag

register_media(media, class) { ... }

// Arguments:
//    Rule (String): CSS rule to be appended to the document.
//
//    Media (String): Optional media query string for the CSS rule to be
//    nested under.

add_custom_rule(rule, media) { ... }

Image Loaded

While binding to the document ready event is usually good enough for most plugins that manipulate the DOM, sometimes you need ALL the content to be loaded before you start calculating things like element sizes. This is especially important with images, which can take a while to load and significantly affect the layout of the page, depending on their size.

This can be avoided by using the image_loaded method, which lets you pass in a callback to be executed when an image has completely finished loading. Passing in a jQuery selector that matches multiple images will cause the callback to be executed when all of the images are fully loaded.

Example

Foundation.utils.image_loaded($('img.wait-for-me'), function(){
  console.log('Image Loaded! :)');
});

Method Signature

// Arguments:
//    Image (jQuery Object): Image(s) to check if loaded.
//
//    Callback (Function): Foundation to execute when image is fully loaded.

image_loaded(image, callback) { ... }

Random String

The random_str method is a helper for generating random strings of a given length. This method is used by some of the Foundation plugins to ensure a reasonable probability of non-collision for IDs in dynamically generated DOM objects. Note that random_str should not be considered cryptographically secure.

Example

>> Foundation.utils.random_str(6);
"P47PGD"
>> Foundation.utils.random_str(6);
"JvuXFc"
>> Foundation.utils.random_str(6);
"XOxB7j"

Method Signature

// Arguments:
//    Length (Integer): Length of string to be generated. Defaults to random
//    integer.
//
// Returns:
//    Rand (String): Pseudo-random, alphanumeric string.

random_str(length) { ... }