Enable tabbed-nav for options-pages via tab_group prop. See CMB2#301, C…

…MB2#627

CHANGELOG.md

@@ -3,6 +3,10 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+### Enhancements
+
+* Enable linking options pages via tabbed-navigation. Will output tabbed navigation for options-pages which share the same `'tab_group'` CMB2 box property. [This snippet](https://github.com/CMB2/CMB2-Snippet-Library/blob/master/options-and-settings-pages/options-pages-with-tabs-and-submenus.php) demonstrates how to create a top-level menu options page with multiple submenu pages, each with the tabbed navigation. To specify a different tab title than the options-page title, set the `'tab_title'` CMB2 box property. See [#301](https://github.com/CMB2/CMB2/issues/301), [#627](https://github.com/CMB2/CMB2/issues/627).
+
 ## [2.3.0 - 2017-12-20](https://github.com/CMB2/CMB2/releases/tag/v2.3.0)
 
 ### Enhancements

includes/CMB2.php

@@ -121,6 +121,8 @@ class CMB2 extends CMB2_Base {
 		'display_cb'       => false, // Override the options-page form output (CMB2_Hookup::options_page_output()).
 		'save_button'      => '', // The text for the options-page save button. Defaults to 'Save'.
 		'disable_settings_errors' => false, // On settings pages (not options-general.php sub-pages), allows disabling.
+		'tab_group'        => '', // Tab-group identifier, enables options page tab navigation.
+		// 'tab_title'    => null, // Falls back to 'title' (above). Do not define here so we can set a fallback.
 	);
 
 	/**

includes/CMB2_Options_Hookup.php

@@ -118,7 +118,7 @@ public function options_page_menu_hooks() {
 	 * @return void
 	 */
 	public function maybe_register_message() {
-		$is_options_page = isset( $_GET['page'] ) && $this->option_key === $_GET['page'];
+		$is_options_page = self::is_page( $this->option_key );
 		$should_notify   = ! $this->cmb->prop( 'disable_settings_errors' ) && isset( $_GET['settings-updated'] ) && $is_options_page;
 		$is_updated      = $should_notify && 'true' === $_GET['settings-updated'];
 		$setting         = "{$this->option_key}-notices";
@@ -181,11 +181,19 @@ public function options_page_output() {
 			return $callback( $this );
 		}
 
+		$tabs = $this->get_tab_group_tabs();
 		?>
 		<div class="wrap cmb2-options-page option-<?php echo $this->option_key; ?>">
 			<?php if ( $this->cmb->prop( 'title' ) ) : ?>
 				<h2><?php echo wp_kses_post( $this->cmb->prop( 'title' ) ); ?></h2>
 			<?php endif; ?>
+			<?php if ( ! empty( $tabs ) ) : ?>
+				<h2 class="nav-tab-wrapper">
+					<?php foreach ( $tabs as $option_key => $tab_title ) : ?>
+						<a class="nav-tab<?php if ( self::is_page( $option_key ) ) : ?> nav-tab-active<?php endif; ?>" href="<?php menu_page_url( $option_key ); ?>"><?php echo wp_kses_post( $tab_title ); ?></a>
+					<?php endforeach; ?>
+				</h2>
+			<?php endif; ?>
 			<form class="cmb-form" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>" method="POST" id="<?php echo $this->cmb->cmb_id; ?>" enctype="multipart/form-data" encoding="multipart/form-data">
 				<input type="hidden" name="action" value="<?php echo esc_attr( $this->option_key ); ?>">
 				<?php $this->options_page_metabox(); ?>
@@ -212,6 +220,35 @@ public function maybe_output_settings_notices() {
 		}
 	}
 
+	/**
+	 * Gets navigation tabs array for CMB2 options pages which share the
+	 * same tab_group property.
+	 *
+	 * @since 2.4.0
+	 * @return array Array of tab information ($option_key => $tab_title)
+	 */
+	public function get_tab_group_tabs() {
+		$tab_group = $this->cmb->prop( 'tab_group' );
+		$tabs      = array();
+
+		if ( $tab_group ) {
+			$boxes = CMB2_Boxes::get_by( 'tab_group', $tab_group );
+
+			foreach ( $boxes as $cmb_id => $cmb ) {
+				$option_key = $cmb->options_page_keys();
+
+				// Must have an option key, must be an options page box.
+				if ( ! isset( $option_key[0] ) || 'options-page' !== $cmb->mb_object_type() ) {
+					continue;
+				}
+
+				$tabs[ $option_key[0] ] = $cmb->prop( 'tab_title', $cmb->prop( 'title' ) );
+			}
+		}
+
+		return $tabs;
+	}
+
 	/**
 	 * Display metaboxes for an options-page object.
 	 *
@@ -269,6 +306,19 @@ public function network_update_override( $test, $option_value ) {
 		return update_site_option( $this->option_key, $option_value );
 	}
 
+	/**
+	 * Determines if given page slug matches the 'page' GET query variable.
+	 *
+	 * @since  2.4.0
+	 *
+	 * @param  string $page Page slug
+	 *
+	 * @return boolean
+	 */
+	public static function is_page( $page ) {
+		return isset( $_GET['page'] ) && $page === $_GET['page'];
+	}
+
 	/**
 	 * Magic getter for our object.
 	 *

tests/test-cmb-core.php

@@ -117,6 +117,7 @@ public function setUp() {
 			'message_cb'       => '',
 			'option_key'       => '',
 			'disable_settings_errors' => false, // On settings pages (not options-general.php sub-pages), allows disabling.
+			'tab_group'        => '',
 		);
 
 		$this->cmb = new CMB2( $this->metabox_array );