Recommended releases

Download Released

Other releases

Download Released
1.x-1.2.2 (16.94 KB) Apr 25th, 2021 Notes

This module allows you to use the same layout on multiple paths. It adds settings to the Layout configuration page where you can specify additional paths on which the layout may be applied (depending on user access and relative layout priority).

Layout Wildcard adds a new "Alternative paths" setting to each layout configuration, which allows specifying a list of multiple additional paths to be handled by the layout.

In addition it implements "ancestor matching," which allows you to stipulate that a layout could be used on all paths of the form somepath/% even if there are only specific paths like somepath/1 and somepath/2 (but not somepath/%) in the menu router table.

Installation

Usage

This module adds two additional fields to the configuration page for each non-default layout:

Alternative Paths

Add any desired additional paths to the "Alternative paths" setting on each layout's configuration page. This layout will be considered for usage on any page whose system path is either the primary path or one of the alternative paths. Whether the layout is actually used depends on visibility conditions and the relative ordering of the matching layout(s) and any other layouts.

Note that if the layout has any placeholders in the primary path, it will have positional contexts; alternative paths must have the same number of placeholders in the same order within the path (though they don't have to be in the same positions).

Ancestor Matching

Check the "Ancestor matching" checkbox to turn on ancestor matching, in which the layout will be used if its primary path matches any ancestor of the request path. This behavior was always invoked in LW versions prior to 1.x-2.0; now it is optional, per the checkbox.

Versions

Backdrop 1.20, introduced September 15, 2021, incorporates some changes in Layouts, including the creation of a new hook, hook_layout_load_by_router_item_alter(), which (for the first time) provides a way for contrib modules to cleanly alter which layout is used for a given path. A collateral effect of these changes are some improvements in how layouts for node preview pages are handled.

Since altering which layout is used for a given path is very much Layout Wildcard's raison d'etre, this change has big ramifications for the future of LW. It lets us simplify the current code and contemplate adding new capabilities in a straightforward way.

The 1.2.x branch of LW works by essentially fully taking over from Backdrop Core the process of determining which layout gets applied to the currently requested path. This did the trick in the past, and will continue to work even after upgrading Backdrop to version 1.20. However, if you upgrade Backdrop to v. 1.20 but keep LW on version 1.2.2, your site will miss out on the node preview fix in 1.20, and if any other modules make use of the new hook, they will not function properly.

This table summarizes the version compatibility of LW and Backdrop core.

Backdrop 1.19.x Backdrop 1.20+
Layout Wildcard 1.2.2 Works as currently Will still work, but no support for new hook and associated functionality
Layout Wildcard 2.0+ Will not work Recommended!

We encourage upgrading LW to version 2.0 at the same time that you upgrade Backdrop to version 1.20. Once LW 2.0 is released, all future development of Layout Wildcard will take places on the 2.0 branch.

Layout Wildcard 2.0, in addition to supporting the new hook, also improves support for contexts in alternative paths and makes ancestor matching optional.

Documentation

Additional documentation (and some explanation of the various types of "paths" in Backdrop) is located in the Wiki.

Issues

Bugs and feature requests should be reported in the Issue Queue.

See the issue queue for the roadmap of future plans, including support for aliases in addition to normal paths.

Current Maintainers

Credits

License

This project is GPL v2 software.
See the LICENSE.txt file in this directory for complete text.