Components

General Approach

When using Luma, the code below will be parsed by js DOM walker, then it will trigger resource loading via RequireJS, and then the component will be initialized:

<div data-mage-init='{"Vendor_Module/js/component": {}}'></div>

Unlike default Magento frontend, Breeze doesn’t use RequireJS to dynamically inject a components into the page.

Instead, the code above will be parsed on the server-side, then Breeze will inject required scripts to the page’s <head> section. You may think of it like server-side RequireJS.

To make this possible, we register a path to the javascript file for each component using layout update instructions. These registrations are grouped into bundles to decrease network requests count.

Component Registration

Each component must be registered in breeze_default.xml layout update file. Here is an example that register Vendor_Module/js/component component in customer bundle:

<referenceBlock name="breeze.js">
  <arguments>
    <argument name="bundles" xsi:type="array">
      <item name="customer" xsi:type="array">
        <!-- Optional. Declare and set to true to force bundle injection on all pages. -->
        <item name="active" xsi:type="boolean">true</item>

        <item name="items" xsi:type="array">
          <!-- 'Vendor_Module/js/component' - is the name used in data-mage-init or x-magento-init -->
          <item name="Vendor_Module/js/component" xsi:type="array">
            <!-- Path to file with component declaration -->
            <item name="path" xsi:type="string">Vendor_Module/js/breeze/file</item>

            <!-- A flag that tells Breeze if the component should be used -->
            <item name="enabled" xsi:type="helper" helper="Swissup\Breeze\Helper\Config::isEnabled">
              <param name="path">config/path/enabled</param>
            </item>

            <!-- Optional. Helpful if you use multiple names for the same component -->
            <!-- 1. data-mage-init='{"vendorModule": {}}'  -->
            <!-- 2. data-mage-init='{"Vendor_Module/js/component": {}}' -->
            <item name="names" xsi:type="array">
              <item name="fullname" xsi:type="string">Vendor_Module/js/component</item>
              <item name="shortname" xsi:type="string">vendorModule</item>
            </item>
          </item>
        </item>
      </item>
    </argument>
  </arguments>
</referenceBlock>

The following bundles are available:

  • default — use it when your script is added on all (almost all) pages.
  • product — use when your script is added on the product page only.
  • product-bundle — for the scripts related to bundle product types.
  • product-configurable — for the configurable products.
  • customer — for the scripts added on customer/login pages.
  • cms — for scripts used across CMS pages.

Additionally, you can declare your own bundles. Just make sure that its name is unique to prevent collisions with other third-party modules.

Component Declaration

Every Breeze Component is declared using $.widget or $.view function. Widget is used to declare most type of components. View is used to declare component that needs reactivity and need to render KnockoutJS template.

Component names are saved in shared registry, so you can’t use same name for view and widget.

// Dropdown widget example
$.widget('dropdown', {
    // Component alias to search in DOM structure
    component: 'dropdown',

    // Default options
    options: {
        parent: null,
        activeClass: 'active',
        dialog: false,
        menu: '[data-target="dropdown"]'
    },

    // Widget constructor
    create: function () {
        console.log(this.element);
        console.log(this.options);
    }
});


// Wishlist View component
$.view('wishlistView', {
    component: 'Magento_Wishlist/js/view/wishlist',
    wishlist: $.sections.get('wishlist')
});

Component Initialization

Breeze Components are the replacements for Luma Widgets and very basic uiComponents. In most cases Breeze Components initialization is fully compatible with Luma-based initialization format:

<!-- Init component via data-mage-init attribute -->
<div data-mage-init='{"Vendor_Module/js/component": {}}'></div>

<!-- Init component via text/x-magento-init script -->
<div class="class-name"></div>
<script type="text/x-magento-init">
{
    ".class-name": {
        "Vendor_Module/js/component": {
            "options": {}
        }
    }
}
</script>

<!-- Init component via scope and Magento_Ui/js/core/app -->
<div data-bind="scope: 'scopeName'"></div>
<script type="text/x-magento-init">
{
    "*": {
        "Magento_Ui/js/core/app": {
            "components": {
                "scopeName": {
                    "component": "Vendor_Module/js/view/component",
                    "config": {}
                }
            }
        }
    }
}
</script>

<!-- Init component programmatically -->
<script data-breeze>
$(document).on('breeze:load', function () {
    $(el).dropdown(options);
});
</script>

Programmatic Usage

Sometimes you’ll need to create new component instance or call some method of existing component programmatically. Breeze allows you to do this with a single line of javascript code.

Create new component instance or update options of existing one:

$(el).cmpName(options);

Get the component instance:

var instance = $(el).cmpName('instance');

Call the methodName in the component instance:

$(el).cmpName('methodName', param);

Call the methodName statically:

$.fn.cmpName().methodName(param);

Additionally, you can collect all instances of specified component name, or call some method in all instances using $.widget or $.view functions:

// iterate over all instances
$.widget('widgetName').each(fn);

// call for specified method in all instances
$.widget('widgetName').invoke('close');

// destroy all instances
$.widget('widgetName').destroy();