CMB2 option-page parameter

Question

CMB2 has an option to use as an option page.

I'm looking in the example files, and on the wiki page but even copying and pasting the example on the files it not work.

I'm probably missing something, but I can't find what it is, I already spent two days trying to make this work.

Following the wiki and the example I modified to this code

add_action( 'cmb2_admin_init', 'yourprefix_register_theme_options_metabox' );
function yourprefix_register_theme_options_metabox() {

    $option_key = 'wherever';

    $cmb = new_cmb2_box( array(
        'id'=> $option_key . '_theme_options-page',
        'object_types' => array( 'options-page' ),
        'hookup'  => false,
        'menu_title' => 'Site Options',
        'parent_slug' => 'tools.php',
        'capability' => 'manage_options'
    ) );

    $cmb->add_field( array(
        'name'    => 'Site Background Color',
        'desc'    => 'field description',
        'id'      => 'bg_color',
        'type'    => 'colorpicker',
        'default' => '#ffffff'
    ) );

}

Any leads on why it's not working?

Answer 1

Currently the documentation for CMB2's options page capabilities just takes you to their Snippet Library which isn't 100% straightforward, so hopefully I can help clarify how to use these functions properly.

First, the metaboxes you register in cmb2_admin_init can generate an entire admin page. Take this code example straight from the snippet library for instance:

add_action('cmb2_admin_init', 'register_my_admin_page');
function register_my_admin_page() {
  /**
   * Registers options page menu item and form.
   */
  $cmb_options = new_cmb2_box( array(
    'id'           => 'myprefix_option_metabox',
    'title'        => esc_html__( 'Site Options', 'myprefix' ),
    'object_types' => array( 'options-page' ),
    /*
      * The following parameters are specific to the options-page box
      * Several of these parameters are passed along to add_menu_page()/add_submenu_page().
      */
    'option_key'      => 'myprefix_options', // The option key and admin menu page slug.
    // 'icon_url'        => 'dashicons-palmtree', // Menu icon. Only applicable if 'parent_slug' is left empty.
    // 'menu_title'      => esc_html__( 'Options', 'myprefix' ), // Falls back to 'title' (above).
    // 'parent_slug'     => 'themes.php', // Make options page a submenu item of the themes menu.
    // 'capability'      => 'manage_options', // Cap required to view options-page.
    // 'position'        => 1, // Menu position. Only applicable if 'parent_slug' is left empty.
    // 'admin_menu_hook' => 'network_admin_menu', // 'network_admin_menu' to add network-level options page.
    // 'display_cb'      => false, // Override the options-page form output (CMB2_Hookup::options_page_output()).
    // 'save_button'     => esc_html__( 'Save Theme Options', 'myprefix' ), // The text for the options-page save button. Defaults to 'Save'.
  ) );

  /*
    * Options fields ids only need
    * to be unique within this box.
    * Prefix is not needed.
    */
  $cmb_options->add_field( array(
    'name' => __( 'Test Text', 'myprefix' ),
    'desc' => __( 'field description (optional)', 'myprefix' ),
    'id'   => 'test_text',
    'type' => 'text',
    'default' => 'Default Text',
  ) );
  $cmb_options->add_field( array(
    'name'    => __( 'Test Color Picker', 'myprefix' ),
    'desc'    => __( 'field description (optional)', 'myprefix' ),
    'id'      => 'test_colorpicker',
    'type'    => 'colorpicker',
    'default' => '#bada55',
  ) );
}

This code snippet will generate a top-level admin page named "Site Options" with two fields: a text field and a color-picker field, complete with a title, form fields, submit button, etc. You can configure how the page is displayed to the user using the commented out settings on the new_cmb2_box function.

When the form is saved, it will save the meta box and its fields to the site option myprefix_options. So if you call the function get_option('myprefix_options'), it will return the following array:

array(
  'myprefix_option_metabox' => array(
    'test_text' => '' // value of the Test Text field,
    'test_colorpicker' => '' // value of the Test Color Picker field
  )
)

I hope that helps clarify things a bit.