jQuery widget coding standard
In the Magento system, all jQuery UI widgets and interactions are built on a simple, reusable base—the jQuery UI Widget Factory.
The factory provides a flexible base for building complex, stateful plug-ins with a consistent API. It is designed not only for plug-ins that are part of jQuery UI, but for general usage by developers who want to create object-oriented components without reinventing common infrastructure.
For more information, see the jQuery Widget API documentation.
This standard is mandatory for Magento core developers and recommended for third-party extension developers. Some parts of Magento code might not comply with the standard, but we are working to gradually improve this.
Use RFC 2119 to interpret the “must,” “must not,” “required,” “shall,” “shall not,” “should,” “should not,” “recommended,” “may,” and “optional” keywords.
- Widget names must consist of one or more non-abbreviated English word and in camelcase format.
- Widget names should be verbose enough to fully describe their purpose and behavior.
Instantiation and resources
$.mage.components()method and must not be included in the
- Use the
- You must use
$.mage.extend()to extend an existing set of widget resources.
You must instantiate widgets using the
data-mage-initattribute. You can use the
.mage()plug-in to instantiate widgets that use callback methods.
- You leverage the benefits of
- You can modify widget initialization parameters.
- You leverage the benefits of
Widgets should comply with the single responsibility principle.
Widgets should not have responsibilities not related to the entity described by the widget.
- Widget properties that modify the widget’s behavior must be located in the widget’s options to make them configurable and reusable.
- Widget communications must be handled by jQuery events
You must use DOM event bubbling to perform one-way communication between a child widget and its parent widget.
Widgets must comply with the Law of Demeter principle. Do not instantiate a widget or call a widget’s methods inside another widget.
Make widgets abstract enough so that they can be used anywhere in Magento.
For example, the
mage.dropdownwidget is applicable in many other scenarios, unlike
Place abstract, share-able widgets under the
<install dir>/pub/lib/<your company>directory so non-Magento applications can access them.
/pub /lib /magento dropdown.js validation.js dialog.js
Place Magento-specific widgets under the
/app /code /Mage /DesignEditor /view /frontend /js vde-block.js vde-container.js
Use an underscore prefix to declare private widget methods.
Properties without an underscore prefix are accessible using the jQuery Widget factory public API.
- Start a widget’s element selection with
Widgets must not interact with DOM elements selected using
This reduces the number of widget conflicts because widgets interact only with their child elements.
- Widget options should have default values.
nullvalue if there is no default value for an option.
- Pass as widget options all DOM selectors used by that widget.
- Use the
_setOptionmethod to process required, immediate state changes.
- Use the public widget API to call widget methods to allow chaining widget methods.
Handle widget initialization if there is a logical action to perform on successive calls to the widget with no arguments.
The widget factory automatically fires the
_init()methods during initialization, in that order and prevents multiple instantiations of the same element.
_create()method is called only once for each widget instance and
_init()is called each time the widget is called without arguments.
When a widget is destroyed, the attached element should be left exactly like it was before attachment.
Common tasks for this include:
- Removing or adding any CSS classes the widget added/removed to the element.
- Detaching any elements the widget added to the DOM.
- Destroying any widgets that the widget applied to other elements.
- Bind event handlers using the
_bind()method to make it easy to find what events the widget reacts on.
Bind events using the
- Delegation is supported using selectors in the event names.
- Maintains proper
thiscontext inside the handlers, so it is not necessary to use the
- Event handlers are automatically namespaced and cleaned up on destruction.
- Delegation is supported using selectors in the event names. For example: