Location rules

Last updated Oct 3, 20267 min read

Location rules decide which screens show a field group. You set them in the group editor under Settings › Location rules.

How rules combine

A rule is parameter + operator + value, for example Post type · is equal to · Page.
Rules inside one Rule group are joined by AND: every rule must match.
Rule groups are joined by OR: the field group shows when any rule group matches.

The editor explains it in one line: All rules in a rule group must match (and); the field group shows when any rule group matches (or). The line Appears on: ... above the tabs summarizes your rules in words.

Button	Does
+ Add rule (in a rule group)	Adds an AND rule to that group.
+ Add rule group (or)	Adds a new OR branch.
Remove rule (the button on a row)	Deletes the rule; an empty rule group disappears.

Operators. Only two exist: is equal to and is not equal to.

No rules, no screen. A group without rules is not shown anywhere (No location rules yet. The field group is not shown anywhere until you add a rule.). Its table also has no mid and mtype columns yet; they are added the first time you save a group that has rules.

Rule parameters

Parameters are grouped in the dropdown as Post, Page, User, Form, Options (and WooCommerce with Pro).

Post group

These apply on post edit screens (posts, pages, custom post types and the Media edit screen).

Parameter	Value	Matches when
Post type	A post type with an admin screen (Posts, Pages, Media, your custom types).	The post being edited has that type.
Post template	Default template or a template of the theme.	The post's page template is that template.
Post status	Published, Draft, Pending, Private, Scheduled.	The saved status of the post. See the note below for new posts.
Post format	Standard, Aside, Gallery, Link, Image, Quote, Status, Video, Audio, Chat.	The post's format (`standard` when none is set).
Post category	A category (term picker).	The post is assigned to exactly that category. A category's parent or children do not count.
Post taxonomy (term)	A taxonomy plus a term.	The post is assigned to that term of that taxonomy.
Post	A single post (picker).	The post id equals the chosen post.

Page group

Parameter	Value	Matches when
Page type	Front page, Posts page, Top level, Child page.	The item is a Page of that kind. Front page and Posts page come from Settings › Reading; Top level is a page without a parent; Child page has a parent. A page is only ever one of these, checked in that order. For other post types the value is empty, so only is not equal to rules can match.
Page template	Default template or a template.	The page template is that template.
Page parent	A page (picker).	The item's direct parent is the chosen page.
Page	A single page (picker).	The item is that page. Only pages ever match.

User group

Parameter	Value	Matches when
User role	A role.	On user screens: the edited user's first role is that role. A user with several roles matches only through the first one.
User form	Your profile, Edit user, Add new user.	The user screen is that form.
Current user	A user (picker).	The person using the screen is that user. Works on every screen.
Current user role	A role.	The first role of the person using the screen. Works on every screen.

Use Current user role to show a group only to administrators, for example. It applies to posts, users, terms, comments, widgets, options pages and orders.

Form group

Parameter	Value	Matches when
Taxonomy	A taxonomy.	The term edit screen of that taxonomy.
Attachment	A MIME type such as `image/jpeg`, or `*` for any.	The Media edit screen of a file with that MIME type. `*` matches any media file, and only media (never other post screens).
Comment	A comment id, or `*` for any.	The Edit Comment screen of that comment (`*` = any comment).
Widget	Text in the form `sidebar\|widget_id\|instance`, for example `sidebar-1\|text-2\|2`.	The widget form for exactly that widget. No wildcard.
Menu	A navigation menu.	A menu item that belongs to that menu.
Menu item	A menu item (picker).	That menu item.

See the Developer API for those functions.

Options group

Parameter	Value	Matches when
Options page	An options page (select).	The group is shown on that options page. If you have no options pages yet the select says `No options pages yet — create one first`. See Options pages.

A group whose every rule group contains an Options page rule stores its values only in the shared options row.

WooCommerce group (Pro)

With Pro and WooCommerce active, two more parameters appear (wc_order, wc_order_status): Order (All orders) and Order status (every WooCommerce status). They put the group on the order edit screen (HPOS and posts storage). See WooCommerce.

Which rule works on which screen

Screen	Parameters that can match
Post, page, custom post type, media	Post type, Post template, Post status, Post format, Post category, Post taxonomy (term), Post, Page type, Page template, Page parent, Page, Attachment, Menu, Menu item, Current user, Current user role
User profile / edit / add user	User role, User form, Current user, Current user role
Term edit	Taxonomy, Current user, Current user role
Edit comment	Comment, Current user, Current user role
Widget form	Widget, Current user, Current user role
Options page	Options page, Current user, Current user role
WooCommerce order (Pro)	Order, Order status, Current user, Current user role

Things that surprise people

Rules are checked when the screen loads. Choosing a category or changing the status in the editor does not show or hide a group live. Save the post and reload to see the effect.
New posts have the status auto-draft. On Add New, Post status is equal to Draft does not match yet. Use Post status is not equal to Published (it matches auto-draft) or combine with Post type.
Not equal on a parameter that does not apply fails. For example Page is not equal to ... or Attachment is not equal to ... on a normal post: the screen has no page or attachment, so the rule cannot match.
Terms are matched as saved. Post category and Post taxonomy (term) read the terms stored for the post.
Invalid rules are refused when you save: Unknown location parameter "x"., "post_id" rule requires a numeric value., Post taxonomy rule requires a valid taxonomy in value_meta., Post taxonomy rule requires a numeric term id., Options page rule requires the slug of an options page., Each location rule group (OR branch) must contain at least one valid rule.
Through the REST API an unknown operator is quietly stored as equal.

Examples

All Pages that are not the front page (one rule group, two rules joined by AND)

Post type is equal to Page
Page type is not equal to Front page

Posts in the category "News" or custom post type "Event"

Rule group 1	Rule group 2
Post category is equal to News	Post type is equal to Event

Only administrators, on user profiles and the shop options page

Rule group 1	Rule group 2
User form is equal to Edit user AND Current user role is equal to Administrator	Options page is equal to Shop settings AND Current user role is equal to Administrator

REST representation

json

"location": [
  [
    { "param": "post_type", "operator": "equal", "value": "post" },
    { "param": "post_taxonomy", "operator": "equal", "value": "12", "value_meta": { "taxonomy": "post_tag" } }
  ],
  [
    { "param": "options_page", "operator": "equal", "value": "shop_settings" }
  ]
]

For developers

Integrations can add parameters with the wpmcf/location/params filter and resolve them on their screen with wpmcf/location/actual_value (WooCommerce orders use it). See Hooks and filters.

Troubleshooting

Problem	Fix
The group does not appear	Check that it is Active, has at least one rule, and that every rule in a rule group can match on that screen (see the table above). Reload the screen after changing terms or status.
The group appears on the wrong post type	Rules are ORed across rule groups: remove the extra rule group, or add Post type to every rule group.
The group appears for a post type but values do not save	The table has no `mid`/`mtype` columns until a group with rules is saved. Save the group once.
A category rule does not match a child category	Post category matches the assigned term only. Add a rule group for each category.
The rule list says `Could not load the location lists (post types, templates, …). Refresh the page to try again.`	The helper REST requests failed (for example a security plugin blocks `wpmcf/v1/location/*`). Reload; check REST access.

Was this page helpful?

Still stuck? Contact support