This tutorial for intermediate to advanced users provides the steps to register a settings page in WordPress + Oxygen site using Meta Box, attach a custom fields group and display the field values conditionally.

FYI: Meta Box is currently running a LTD (lifetime deal) sale at Appsumo. The complete package for unlimited sites for lifetime access with support costs $150. Get Meta Box (affiliate link)

Step 1 – Register a Settings page

Install and activate Meta Box.

Next, install and activate either MB Settings Page + Meta Box Builder or Meta Box AIO.

Go to Meta Box > Settings Pages and click New Settings Page.

Give it a title of say, “Options”. This is only for organizational purpose and won’t be used in the code.

Option name: my_options

Select the gear (cog) icon.

Settings Page ID: my-options

Step 2 – Register a field group

Let’s create a field group for our settings page.

Go to Meta Box > Custom Fields and click Add New.

Give a title of say, “Sitewide”.

Add your desired fields. In this example, we are going to add

  1. logo – “Single Image” type of field
  2. notice – “WYSIWYG Editor” type of field
  3. button_background_color – “Color Picker” type of field

Set the field group to appear on the setting page created in the first step.

Note the sitewide_ string we have set as the Field ID prefix.

This means we can keep the ID of our fields simple like logo instead of sitewide_logo when adding the fields. In a later step when it is time to refer to the field, we need to use sitewide_logo even if the field ID appears as logo in the interface.

Step 3 – Populate the field group

Click Options in the WP admin left menu and populate the fields.

Step 4 – Define functions to retrieve field values

Let us define a custom function to get the URL of logo image from the settings page so we can set this as Oxygen Image component’s URL via dynamic data.

Install and activate Code Snippets plugin.

Go to Snippets > Add New.

Title: [Meta Box] Functions for getting Settings page field values

Code:

/* Get the URL of logo image from the settings page */
function wpdd_get_mb_settings_logo_url( $field_id ) {
	$logo = rwmb_meta( 'sitewide_logo', ['object_type' => 'setting'], 'my_options' );
	
	return $logo ? $logo['url'] : 'https://oxygen.local/wp-content/uploads/2021/03/placeholder-logo.png';
}

rwmb_meta() is the core function that we typically use with Meta Box.

Here we are supplying it 3 parameters:

  1. sitewide_logo: This is the internal ID of the custom field.
  2. ['object_type' => 'setting']: Since we are pulling the value from a Settings page.
  3. my_options: This is the option name from Step 1.

In the next line

return $logo ? $logo['url'] : 'https://oxygen.local/wp-content/uploads/2021/03/placeholder-logo.png';

we are checking to see if the logo field has an image set and if so, returning its URL and if not, setting it equal to a placeholder image’s URL.

Replace https://oxygen.local/wp-content/uploads/2021/03/placeholder-logo.png with the URL of a placeholder image from your site’s Media Library.

In the code snippet, we are currently using rwmb_meta function. It is a good idea to always wrap it in a if conditional that runs it only if that function exists. Meta Box documentation provides this handy code for the same:

/* Avoid Undefined Function Errors */
if ( ! function_exists( 'rwmb_meta' ) ) {
    function rwmb_meta( $key, $args = '', $post_id = null ) {
        return false;
    }
}

Place this code ABOVE so it is at the top of the code snippet.

Set the snippet to run everywhere. Save changes and activate.

Step 5

Edit your Main Catch All Template with Oxygen.

Add an Image component in the header.

Click data for the Image URL control, then PHP Function Return value.

Function Name: wpdd_get_mb_settings_logo_url

Click INSERT.

Click anywhere outside off of the image element and it should show the image from settings page (if present) or the fallback image (if not present).

You may want to set Width and/or Height values and Alt Text.

Now that you got a sense of how things work, let us proceed to define custom functions for pulling the other fields.

Custom function to pull the notice field

Edit the code snippet and add

/* Get the value of the specified Settings page field */
function wpdd_get_mb_settings_field( $field_id ) {
	return rwmb_meta( $field_id, ['object_type' => 'setting'], 'my_options' );
}

This function can be used for most type of fields created using Meta Box including our WYSIWYG field.

Our custom function wpdd_get_mb_settings_field has been set to receive one parameter: $field_id. This could be, for example, sitewide_notice.

Use the custom function

In the Oxygen editor, add a Section and move it above the header.

Add a Text component.

Double click it, select all the text (and delete, if using Safari). Click Insert Data in the top toolbar > PHP Function Return value.

Function Name: wpdd_get_mb_settings_field
Function Arguments: sitewide_notice

Click INSERT.

Click anywhere outside off of the text element and it should show the notice HTML from the settings page.

Conditional output of the section

When this field is empty we do not want the Section to be output. Oxygen’s conditions feature to the rescue!

Select the Section, click the Condition Settings icon and click Set Conditions.

Select Other > Dynamic Data.

Advanced > PHP Function Return value.

Function Name: wpdd_get_mb_settings_field
Function Arguments: sitewide_notice

Click INSERT.

Select is_not_blank as the operator.

CSS Custom property for the color picker value

Let us create a custom property or CSS variable whose value is equal to the color picker field’s value using the handy wp_add_inline_style() function in WordPress. We can then set this variable as the color inside Oxygen.

In the code snippet, add

add_action( 'wp_enqueue_scripts', 'custom_css_from_mb_color_picker_value' );
/**
 * Set custom CSS variable using the value from the Settings page.
 */
function custom_css_from_mb_color_picker_value() {

	$button_background_color = rwmb_meta( 'sitewide_button_background_color', ['object_type' => 'setting'], 'my_options' );
	
	$button_background_color = $button_background_color ? $button_background_color : '#65bec2';
	
	$custom_css = "
		:root {
			--button-background-color: {$button_background_color};
		}";

	wp_add_inline_style( 'oxygen', $custom_css );

}

#65bec2 is the fallback color. Change as needed.

Use the CSS variable in Oxygen

We can now refer to the above variable’s value via var(--button-background-color) in Oxygen wherever hexadecimal color can be entered.

and we are done.

This may seem like a lot of steps. But it should be fairly easy and straightforward if you spend a bit of time understanding how it is all working and go through the Meta Box documentation.


References

https://docs.metabox.io/extensions/mb-settings-page/

https://docs.metabox.io/displaying-fields/

https://docs.metabox.io/fields/image/

https://metabox.io/support/topic/getting-field-values-from-settings-page/

Need help implementing a tutorial in your site or want to hire me for custom work?

HIRE ME

Find the article helpful and wish to donate?

DONATE

Comments

You need to be logged in to view and post comments.
Not a member yet? Join here.
magnifiercross
linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram
%d bloggers like this: