Ticket #39441: 39441.2.diff

src/wp-admin/includes/template.php

@@ -1235 +1235 @@
  *
  * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections
  *
- * @param string   $id       Slug-name to identify the field. Used in the 'id' attribute of tags.
- * @param string   $title    Formatted title of the field. Shown as the label for the field
- *                           during output.
- * @param callable $callback Function that fills the field with the desired form inputs. The
- *                           function should echo its output.
- * @param string   $page     The slug-name of the settings page on which to show the section
- *                           (general, reading, writing, ...).
- * @param string   $section  Optional. The slug-name of the section of the settings page
- *                           in which to show the box. Default 'default'.
- * @param array    $args {
+ * @param string          $id       Slug-name to identify the field. Used in the 'id' attribute of tags.
+ * @param string          $title    Formatted title of the field. Shown as the label for the field
+ *                                  during output.
+ * @param callable|string $callback Function that fills the field with the desired form inputs. The
+ *                                  function should echo its output. May instead be one out of 'text',
+ *                                  'number', 'email', 'url', 'tel', 'textarea', 'select', 'checkbox'
+ *                                  or 'radio' to use a default function to render the form input.
+ * @param string          $page     The slug-name of the settings page on which to show the section
+ *                                  (general, reading, writing, ...).
+ * @param string          $section  Optional. The slug-name of the section of the settings page
+ *                                  in which to show the box. Default 'default'.
+ * @param array           $args {
  *     Optional. Extra arguments used when outputting the field.
  *
- *     @type string $label_for When supplied, the setting title will be wrapped
- *                             in a `<label>` element, its `for` attribute populated
- *                             with this value.
- *     @type string $class     CSS Class to be added to the `<tr>` element when the
- *                             field is output.
+ *     @type string   $input_id       The 'id' attribute of the input field. Default is the
+ *                                    value of $id.
+ *     @type string   $input_name     The `name` attribute of the input field. Default is the
+ *                                    value of $id.
+ *     @type string   $input_class    CSS Class to be added to the input field element when
+ *                                    it is output. Default empty.
+ *     @type string   $label_for      When supplied, the setting title will be wrapped
+ *                                    in a `<label>` element, its `for` attribute populated
+ *                                    with this value. Default is the value of $input_id.
+ *     @type string   $class          CSS Class to be added to the `<tr>` element when the
+ *                                    field is output. Default empty.
+ *     @type string   $description    When supplied, this description will be shown below the
+ *                                    input field when using a default callback function.
+ *     @type callable $value_callback Callback to retrieve the value. Default is
+ *                                    'get_settings_field_option', which calls get_option()
+ *                                    based on the $input_name argument.
  * }
  */
 function add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array()) {
@@ -1267 +1280 @@
                 $page = 'reading';
         }
 
+        $defaults = array(
+                'input_id'       => $id,
+                'input_name'     => $id,
+                'input_class'    => '',
+                'class'          => '',
+                'description'    => '',
+                'value_callback' => 'get_settings_field_option',
+        );
+
+        switch ( $callback ) {
+                case 'text':
+                case 'number':
+                case 'email':
+                case 'url':
+                case 'tel':
+                        $defaults['type'] = $callback;
+                        $callback = 'render_settings_field_text';
+                        break;
+                case 'select':
+                case 'checkbox':
+                case 'radio':
+                        $defaults['choices'] = array();
+                case 'textarea':
+                        $callback = 'render_settings_field_' . $callback;
+                        break;
+        }
+
+        $args = wp_parse_args( $args, $defaults );
+
+        if ( ! isset( $args['label_for'] ) ) {
+                $args['label_for'] = $args['input_id'];
+        }
+
         $wp_settings_fields[$page][$section][$id] = array('id' => $id, 'title' => $title, 'callback' => $callback, 'args' => $args);
 }
 
@@ -1340 +1386 @@
                 }
 
                 echo '<td>';
