I am a developer familiar with HTML, CSS and JavaScript but not Magento conventions. In particular, I'm having trouble with the layout files.

Some themes have one, some have over a dozen, and some are nested. How are these layout files called? I read somewhere else that they are all defined in a config.xml but I can't find that for each theme.

For example, in one theme I have in app/design/frontend/THEMENAME/default/layout


In other themes I don't even have a local.xml. So my question is, I thought the layout files controlled the placement of blocks, widgets, the content in general. But how does the layouts work when there are multiple of them and they are specific to different programmatic circumstances?

  • @RaphaelatDigitalPianism where is this "configuration" mentioned in that answer? It says each module has a configuration but I can't find it. – Summer Developer Jan 10 '17 at 14:13

Indeed, the layout XML files are specified in config.xml files. Usually, each module has one layout XML file for the shop frontend and one for the admin panel

  1. Module specific layout XML files are defined in app/code/[pool]/[vendor]/[module]/etc/config.xml like this

  2. The modules place their default layout files in app/design/frontend/base/default/layout, but each theme can override them in app/design/frontend/[package]/[theme]/layout

  3. local.xml is a special case. It is not defined explitly, but if a theme contains it, it is always loaded after all module specific files, so that you can override anything in there. It is considered best practice to not override complete files as described above, but make modifications via local.xml

  4. Another special case is etc/theme.xml. More info: Is there a local theme layout XML file other than local.xml?

  • I understand everything except this module business. What is a module, aren't they additions to the core? Where is the config.xml that defines the layout files for the default theme? – Summer Developer Jan 10 '17 at 14:37
  • modules are not only additions to the core (they can be, as part of an extension), but also the core itself consists of modules. the core modules are in app/code/core and there you will find the config.xml files – Fabian Schmengler Jan 10 '17 at 14:40
  • also, because you asked for "layout files for the default theme": the modules define the layout XML file names independent of the theme. Magento then looks for each of them in the theme directory and falls back to those in the default theme if it cannot find them – Fabian Schmengler Jan 10 '17 at 14:43
  • so if i want to create a new theme do I need to essentially create a new module to avoid editing the core? – Summer Developer Jan 10 '17 at 14:48
  • No, although it is generally a good idea for theme specific features. Why would you want to edit the core? You can use local.xml for theme specific layout instructions – Fabian Schmengler Jan 10 '17 at 14:49

Each layout files declared in any config.xml from an active module are loaded and merged into one big xml file.

Here is an example on how the layout file is declared in config.xml


This means that from the catalog module 2 layout files will be loaded. catalog.xml and catalog_msrp.xml.
The files are searched in the current package and theme (declared in config), if it's not there then the file is searched in the default declared theme. If it's not there it will be searched for in the default named folder of that package and if it's not there either it will be searched in base/default folder.

After all the module files are loaded, at the end the file called local.xml of your current theme will be added also.

When the big file is merged and cached, on a page, certain tags will be loaded depending on the page.
For example in the cart page the tag called checkout_cart_index will be loaded, all the blocks declared inside it will be instantiated and information will be displayed on the page.
This is a nice way of extending a page without changing the core code.

  • Sorry, but where is this config file? In the core? How do I edit it safely or see the one that is being applied currently? – Summer Developer Jan 10 '17 at 14:14
  • Every module should have a etc/config.xml file. You should not edit the core. You should create your own module and add your own config.xml file where you declare the layout file. Then create the layout file. Read this for more info: devdocs.magento.com/guides/m1x/magefordev/mage-for-dev-4.html – Marius Jan 10 '17 at 14:17
  • So in the Magento hierarchy a module encompasses a theme? Is this correct? Is a theme appears to not have a config.xml or a module, does that mean it is inheriting? – Summer Developer Jan 10 '17 at 14:22

Not the answer you're looking for? Browse other questions tagged or ask your own question.