Implement a priority system for Help Tabs to add them at specific positions.

Adds unit tests.

Props swissspidy.
Fixes #19828.


git-svn-id: https://develop.svn.wordpress.org/trunk@33985 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-admin/includes/screen.php

@@ -718,11 +718,29 @@ final class WP_Screen {
 	 * Gets the help tabs registered for the screen.
 	 *
 	 * @since 3.4.0
+	 * @since 4.4.0 Help tabs are ordered by their priority.
 	 *
 	 * @return array Help tabs with arguments.
 	 */
 	public function get_help_tabs() {
-		return $this->_help_tabs;
+		$help_tabs = $this->_help_tabs;
+		uasort( $help_tabs, array( $this, '_sort_help_tabs' ) );
+		return $help_tabs;
+	}
+
+	/**
+	 * Compares the difference between the help tabs priorities.
+	 *
+	 * Used for help tabs sorting.
+	 *
+	 * @since 4.4.0
+	 *
+	 * @param int $tab_a The priority argument for the first tab.
+	 * @param int $tab_b The priority argument for the second tab.
+	 * @return int The difference between the priority arguments.
+	 */
+	protected function _sort_help_tabs( $tab_a, $tab_b ) {
+		return $tab_a['priority'] - $tab_b['priority'];
 	}
 
 	/**
@@ -744,13 +762,17 @@ final class WP_Screen {
 	 * Call this on the load-$pagenow hook for the relevant screen.
 	 *
 	 * @since 3.3.0
+	 * @since 4.4.0 The `$priority` argument was added.
 	 *
-	 * @param array $args
+	 * @param array $args {
-	 * - string   - title    - Title for the tab.
+	 *     Array of arguments used to display the help tab.
-	 * - string   - id       - Tab ID. Must be HTML-safe.
-	 * - string   - content  - Help tab content in plain text or HTML. Optional.
-	 * - callback - callback - A callback to generate the tab content. Optional.
 	 *
+	 *     @type string $title    Title for the tab. Default false.
+	 *     @type string $id       Tab ID. Must be HTML-safe. Default false.
+	 *     @type string $content  Optional. Help tab content in plain text or HTML. Default empty string.
+	 *     @type string $callback Optional. A callback to generate the tab content. Default false.
+	 *     @type int    $priority Optional. The priority of the tab, used for ordering. Default 10.
+	 * }
 	 */
 	public function add_help_tab( $args ) {
 		$defaults = array(
@@ -758,6 +780,7 @@ final class WP_Screen {
 			'id'       => false,
 			'content'  => '',
 			'callback' => false,
+			'priority' => 10,
 		);
 		$args = wp_parse_args( $args, $defaults );
 

tests/phpunit/tests/admin/includesScreen.php

@@ -163,7 +163,13 @@ class Tests_Admin_includesScreen extends WP_UnitTestCase {
 
 		$screen = get_current_screen();
 		$screen->add_help_tab( $tab_args );
-		$this->assertEquals( $screen->get_help_tab( $tab ), $tab_args );
+		$this->assertEquals( $screen->get_help_tab( $tab ), array(
+			'id' => $tab,
+			'title' => 'Help!',
+			'content' => 'Some content',
+			'callback' => false,
+			'priority' => 10,
+		) );
 
 		$tabs = $screen->get_help_tabs();
 		$this->assertArrayHasKey( $tab, $tabs );
@@ -175,6 +181,62 @@ class Tests_Admin_includesScreen extends WP_UnitTestCase {
 		$this->assertEquals( $screen->get_help_tabs(), array() );
 	}
 
+	/**
+	 * @ticket 19828
+	 */
+	function test_help_tabs_priority() {
+		$tab_1      = rand_str();
+		$tab_1_args = array(
+			'id'       => $tab_1,
+			'title'    => 'Help!',
+			'content'  => 'Some content',
+			'callback' => false,
+			'priority' => 11,
+		);
+
+		$tab_2      = rand_str();
+		$tab_2_args = array(
+			'id'       => $tab_2,
+			'title'    => 'Help!',
+			'content'  => 'Some content',
+			'callback' => false,
+			'priority' => 9,
+		);
+
+		$screen = get_current_screen();
+
+		// Add help tabs.
+
+		$screen->add_help_tab( $tab_1_args );
+		$this->assertEquals( $screen->get_help_tab( $tab_1 ), $tab_1_args );
+
+		$screen->add_help_tab( $tab_2_args );
+		$this->assertEquals( $screen->get_help_tab( $tab_2 ), $tab_2_args );
+
+		$tabs = $screen->get_help_tabs();
+		$this->assertEquals( 2, count( $tabs ) );
+		$this->assertArrayHasKey( $tab_1, $tabs );
+		$this->assertArrayHasKey( $tab_2, $tabs );
+
+		// Test priority order.
+
+		$this->assertEquals( $tabs, array(
+			$tab_2 => $tab_2_args,
+			$tab_1 => $tab_1_args,
+		) );
+
+		$screen->remove_help_tab( $tab_1 );
+		$this->assertNull( $screen->get_help_tab( $tab_1 ) );
+		$this->assertEquals( 1, count( $screen->get_help_tabs() ) );
+
+		$screen->remove_help_tab( $tab_2 );
+		$this->assertNull( $screen->get_help_tab( $tab_2 ) );
+		$this->assertEquals( 0, count( $screen->get_help_tabs() ) );
+
+		$screen->remove_help_tabs();
+		$this->assertEquals( $screen->get_help_tabs(), array() );
+	}
+
 	/**
 	 * @ticket 25799
 	 */