The problem one layer cannot solve
A RuleCMS widget is a stack of rows. Each row sits below the one above it, and the columns in a row sit beside each other. That is the right model for almost every page: a heading, then a photo, then a button. The content flows, and nothing covers anything else.
Some designs are not a flow. They are a stack. A “SALE” badge belongs on the product photo, not under it. A caption belongs on the hero, not in the next row. A play button belongs on the video. A faint tint or a seasonal frame should decorate what is already there without pushing it down the page.
The web has always had a name for this: z-index, the third axis after left-right and top-bottom. Later paint wins. An element with a higher stack order is drawn on top of the ones behind it, even when they occupy the same rectangle on the page. Designers have used that for decades. What they have not had in a visual CMS is a way to author those extra stacks without dropping into raw HTML, or without flattening the badge into the photo itself so it can never be edited, hidden on phones, or reused.
Overlay layers are RuleCMS's answer. The widget you already know is the base. On top of it you can add one or more extra layouts — each a full page of rows and columns in its own right — that cover the same box and paint in order. Layer 1 sits on the base. Layer 2 sits on Layer 1. Preview and the published page show the whole stack. The editing canvas shows one target at a time, so the thing you are working on is never buried.
Where this is really useful
If the extra content can live in the next row, put it in the next row. Layers earn their keep when the extra content has to occupy the same space as something already there.
| You want | Why a second row will not do | What a layer does |
|---|---|---|
| A sale, new, or featured badge on a product photo | A row under the photo is a caption, not a stamp. Baking the badge into the image means a designer every time the copy changes. | Layer 1 holds a small text or image in the corner. Hide it on phones, or swap the wording, without touching the photo. |
| A caption or credit over a hero | Putting the credit below the hero loses the “on the picture” look the design asked for. | The credit sits on the image. Pointer Events of none lets the hero's own link or button still receive the click. |
| A play, mute, or skip control on a video | A control in the next row is a toolbar, not an overlay. Viewers expect it on the picture. | The control lives on Layer 1, aligned to a corner of the video on the base. |
| A promo or cookie-style strip across a hero that already has a call to action | Another row pushes the hero down. Covering the hero with a normal column steals every click meant for the button underneath. | The strip is a layer. Pointer Events of none on the layer, and auto on the strip's own button, is the usual recipe: decoration passes through, the one control you added still works. |
| A seasonal frame — frost, confetti, a Black Friday banner — on a landing page you do not want to rebuild | Duplicating the whole widget for a two-week campaign doubles the thing you have to keep in sync. | The campaign lives on its own layer. Hide the layer, or delete it, when the season ends. The base is untouched. |
| A device-only treatment — a badge that is fine on desktop and cramped on a phone | Hiding a column on the base also hides the photo it was sitting next to, if you structured it as one piece. | Hide the layer on phones. The base photo stays. Hide Widget in Layer Settings is the control; the canvas keeps the layer visible so you can still edit it. |
How RuleCMS models a layer
The widget (or collection) you have always edited is the base. It invents the size of the box. Every overlay layer is another full layout — rows, columns, components, even nested collections — stretched to that same box and painted on top.
- Layer 1, Layer 2, Layer 3 are just the order in the list. Later layers paint on earlier ones. There are no custom names in this version, and there is no separate z-index field: the list is the stack.
- A layer is always as wide and as tall as the base. Width and height on Layer Settings do not change that. Size the contents of the layer (a small badge, a bottom caption) the way you already size a column.
- The base has to have some height of its own — a photo, a min height, enough content to grow the box. A layer-only widget has nothing to cover.
- Hiding the widget still hides the whole stack, layers included. To hide just the overlay, hide the layer.
Adding, choosing, and deleting layers
Open a widget or a collection in the composer. In the header, just left of the settings gear:
- Click Add Layer. RuleCMS creates an empty layer, selects it, and the canvas switches to that layer so you can start dropping components.
- Once at least one layer exists, Add Layer becomes a dropdown. Choose Base, Layer 1, Layer 2, and so on, or Add Layer at the bottom to append another.
- With a layer selected — not Base — a Delete Layer button appears to the right of the dropdown. It removes that layer from the widget (or collection) completely. Undo in the top bar brings it back.
The address bar follows along: ?layer=2 means Layer 2. Reload, the browser Back button, and a trip into an embedded collection all return you to that layer instead of dropping you on the base. Back to widget (and Back to a parent collection) does the same — it opens the parent on the layer you left, not on Base.
Editing a layer
Once a layer is selected, the composer is the composer you already know. Drop components and collections, move them, copy them, delete them, change row layout, reset, undo, and redo. Every one of those actions writes into the selected layer, not into the base.
The canvas shows only the layer you are on. That is deliberate. If the layers painted on top of the base while you edited, you would be clicking through badges to reach the photo underneath. Switch the picker back to Base to work on the original layout; the layers disappear from the canvas and wait for Preview.
Layer Settings
With a layer selected, the gear still opens the settings drawer — it is now labelled Layer 1 Settings (or Layer 2, and so on). The controls are the same family as Widget Settings, and they apply to that layer's own box.
Two settings do most of the work on a layer:
- Pointer Events — auto (the default) takes the click. none lets the click fall through to the base, which is what a decorative overlay needs. A button you drop on that layer can take clicks back by setting Pointer Events to auto on its own column. The canvas ignores this so you can still select things; open Preview to confirm clicks pass through.
- Hide — hide this layer on phones, tablets, or desktops. The layer stays on the canvas so you can keep editing it.
Background colour, opacity, and typography on the layer are useful for a tint or a default type style. Width and height on the layer itself do not change the cover — the layer is already 100% of the base.
Seeing the stack
- On the canvas you see the selected target only: Base, or Layer 1, or Layer 2. Layers never paint on top of the thing you are editing.
- Preview shows the composed stack — base, then every layer, in order. This is also what a visitor sees on the published page.
- Publish is unchanged. Publish the widget (or collection) the way you always have; the layers travel with it. See Publishing.
Good to know
- Start from a base that already has size. Drop the photo or the hero first, then add the layer. An empty base gives the layer nothing to cover.
- Prefer Pointer Events over Hide when the overlay should stay visible. Hide removes the layer from view; none keeps it visible and lets clicks through.
- Deleting a middle layer renumbers the ones above it. Delete Layer 1 and the old Layer 2 becomes Layer 1. Paint order is whatever is left in the list.
- Undo restores a deleted layer. There is no confirm dialog, because Undo is the safety net — the same as deleting a column.
- Every setting still has its own page. The information icon in Layer Settings opens the same Attribute Reference as Widget Settings, including Pointer Events.