Skip to Content

Globals

About

Since Breeze doesn’t use modern JS techniques to load js dependencies, you will work with global js variables. For the sake of simplicity, most of globals declared under $ scope:

Variable Description
_ Underscore library
$() Cash library
$.storage Local storage manager
$.cookies Cookie Manager
$.sections Section/Customer Data
$.request, $.ajax Ajax requests tool
$.async() DOM watcher tool
$.translation Translation manager
$.__() Translate function
$.widget() Widget constructor
$.view() View constructor
$.mixin() Mixin

Underscore

Underscore is a JavaScript library that provides useful functional programming helpers:

// find first even number
var value = _.find([1, 2, 3, 4, 5, 6], function(num) {
    return num % 2 == 0;
});

// render template
var string = _.template('hello: <%= name %>')({name: 'moe'});

// create throttled function
var throttled = _.throttle(updatePosition, 100);

Cash

Cash is a super small jQuery alternative which provides:

  • DOM query selector
  • DOM manipulation
  • Collection methods

Usage example:

$('button.continue')
    .attr('id', 'next')
    .html('Next Step...')
    .on('click', function (event) {
        //
    });

Local Storage

$.storage — is a Breeze wrapper around window.localStorage that adds namespaces support and a few additional methods.

Usage examples:

// Simple storage
$.storage.set(key, value);
$.storage.get(key);
$.storage.remove(key|keys);

// Namespaced storage
var storage = $.storage.ns('vendor-module');
storage.set(key, value);
storage.get(key);
storage.keys();
storage.remove(key|keys);
storage.removeAll();

Cookies

$.cookies — is a wrapper around JS Cookie library. Our wrapper adds ability to work with JSON data in cookies.

Usage examples:

$.cookies.set(name, value);
$.cookies.get(name);
$.cookies.setJson(name, object);
$.cookies.getJson(name);
$.cookies.remove(name);

Customer Data

$.customerData or $.sections — is an object to work with Magento’s dynamic sections (Wishlist, Shopping Cart, Messages, etc).

Usage examples:

$.sections.get(name);
$.sections.set(name, data);
$.sections.reload(names, forceNewSectionTimestamp);
$.sections.invalidate(names);
$.sections.getAffectedSections(url);

Ajax requests

$.request — is tool to work with ajax requests.

Usage examples:

// GET request
var promise = $.request.get({
    url: 'url',
    type: 'html',
    success: callback,
    complete: callback,
    error: callback
});

// POST request
var promise = $.request.post({
    url: 'url',
    data: data,
    success: callback,
    complete: callback,
    error: callback
});

// jQuery-friendly API
$.[ajax|get|post]({
    //
});

Async

$.async — is a handy function to watch for selector appearance in DOM structure. It uses MutationObserver under the hood.

Usage example:

$.async('.selector', function (node) {
    //
});

Translate

$.translation — is an object to work with js translations. There is a shorthand to the $.translation.translate method available: $.__.

Usage examples:

// get translated string
var translated = $.translation.translate('Shopping Cart');
// or
var translated = $.__('Shopping Cart');

// Dynamically register translation for the 'key' phrase
$.translation.add('key', 'value');
// or
$.translation.add({
    'key': 'value'
});

Widgets and Views

  • $.widget — is the function that registers Breeze Widget.
  • $.view — is the function that registers special Widget that has an additional ability to render reactive view (KnockoutJS is used under the hood).
// Declare a widget that will be automatically created
// for each DOM node with data-mage-init='{"dropdown":{}}'
$.widget('dropdown', {
    component: 'dropdown',
    create: function () {},
    destroy: function () {}
});

// Declare a view that will be automatically created
// for each DOM node with
// data-mage-init='{"Vendor_Module/js/view/component":{}}'
$.view('cmpName', {
    component: 'Vendor_Module/js/view/component',
    create: function () {},
    destroy: function () {}
});

You can read more information about Widgets and Views at the separate pages:

Mixin

$.mixin — is the utility to extend or override standard component functionality. You can use it to extend any Widget or View methods:

$.mixin('dropdown', {
    destroy: function (original) {
        return original();
    }
});

You can also use mixin to completely disable any component:

$.mixin('cmpName', {
    component: false
});