URLs and Layout Handles in Adobe Commerce

In Adobe Commerce, layout XML files control the content on a given page. It’s often fairly easy to sleuth out which layout filename controls which URL path. The content for the URL path /sales/order/history, for example, is controlled by sales_order_history.xml. Some URL patterns are not so cut and dry, though, and it’s important to know what’s actually happening to map URLs to filenames.

The name of a layout file corresponds with a “layout handle.” The most common handles, as we can discern from our example, are formed from three significant segments. (Although other handles can exist, such as the default handle that is applied to every page.) While the second and third segments in a typical layout handle are derived exactly from the respective segments of the page URL, the first is a little more complicated. It comes from the ID of a route, like in this example:

Route XML files defines routes and how they resolve to controllers. They also dictate how routes are matched to a URL path’s first segment, and how the layout handle is formed. The frontName is used to match the URL, while the id actually forms the first segment of the layout handle. These are almost always identical, but it's possible for them to diverge. In our example above, the URL path /posts/archive/view would be controlled by layout files named blogposts_archive_view.xml.

What about URL paths with fewer or more than three segments? The second and third URL segments are implicitly resolved as index if absent (with /checkout/cart resolving to the handle checkout_cart_index and /checkout resolving to checkout_index_index). As for segments beyond the third, these form key/value pairs that actually get translated to querystring parameters. So the page /sales/order/view/order_id/1 is controlled by layout files named sales_order_view.xml, while the controller will find an order_id querystring parameter with the value 1.

And finally, what do we make of SEO-friendly URL paths that follow no such segmented pattern, such as the path /cool-tshirt.html? These are application-level rewrites that can be found in your url_rewrite table in the database. Under the hood, they are rewritten to paths that follow the typical pattern (catalog/product/view/id/{id} in the case of product pages) before the main routing process begins. Such rewrites are implemented for products, categories, and CMS pages.