Options Page

Intro

Sometimes when using WordPress, you need to add some additional global website settings. In those cases you need to create a new settings page, where your users adjut their preferences.

The Customizer is a new feature of WordPress, which allows users to change their options with a live preview. If you want to add options there, please read about the Customizer location.

The Options Page in Ultimate Fields creates a new settings page and allows you to put it anywhere in the administration menu. The name "Options Page", rather than "Settings Page" comes from the fact that WordPress stores those settings as "options", which are accessible through the Options API.

Usage

The "Options Page" location allows you to associate a container with an options page. You can either associate the container with an existing options page (created with Ultimate Fields) or create a new one.

Usage through the interface

To add fields to an options page with the the Administration Interface, please follow these steps:

1. If you are not on the "Add Container" screen already, locate the "Ultimate Fields" section in the administration area and click the "Add New" button on the top (next to the "Containers" title).
2. Locate the "Locations" box.
3. Click "Options Page" from the bottom row.
4. Adjust all other needed options. All of them are described further down this page.

This will create a new options page, which has the same name as the container. By default the page will appear in the end of the administration menu with a generic icon.

Usage through PHP

The options page location in Ultimate Fields is handled by the Ultimate_Fields\Location\Options class. In order to use it, you can either create the new location object manually or let the container do it for you.

The constructor of the class looks like this:

public function __construct( $page = null, $args = array() )

• $page is optional, but recommended. You can either pass an Options_Page object or the slug of an existing options page.
• $args is an array, which allows you to set arguments without having to explicitly call the particular setter. For example, you can pass 'type' => 'apearance' instead of calling ->set_type( 'appearance' )

As you can see, should create a new Options_Page, which you are adding the container to. It is described later in this article. For now we will just use a variable called $page.

Manual creation

Create a new location by using the new keyword and assign it to the container through the add_location() method.

use Ultimate_Fields\Container;
use Ultimate_Fields\Location;

$container = Container::create( 'theme-options' );

// Create a new location and add definitions to it
$location = Location::create( 'options', $page );
$location->set_priority( 'high' );

// Once the location has been fully set up, add it to the container
$container->add_location( $location );

Of course, do not forget to use the correct namespace for the location class!

The uf.init action

Do not forget to only register containers on the uf.init action. Otherwise you will get fatal errors during plugin updates or if the plugin is deactivated and you will not be able to access your website or its backend.

Automatic creation

You can also let the container create the location for you by providing the "options" string as the first parameter for add_location(). The rest of the parameters are the same as for the constructor of the location class.

use Ultimate_Fields\Container;

Container::create( 'options-page' )
	->add_location( 'options', $page );

This way the method allows you to use method chaining and shortens the syntax, in order to make the code more readable.

Creating an options page

Because of the fact that containers in Ultimate Fields cannot create new locations, but only use existing ones, you need to manually create an options page before assigning containers to it.

Those pages are handled by the Ultimate_Fields\Options_Page class, which controls the display and the saving of the page. Just like containers, this class also uses the static create method in order to allow for immediate method chaining. The methods accepts and requires two parameters:

1. id is the ID of the options page. This ID will appear in the URL of editors. For example, a page with ID theme-options will appear as wp-admin/themes.php?page=theme-options
2. title is a string, which is used as the title of the page. It will be also displayed in the menu.

A complete example looks like this:

use Ultimate_Fields\Container;
use Ultimate_Fields\Options_Page;

$page = Options_Page::create( 'theme-options', __( 'Theme Options' ) );

Container::create( 'theme-options' )
	->add_location( 'options', $page )
	->add_fields(array(
		// Your fields here
	));

The Option_Page class allows you to adjust various of the pages' details.

Type

You can either pass the 'type' argument to the $args array or use the set_type() method of the options page to indicate where you want to show it.

The available types are:

• menu (default): Adds the page directly in the menu
• appearance: Adds the page in the "Appearance" sub-menu
• settings: Adds the page in the "Settings" sub-menu
• tools: Adds the page in the "Tools" sub-menu

Please note that the type is ignored if you have selected a parent page.

Example:

// Show the page in the 'Appearance' menu
$page->set_type( 'appearance' );

Parent page

You can add an options page as a sub-menu item of another page, created with Ultimate FIelds, or to a post type.

This is done through the 'parent' argument in the $args array or through the set_parent() method. The only argument for the method, as well as the value of the argument, can be:

• An existing Options_Page object
• The slug of an existing options page
• A string, containing an existing post type

Examples:

use Ultimate_Fields\Options_Page;

$main_page = Options_Page::create( 'theme-options', 'Theme Options' );
$sub_page = Options_Page::create( 'fonts', 'Fonts' );

// Use a variable
$sub_page->set_parent( $main_page );

// Use a slug
$sub_page->set_parent( 'theme-options' );

// Show in the "Pages" menu
$sub_page->set_parent( 'edit.php?post_type=page' );

Icon

When you are adding a page directly to the menu as a top-level page, you can use a custom icon for the page.

WordPress works with the Dashicons icon set. You can go to the developer documentation of WordPress, choose an icon and use it for the options page.

This done either through the 'icon' argument in the $args array of through the set_icon() method:

$page->set_icon( 'dashicons-calendar' );

Menu Position

The pages, which appear directly int he WordPress administration menu can have various positions. By default, all pages, created with Ultimate Fields will appear near the bottom of the menu. You can however, customize this by setting a new position.

The default positions are defined in The Codex. Please check them, but use different numbers when adding pages, as using the same number as a built-in item will overwrite it.

If you want a page to appear between "Pages" and "Comments", you need to select a number between 20 and 25, let's say 23.

Use that number as the 'position' argument in the $args array or directly pass it to the set_position() method:

$page->set_position( 23 );

Capability

When adding a new page to the WordPress backend, a capability must be specified. By default, the page uses the manage_options capability, which means that it is only accessible to administrators.

If you want to modify the required capability, you can use the set_capability() method or the capability argument:

// Grant editors the capability to manage the page
$page->set_capability( 'publish_posts' );

Data Retrival

To retrieve the values of fields, associated with an options page, you should use option as the $type parameter of all *_value functions:

<?php if( 'plain_text' == get_value( 'logo_type', 'option' ) ) {
	the_value( 'logo_text', 'option' );
} else {
	the_value( 'logo_image', 'option' );
} ?>

Adding to the customizer

The Options Page location is supported in the customizer.

Please read the Adding fields to the Customizer article to learn how to add options pages to the customizer and use their values.

Usage with the REST API

In the UI

you need to go the "REST API" tab and select which fields you want to include. You can also select if those fields are editable or not.

In PHP

Please read the REST API section section of the Container Settings article, as the REST functionality is directly controlled in containers.