Options pages

An options page is a settings screen in the WordPress admin menu. Use it for data that belongs to the whole site rather than to one post: a phone number, a footer text, a logo, social media links.

The page itself only defines the screen (title, place in the menu, who may open it). The fields shown on it come from field groups that have the location rule Options page pointing at it. The values are saved once for the whole site.

Options pages are available on every plan.

Where to find it

Open WPM Fields › Options Pages. The list is introduced as "Admin screens for site-wide settings, such as contact details or a footer text. Put field groups on a page with the location rule “Options page”."

Click Add options page to create one.

Create an options page

1. Click Add options page.
2. Enter a Page title, for example "Site Settings". The slug is filled in from the title until you edit it.
3. Choose where it goes under Place in menu (see below).
4. Click Create options page. You see "Options page created."
5. Create a field group and add the location rule Options page is equal to your page. The field group editor lists every options page by its title.

The editor shows a Field groups on this page section listing the groups already attached, with an "Inactive" badge for groups that are switched off. When there are none it says: "None yet. In a field group, add the location rule “Options page is Site Settings”." with a link to Field Groups.

Page section

Slug rules, with the messages you see:

• "The slug must start with a letter and use 2–64 lowercase letters, numbers, hyphens or underscores."
• "This slug is reserved. Choose another one." Refused: wpmcf, options, general, settings, tools, plugins, themes, users, profile, and anything starting with wpmcf-.
• "An options page with this slug already exists."

Menu section

How the menu is built:

• A page under a WordPress menu appears as a sub-item of Settings, Appearance, Tools or Users. Its URL is options-general.php?page={slug} (or the matching file); a top-level or nested page is admin.php?page={slug}.
• A page under another options page becomes a sub-item of it. The parent also gets a first sub-item with its own name so it stays reachable.
• WordPress menus have two levels. A chain such as A › B › C is flattened: C is placed under the topmost page of the chain.
• If a page's parent menu does not exist (for example it came from an import) the page falls back to top level.
• An options page cannot be its own parent: "An options page cannot be its own parent."

Form section

Fill in the values

Open the page from the admin menu (or Open page in the list). Each field group is shown in its own box with the group's title, using the group's style and label settings. Click the save button once to save every group on the page.

• After saving, the page reloads and shows the saved message. Reloading again does not post again.
• If a required field is empty it is still saved, with the warning "Saved, but these required fields are empty: Phone."
• If one field group fails, only that group shows the error ("These field groups could not be saved: …"). The others are saved. Details are in WPM Fields › Settings › Health.
• A group whose database table is not ready shows "This field group cannot store values yet. Open it in Field Groups and save it again."
• With no group attached, the page shows an info notice with a Go to Field Groups link: "No field groups are shown on this page yet. Create a field group and set its location to this options page."

Only groups that are active and whose every location rule matches are shown. For example a rule on Current user role hides the group from other roles.

One set of values per group

Values belong to the field group, not to the page. If you place the same group on two options pages, both screens edit the same values.

Read the values

Use the group key and the field key, not the page slug.

// Raw value, not escaped: escape it yourself.
$phone = wpmcf_get_option_field( 'site_contact', 'phone' );

// Escaped output, wrapped in <span class="wpmcf-field-value">
wpmcf_the_option_field( 'site_contact', 'phone' );

// Check before printing.
if ( wpmcf_has_option_field( 'site_contact', 'tagline' ) ) {
	wpmcf_the_option_field( 'site_contact', 'tagline', array( 'wrap' => false ) );
}

// Fallback when empty or unavailable.
$email = wpmcf_get_option_field( 'site_contact', 'email', array( 'default' => '[email protected]' ) );

For repeaters and groups, $args accepts path and sub_key. See Template functions.

Shortcode

[wpmcf_field group="site_contact" field="phone" context="options"]
[wpmcf_field group="site_contact" field="phone" context="options" wrap="false" default="n/a"]

context="options" is required. Without it the shortcode looks for a post and prints nothing.

The shortcode only prints in content whose author may open an options page that shows the group. A contributor's post that uses the shortcode prints nothing for a group on an options page that needs manage_options or edit_pages. This stops low-privilege authors from publishing site settings through a shortcode. Theme templates and widgets are trusted and always print. The filters wpmcf/options/capabilities and wpmcf/shortcode/can_view adjust this.

Edit, deactivate and delete

• Active off: the menu entry disappears; the list shows no Open page URL. Values are kept and all functions keep reading them.
• Delete: removes the page definition only. "Deleting a page keeps the field values (they belong to the field groups)." The field group's location rule then points at nothing, so edit the group if you want it elsewhere.
• Changing the Capability takes effect on the next page load.

Hooks

See Hooks.

Troubleshooting

My group does not appear on the page. Open the group in Field Groups and check the location rule is Options page is equal to the page, that the group is active, and that no other rule excludes you.

I get 403 or the menu entry is missing. Your user lacks the page's Capability.

The shortcode prints nothing. Add context="options", and check the author of the post may open the page.

The value does not update on the front end. A page cache is serving old HTML. Clear it on wpmcf/options_pages/values_saved.