Contents

Widget Selection Rulesets

A widget is one piece of content. A ruleset is the decision about which widget this visitor should see. You write that decision in the dashboard — locale, plan, campaign, time of day — and RuleCMS evaluates it for you.

What you can do with a ruleset

You already know how to build and publish a widget. The question a ruleset answers is the next one: which of those widgets should this visitor see?

Picture a homepage hero. You have four published widgets for the same slot — a default hero, a German hero, a Pro-plan hero, and a spring-sale takeover. Without a ruleset, your app has to pick one published key and live with it. With a ruleset, you send the visitor's locale, plan, and campaign, and RuleCMS returns the widget that matches.

That same pattern covers a lot of everyday work:

  • Locale. Show de-DE content when the request says German, and keep everyone else on the default.
  • Plan or role. A logged-in Pro customer sees an upgrade-already-done banner. A free customer sees the upgrade CTA.
  • Campaign. A query string or cookie named spring-sale swaps the hero for the sale creative.
  • Time. A weekend promo starts and ends on timestamps you type into a rule. You do not have to remember to publish a revert on Monday.

The decision lives next to the widgets it chooses, with the same draft / publish / history habits you already use. Your app stays a client: it sends parameters and renders whatever comes back.

How a ruleset thinks

A ruleset is an ordered list of rules plus a default widget. Each rule looks at the parameters you declared — locale, user.plan, campaign, and so on — and, if every condition on that rule is true, it picks a widget.

Evaluation is first match wins. Rules run from top to bottom. The first enabled rule whose conditions all pass is the answer. Later rules are not asked. If nothing matches, the default widget is used.

That order is the whole game. Put the narrow, expensive cases at the top (the sale, the one locale, the VIP plan) and the broader cases underneath. A German Pro visitor on the spring sale hits the sale rule first if you listed it first — which is usually what you want.

Rules point at widget keys (widget-…), not published keys. A published key is tied to one environment. A widget key is the same name in Development, Staging, and Production, so the same ruleset can promote with those widgets as you publish them in each environment.

Build your first ruleset

You do this on an environment page — the same place you open Widgets and Collections. You need a Widget Selection Access group (View, Manage, or Admin) for that environment, or a RuleCMS admin account. Manage is enough to create and edit. Publishing reuses the same Staging / Production publish permission you already use for widgets.

  1. Open the organization → team → project → environment you want to work in.
  2. Find the orange Widget Selection Rulesets card, after Collections. Click New Ruleset.
  3. Give it a name a teammate would recognize — “Homepage hero” — and an optional description of the slot it owns. Submit. You land in the editor.
  4. In Parameters, add the fields your app will send. Start small. For the hero story: locale (string, case-insensitive), user.plan (string), and campaign (string).
  5. In Rules, add the first rule. Label it “Spring sale”. Condition: campaign equals spring-sale. Outcome: your sale hero widget.
  6. Add the next rules underneath — German locale, then Pro plan — each pointing at its own widget. Use Up / Down to keep the sale on top.
  7. In Default, pick the everyday hero. A ruleset cannot publish without a default. That is the safety net for everyone who matches nothing.
  8. Click Dry run. Paste a sample such as { "locale": "de-DE", "user": { "plan": "pro" }, "campaign": "spring-sale" }. The drawer tells you which rule won and which widget key was selected. Change the campaign, run it again, and watch the winner move. Save when the traces look right.
  9. On a Development environment you can stop there and resolve from your app against the live draft. On Staging or Production, publish a snapshot the way you publish a widget.

The list page for that environment shows every ruleset: name, key, how many rules are enabled, whether the draft is valid, and whether a published snapshot exists. Open one to keep editing.

What to read next

This page is the story and the first walkthrough. The levers — every operator, every publish action, the Development request — live on the pages below.

  • Rules and operators — Parameter types, reserved names, every operator, first-match order, enable / disable, and what the editor will warn about versus what publish will refuse.
  • Publish, promote, and history — Snapshots, promote versus copy, unpublish, republish a past version, and the guard that stops you deleting a widget a live ruleset still points at.
  • Resolve from your app — RuleCMSWidget with rulesetPublishedKey, or the same POST yourself — Development evaluates the live draft; Staging and Production evaluate the published snapshot on widget-cache.

How this fits next to widgets

A ruleset does not replace a widget. It chooses one. Build the variants in the composer, publish each of them to the environment you care about, then point rules at those keys. If a widget is not published in that environment, the editor warns you and publish will not go through until you fix it.

Development is the place to try this. Staging is the place to publish a snapshot your QA site can trust. Production is the same snapshot idea, with the production publish permission. The Development resolve path reads the live draft — no publish step — so you can iterate the way Development integration already works for a single widget.