Changeset 33985

Timestamp:

09/10/2015 01:26:26 AM (9 years ago)

Author:

wonderboymusic

Message:

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

Adds unit tests.

Props swissspidy.
Fixes #19828.

Location:

trunk

Files:

• src/wp-admin/includes/screen.php (modified) (3 diffs)
• tests/phpunit/tests/admin/includesScreen.php (modified) (2 diffs)

trunk/src/wp-admin/includes/screen.php

@@ -719 +719 @@
      *
      * @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'];
     }
 
@@ -745 +763 @@
      *
      * @since 3.3.0
-     *
-     * @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.
-     *
+     * @since 4.4.0 The `$priority` argument was added.
+     *
+     * @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 ) {
@@ -759 +781 @@
             'content'  => '',
             'callback' => false,
+            'priority' => 10,
         );
         $args = wp_parse_args( $args, $defaults );

trunk/tests/phpunit/tests/admin/includesScreen.php

@@ -164 +164 @@
         $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();
@@ -171 +177 @@
         $screen->remove_help_tab( $tab );
         $this->assertNull( $screen->get_help_tab( $tab ) );
+
+        $screen->remove_help_tabs();
+        $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();