Changing Light for one shop
Relabel, remove or re-sort what Light or another module declares, for one shop.
A per-client module can change or remove what Light or another module declares: relabel a nav item, drop a setup step, hide a Settings card, change a list's default sort. This is tier 2: it works, but a minor release may change the defaults you changed (Versioning). Every snippet here comes from Acme_LightProof, which proves each change in a browser test, except the one from the Dutch pack in step 2.
Tier 2
A change to another module's item works, but a minor release may change the defaults it builds on. Read "Changed defaults" in the changelog and retest after every minor.
When to use it
- One shop needs Light to read or behave differently, and the change belongs to that shop, not to a module many shops install.
- Change as little as you can: every change is something to retest after an upgrade (Built for Light, rule 2).
Steps
1. Sequence the module that declares the item
DI merges items by key in module load order. Your module must load after the module that declares the item, or your change may lose:
<module name="Mrx_Settings"/>2. Change a core item
Add the same key to the same pool in the same area, with only the keys you change. Never set module on a change: your di.xml isn't loaded while your module is off, and a module key would replace the declaring module's gate. Acme_LightProof relabels the nav item reviews:
<item name="reviews" xsi:type="array">
<item name="label" xsi:type="string" translate="true">Product reviews</item>
</item>A pack does the same to core's page drafts. Content > Pages offers the pool page_templates when a merchant adds a page, and core's about-us item reads its text from a file in Mrx_Content. Mrx_CountryNl keeps the item and points file at its own folder, in the form Module_Name::name (the file is view/adminhtml/page_templates/<locale>/<name>.html of that module):
<item name="about-us" xsi:type="array">
<item name="file" xsi:type="string">Mrx_CountryNl::about-us</item>
</item>The label, icon and order stay core's. The value of file is tier 2 like any changed value, so retest it after a minor release.
3. Remove one
Set the item to null in the declaring pool and area, with the same sequence. Acme_LightProof drops the setup step "Add your first product" and the Tracking card on the Settings index:
<item name="product" xsi:type="null"/>A nested entry is removed the same way. A nav item can also take disabled true, which hides its children too.
4. Change a core list's defaults
A list's defaults are block arguments in layout. referenceBlock on the list block changes them for your handle:
<referenceBlock name="mrx.reviews.table">5. What is contract
| You rely on | Tier | After a minor |
|---|---|---|
Pool codes, item keys, core codes such as the nav key reviews | 1 | Stays until the next major |
| The values of core items you changed, block names, block arguments | 2 | Read "Changed defaults" in Changelog, and retest |
Plugins or preferences on non-@api Light classes | 3 | May break; the doctor reports private_api |
What the admin sees
- Simple mode. Products shows "Product reviews" instead of "Reviews", Home has no "Add your first product" step, Settings has no Tracking card, and the reviews list opens with the new sort. Disable the module and everything is back.
- Advanced mode. Nothing changes.
ACL
A change keeps the declaring item's resource unless you change it too.
Check it
bin/magento mrx:light:doctor --module=<your module>:override_orderwarns when the result depends on load order, so a<sequence>is missing;override_gatewarns when a change setsmodule.tests/playwright/light-proof.spec.tstest 8 checks every change and that disabling the module undoes them.
Pitfalls
- Without the sequence, a
nullthat loads first is replaced by the declaring module's array, and the item comes back. - A change in the wrong area replaces the whole pool argument of that area: the doctor reports
wrong_areaortwo_areas. - A hidden module's changes to core items stay in effect (Versioning).
Last updated on