Events, JS modules and #mrx-config keys
The DOM events, server events, JS modules and #mrx-config keys that are contract.
Everything on this page is in the API surface (event, js and config lines of surface.json), so it is versioned like the PHP API: a name or a detail key is never renamed or removed before the next major (Versioning). npm run docs:check fails when the surface has an event, module, export or key this page doesn't name. The ui-kit describes the modules in full (Design system, section 5); this page is the contract.
DOM events
Each event carries its data in event.detail. An event fired on an element bubbles, so you can listen on that element or on document.
| Event | Detail keys | Fired on | When |
|---|---|---|---|
mrx:ready | none | document | The shell has installed popovers, formatting, the mode switch and, in simple mode, the palette and shortcuts. html[data-mrx-ready="true"] is set at the same moment |
mrx:form-saved | formCode, entityId, response | the editor's form | A Light editor saved. formCode is one of the seven form codes, response the editor's JSON with success, message, entity_id and ext (Fields on a Light editor) |
mrx:product-saved | success, message, product, entity_id, ext | the product form | The product editor saved. Kept next to mrx:form-saved for product-only listeners |
mrx:badges | items | document | The nav counters were refreshed in the background. items maps a nav item key to {count, display, tone, label} (A nav item with a counter) |
mrx:customer-message-sent | options, response | document | The contact-customer modal sent an email, so a timeline can refresh |
mrx:languagebeforechange | storeId, previousStoreId, option, switcher | the switcher | An editor's language switcher is about to change the store view. Cancel it with preventDefault() |
mrx:languagechange | storeId, previousStoreId, option, switcher | the switcher | The editor now shows another store view |
mrx:channelschange | ids, level, card | the Channels card | The channels of a product, discount, page or block changed |
mrx:tabchange | tab, panel | the tab list | A tab of a Light tab set opened |
mrx:themechange | source, state | document | The admin theme or scheme changed |
mrx:themepreference | state | document | The admin saved a theme preference |
The editors dispatch mrx:form-saved from the form hooks module:
ctx.form.dispatchEvent(new CustomEvent('mrx:form-saved', {bubbles: true, detail: {formCode: formCode, entityId: ctx.entityId, response: response}}));Server events
| Event | Payload | Dispatched by | When |
|---|---|---|---|
mrx_return_resolved_after | return, an array with entity_id, increment_id and order_id | Mrx_Returns | A return is closed after a refund or a check. It runs inside try/catch, so an observer that fails never undoes the return's new status |
public const EVENT_RESOLVED = 'mrx_return_resolved_after';An observer of an mrx_* event uses Light, so its module declares a Light API range (Versioning).
Light also observes Magento's email_order_set_template_vars_before, email_invoice_set_template_vars_before, email_shipment_set_template_vars_before and email_creditmemo_set_template_vars_before, in the global area. Mrx_Documents adds the mrx_* variables its bodies read: mrx_order_url and mrx_created_at on every sales mail, mrx_invoice_date with an invoice, and mrx_has_tracking, mrx_track_url, mrx_track_number and mrx_carrier with a shipment. It only adds keys, so your own observer of these events still runs and its variables still reach the body (Your module's email and document). Mrx_Documents dispatches no events of its own.
<event name="email_order_set_template_vars_before">
<observer name="mrx_documents_sales_email_variables" instance="Mrx\Documents\Observer\AddSalesEmailVariables"/>
</event>JS modules
Each module is a RequireJS AMD module. Only the exports listed here are contract.
| Module | Exports | Use it for |
|---|---|---|
Mrx_Light/js/api | request, get, post, ApiError | JSON calls to your controllers, with the form key, error toasts and the session timeout handled |
Mrx_Light/js/config | get, url, all | The #mrx-config values below |
Mrx_Light/js/toast | show, error | Short confirmations and errors |
Mrx_Light/js/modal | open, confirm, isOpen | Dialogs, and confirmations before a destructive action |
Mrx_Light/js/save-bar | attach, get | The "Unsaved changes" bar on your own forms |
Mrx_Light/js/format | money, number, date, dateShort, dateTime, time, relative, parse, hydrate | Money, numbers and dates in the admin's locale and the store's time zone |
Mrx_Light/js/form-hooks | register, validate, extend, saved | Validation and extra payload for your fields on a Light editor (Fields on a Light editor) |
Mrx_Light/js/loader | during, button, skeleton, spinner | A skeleton shaped like what is coming while a region waits for a request, and the spinner on a busy button (Design system, Loading states) |
A palette action's command works the other way round: it names a module of your own that returns an object with run(), and the palette calls run() after it closes (The command palette).
#mrx-config keys
config.get('<key>') reads them.
| Key | Holds |
|---|---|
apiVersion | ExtensionApi::VERSION, the Light API version of this shop |
mode | simple or advanced |
stockView | Whether a stock screen is open through the advanced view in simple mode |
locale | The admin locale, for example nl-NL |
currency | The base currency of the default store |
timezone | The store time zone |
storeName | The store name |
sender | {name, email}, the default sender |
user | {username, name, email} of the signed-in admin |
canContact | Whether the admin may email customers |
urls | The shell's endpoints, among them cacheRefresh (light/cache/refresh, empty when the admin lacks Magento_Backend::cache) |
nav | The nav items the admin may open, {key: {label, url}} |
shortcuts | The keyboard shortcuts |
channels | The channels and their languages |
icons | The registered icons |
Not in the contract
These work, but a minor release may change them. Don't build on them.
- Internal events:
mrx:valuechange(the save bar fires it on each field after a discard; a custom widget in your own form may listen for it to redraw, but that is tier 2),mrx:table:bulk,mrx:table:channel,mrx:table:loaded,mrx:settings-saved,mrx:settings-discard,mrx:pagechangeandmrx:order:updated. - The other modules of ui-kit section 5:
popover,tabs,rich-text,index-table,search-preview,command-palette,shortcuts,icons,dom,contact-customerand the channels modules. Use them on your own pages as the ui-kit shows; they are tier 2.
Last updated on
API reference
Every @api type with its members, generated by the doctor.
Packages and compatibility
Every Light package, which ones install on their own and which come as a set, what a shop may leave off, the bridges to other modules with their version ranges, and the platforms each release is checked on.