-                call_user_func($field['callback'], $field['args']);
+
+                // Duplicate arguments to not modify globals permanently.
+                $field_args = $field['args'];
+
+                if ( ! empty( $field_args['value_callback'] ) ) {
+                        $field_args['value'] = call_user_func( $field_args['value_callback'], $field_args );
+                }
+
+                call_user_func( $field['callback'], $field_args );
+
                 echo '</td>';
                 echo '</tr>';
         }
 }
 
 /**
+ * Renders a text input for a settings field.
+ *
+ * This function is used as a default callback when specifying 'text',
+ * 'number', 'email', 'url' or 'tel' for the $callback parameter in
+ * `add_settings_field()`.
+ *
+ * @since 4.8.0
+ *
+ * @param array $field_args Field arguments. See the documentation for the
+ *                          $args parameter of `add_settings_field()` for a
+ *                          list of default arguments.
+ */
+function render_settings_field_text( $field_args ) {
+        $type = ! empty( $field_args['type'] ) ? $field_args['type'] : 'text';
+
+        $id    = ! empty( $field_args['input_id'] ) ? ' id="' . esc_attr( $field_args['input_id'] ) . '"' : '';
+        $name  = ! empty( $field_args['input_name'] ) ? ' name="' . esc_attr( $field_args['input_name'] ) . '"' : '';
+        $class = ! empty( $field_args['input_class'] ) ? ' class="' . esc_attr( $field_args['input_class'] ) . '"' : '';
+        $value = ! empty( $field_args['value'] ) ? ' value="' . esc_attr( $field_args['value'] ) . '"' : '';
+
+        $description_id = $aria_describedby = '';
+        if ( ! empty( $field_args['description'] ) && ! empty( $field_args['input_id'] ) ) {
+                $description_id   = ' id="' . $field_args['input_id'] . '-description"';
+                $aria_describedby = ' aria-describedby="' . $field_args['input_id'] . '-description"';
+        }
+
+        echo '<input type="' . esc_attr( $type ) . '"' . $id . $name . $class . $value . $aria_describedby . ' />';
+
+        if ( ! empty( $field_args['description'] ) ) {
+                echo '<p' . $description_id . ' class="description">' . $field_args['description'] . '</p>';
+        }
+}
+
+/**
+ * Renders a textarea input for a settings field.
+ *
+ * This function is used as a default callback when specifying 'textarea'
+ * for the $callback parameter in `add_settings_field()`.
+ *
+ * @since 4.8.0
+ *
+ * @param array $field_args Field arguments. See the documentation for the
+ *                          $args parameter of `add_settings_field()` for a
+ *                          list of default arguments.
+ */
+function render_settings_field_textarea( $field_args ) {
+        //TODO: Implement this.
+}
+
+/**
+ * Renders a dropdown input for a settings field.
+ *
+ * This function is used as a default callback when specifying 'select'
+ * for the $callback parameter in `add_settings_field()`.
+ *
+ * @since 4.8.0
+ *
+ * @param array $field_args Field arguments. See the documentation for the
+ *                          $args parameter of `add_settings_field()` for a
+ *                          list of default arguments.
+ */
+function render_settings_field_select( $field_args ) {
+        $id    = ! empty( $field_args['input_id'] ) ? ' id="' . esc_attr( $field_args['input_id'] ) . '"' : '';
+        $name  = ! empty( $field_args['input_name'] ) ? ' name="' . esc_attr( $field_args['input_name'] ) . '"' : '';
+        $class = ! empty( $field_args['input_class'] ) ? ' class="' . esc_attr( $field_args['input_class'] ) . '"' : '';
+
+        $choices = ! empty( $field_args['choices'] ) ? $field_args['choices'] : '';
+        $current = ! empty( $field_args['value'] ) ? $field_args['value'] : '';
+
+        $description_id = $aria_describedby = '';
+        if ( ! empty( $field_args['description'] ) && ! empty( $field_args['input_id'] ) ) {
+                $description_id   = ' id="' . $field_args['input_id'] . '-description"';
+                $aria_describedby = ' aria-describedby="' . $field_args['input_id'] . '-description"';
+        }
+
+        echo '<select' . $id . $name . $class . $aria_describedby . '>';
+
+        foreach ( $choices as $value => $label ) {
+                echo '<option value="' . esc_attr( $value ) . '"' . selected( $current, $value, false ) . '>' . esc_html( $label ) . '</option>';
+        }
+
+        echo '</select>';
+
+        if ( ! empty( $field_args['description'] ) ) {
+                echo '<p' . $description_id . ' class="description">' . $field_args['description'] . '</p>';
+        }
+}
+
+/**
+ * Renders a checkbox input for a settings field.
+ *
+ * This function is used as a default callback when specifying 'checkbox'
+ * for the $callback parameter in `add_settings_field()`.
+ *
+ * @since 4.8.0
+ *
+ * @param array $field_args Field arguments. See the documentation for the
+ *                          $args parameter of `add_settings_field()` for a
+ *                          list of default arguments.
+ */
+function render_settings_field_checkbox( $field_args ) {
+        //TODO: Implement this.
+}
+
+/**
+ * Renders a radio input for a settings field.
+ *
+ * This function is used as a default callback when specifying 'radio'
+ * for the $callback parameter in `add_settings_field()`.
+ *
+ * @since 4.8.0
+ *
+ * @param array $field_args Field arguments. See the documentation for the
+ *                          $args parameter of `add_settings_field()` for a
+ *                          list of default arguments.
+ */
+function render_settings_field_radio( $field_args ) {
+        //TODO: Implement this.
+}
+
+/**
+ * Retrieves the value for a settings field, based on the field arguments.
+ *
+ * The function will call `get_option()` based on the 'input_name' argument
+ * passed. It will automatically look for the correct key if an array option
+ * is used for the field.
+ *
+ * This is the default callback function used when registering a field with
+ * `add_settings_field()`.
+ *
+ * @since 4.8.0
+ *
+ * @param array $field_args Field arguments. See the documentation for the
+ *                          $args parameter of `add_settings_field()` for a
+ *                          list of default arguments.
+ * @return mixed The value for the settings field, or null if no value set.
+ */
+function get_settings_field_option( $field_args ) {
+        if ( empty( $field_args['input_name'] ) ) {
+                return null;
+        }
+
+        $keys = preg_split( '/\[/', str_replace( ']', '', $field_args['input_name'] ) );
+        $base = array_shift( $keys );
+
+        $value = get_option( $base, null );
+        while ( ! empty( $keys ) ) {
+                $current_key = array_shift( $keys );
+                if ( ! isset( $value[ $current_key ] ) ) {
+                        return null;
+                }
+
+                $value = $value[ $current_key ];
+        }
+
+        return $value;
+}
+
+/**
  * Register a settings error to be displayed to the user
  *
  * Part of the Settings API. Use this to show messages to users about settings validation