From 6bc498c0e6ee9ba2d41a87d281a627f13f6708ac Mon Sep 17 00:00:00 2001
From: Scott Taylor <wonderboymusic@git.wordpress.org>
Date: Thu, 10 Sep 2015 01:26:26 +0000
Subject: [PATCH] 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             | 35 +++++++++--
 tests/phpunit/tests/admin/includesScreen.php | 64 +++++++++++++++++++-
 2 files changed, 92 insertions(+), 7 deletions(-)

diff --git a/src/wp-admin/includes/screen.php b/src/wp-admin/includes/screen.php
index d23cff36a3..7b84bcfd18 100644
--- a/src/wp-admin/includes/screen.php
+++ b/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
-	 * - string   - title    - Title for the 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.
+	 * @param array $args {
+	 *     Array of arguments used to display the help tab.
 	 *
+	 *     @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 );
 
diff --git a/tests/phpunit/tests/admin/includesScreen.php b/tests/phpunit/tests/admin/includesScreen.php
index b1333ce816..898bb4608c 100644
--- a/tests/phpunit/tests/admin/includesScreen.php
+++ b/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
 	 */