Changeset 31006

Timestamp:

12/30/2014 09:30:16 PM (10 years ago)

Author:

boonebgorges

Message:

In wp_dropdown_categories(), allow the term field used to populate option valuesto be specified.

The new 'value_field' parameter makes it possible to set term slugs (or some
other term property) as the 'value' attribute of the option elements generated
by wp_dropdown_categories(). This additional flexibility reduces the effort
required to translate term_id to other term fields when processing form
submissions that include values from taxonomy dropdowns. See #30865 for a
use case.

Props collinsinternet.
Fixes #30306.

Location:

trunk

Files:

• src/wp-includes/category-template.php (modified) (5 diffs)
• tests/phpunit/tests/category.php (modified) (1 diff)

trunk/src/wp-includes/category-template.php

@@ -294 +294 @@
  *
  * @since 2.1.0
+ * @since 4.2.0 Introduced the 'value_field' parameter.
  *
  * @param string|array $args {
@@ -328 +329 @@
  *                                           Defaults to the value of $name.
  *     @type string       $class             Optional. Value for the 'class' attribute of the select element.
- *     @type int          $selected          Optional. ID of the category to be selected.
+ *     @type int|string   $selected          Optional. Value of the option that should be selected.
+ *     @type string       $value_field       Optional. Term field that should be used to populate the 'value' attribute
+ *                                           of the option elements. Accepts any valid term field: 'term_id', 'name',
+ *                                           'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description',
+ *                                           'parent', 'count'. Default 'term_id'.
  *     @type string       $taxonomy          Optional. Name of the category to retrieve. Default 'category'.
  *     @type bool         $hide_if_empty     Optional. True to skip generating markup if no categories are found.
@@ -347 +352 @@
         'class' => 'postform', 'depth' => 0,
         'tab_index' => 0, 'taxonomy' => 'category',
-        'hide_if_empty' => false, 'option_none_value' => -1
+        'hide_if_empty' => false, 'option_none_value' => -1,
+        'value_field' => 'term_id',
     );
 
@@ -1107 +1113 @@
      * @param object $category Category data object.
      * @param int    $depth    Depth of category. Used for padding.
-     * @param array  $args     Uses 'selected' and 'show_count' keys, if they exist. @see wp_dropdown_categories()
+     * @param array  $args     Uses 'selected', 'show_count', and 'value_field' keys, if they exist.
+     *                         See {@see wp_dropdown_categories()}.
      */
     public function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) {
@@ -1115 +1122 @@
         $cat_name = apply_filters( 'list_cats', $category->name, $category );
 
-        $output .= "\t<option class=\"level-$depth\" value=\"".$category->term_id."\"";
+        if ( ! isset( $args['value_field'] ) || ! isset( $category->{$args['value_field']} ) ) {
+            $args['value_field'] = 'term_id';
+        }
+
+        $output .= "\t<option class=\"level-$depth\" value=\"" . esc_attr( $category->{$args['value_field']} ) . "\"";
+
         if ( $category->term_id == $args['selected'] )
             $output .= ' selected="selected"';

trunk/tests/phpunit/tests/category.php

@@ -247 +247 @@
     }
 
+    /**
+     * @ticket 30306
+     */
+    public function test_wp_dropdown_categories_value_field_should_default_to_term_id() {
+        // Create a test category.
+        $cat_id = $this->factory->category->create( array(
+            'name' => 'Test Category',
+            'slug' => 'test_category',
+        ) );
+
+        // Get the default functionality of wp_dropdown_categories().
+        $dropdown_default = wp_dropdown_categories( array(
+            'echo' => 0,
+            'hide_empty' => 0,
+        ) );
+
+        // Test to see if it returns the default with the category ID.
+        $this->assertContains( 'value="' . $cat_id . '"', $dropdown_default );
+    }
+
+    /**
+     * @ticket 30306
+     */
+    public function test_wp_dropdown_categories_value_field_term_id() {
+        // Create a test category.
+        $cat_id = $this->factory->category->create( array(
+            'name' => 'Test Category',
+            'slug' => 'test_category',
+        ) );
+
+        // Get the default functionality of wp_dropdown_categories().
+        $found = wp_dropdown_categories( array(
+            'echo' => 0,
+            'hide_empty' => 0,
+            'value_field' => 'term_id',
+        ) );
+
+        // Test to see if it returns the default with the category ID.
+        $this->assertContains( 'value="' . $cat_id . '"', $found );
+    }
+
+    /**
+     * @ticket 30306
+     */
+    public function test_wp_dropdown_categories_value_field_slug() {
+        // Create a test category.
+        $cat_id = $this->factory->category->create( array(
+            'name' => 'Test Category',
+            'slug' => 'test_category',
+        ) );
+
+        // Get the default functionality of wp_dropdown_categories().
+        $found = wp_dropdown_categories( array(
+            'echo' => 0,
+            'hide_empty' => 0,
+            'value_field' => 'slug',
+        ) );
+
+        // Test to see if it returns the default with the category slug.
+        $this->assertContains( 'value="test_category"', $found );
+    }
+
+    /**
+     * @ticket 30306
+     */
+    public function test_wp_dropdown_categories_value_field_should_fall_back_on_term_id_when_an_invalid_value_is_provided() {
+        // Create a test category.
+        $cat_id = $this->factory->category->create( array(
+            'name' => 'Test Category',
+            'slug' => 'test_category',
+        ) );
+
+        // Get the default functionality of wp_dropdown_categories().
+        $found = wp_dropdown_categories( array(
+            'echo' => 0,
+            'hide_empty' => 0,
+            'value_field' => 'foo',
+        ) );
+
+        // Test to see if it returns the default with the category slug.
+        $this->assertContains( 'value="' . $cat_id . '"', $found );
+    }
 }