WordPress.org

Make WordPress Core

Ticket #39441: 39441.2.diff

File 39441.2.diff, 11.3 KB (added by flixos90, 3 years ago)
  • src/wp-admin/includes/template.php

     
    12351235 *
    12361236 * @global $wp_settings_fields Storage array of settings fields and info about their pages/sections
    12371237 *
    1238  * @param string   $id       Slug-name to identify the field. Used in the 'id' attribute of tags.
    1239  * @param string   $title    Formatted title of the field. Shown as the label for the field
    1240  *                           during output.
    1241  * @param callable $callback Function that fills the field with the desired form inputs. The
    1242  *                           function should echo its output.
    1243  * @param string   $page     The slug-name of the settings page on which to show the section
    1244  *                           (general, reading, writing, ...).
    1245  * @param string   $section  Optional. The slug-name of the section of the settings page
    1246  *                           in which to show the box. Default 'default'.
    1247  * @param array    $args {
     1238 * @param string          $id       Slug-name to identify the field. Used in the 'id' attribute of tags.
     1239 * @param string          $title    Formatted title of the field. Shown as the label for the field
     1240 *                                  during output.
     1241 * @param callable|string $callback Function that fills the field with the desired form inputs. The
     1242 *                                  function should echo its output. May instead be one out of 'text',
     1243 *                                  'number', 'email', 'url', 'tel', 'textarea', 'select', 'checkbox'
     1244 *                                  or 'radio' to use a default function to render the form input.
     1245 * @param string          $page     The slug-name of the settings page on which to show the section
     1246 *                                  (general, reading, writing, ...).
     1247 * @param string          $section  Optional. The slug-name of the section of the settings page
     1248 *                                  in which to show the box. Default 'default'.
     1249 * @param array           $args {
    12481250 *     Optional. Extra arguments used when outputting the field.
    12491251 *
    1250  *     @type string $label_for When supplied, the setting title will be wrapped
    1251  *                             in a `<label>` element, its `for` attribute populated
    1252  *                             with this value.
    1253  *     @type string $class     CSS Class to be added to the `<tr>` element when the
    1254  *                             field is output.
     1252 *     @type string   $input_id       The 'id' attribute of the input field. Default is the
     1253 *                                    value of $id.
     1254 *     @type string   $input_name     The `name` attribute of the input field. Default is the
     1255 *                                    value of $id.
     1256 *     @type string   $input_class    CSS Class to be added to the input field element when
     1257 *                                    it is output. Default empty.
     1258 *     @type string   $label_for      When supplied, the setting title will be wrapped
     1259 *                                    in a `<label>` element, its `for` attribute populated
     1260 *                                    with this value. Default is the value of $input_id.
     1261 *     @type string   $class          CSS Class to be added to the `<tr>` element when the
     1262 *                                    field is output. Default empty.
     1263 *     @type string   $description    When supplied, this description will be shown below the
     1264 *                                    input field when using a default callback function.
     1265 *     @type callable $value_callback Callback to retrieve the value. Default is
     1266 *                                    'get_settings_field_option', which calls get_option()
     1267 *                                    based on the $input_name argument.
    12551268 * }
    12561269 */
    12571270function add_settings_field($id, $title, $callback, $page, $section = 'default', $args = array()) {
     
    12671280                $page = 'reading';
    12681281        }
    12691282
     1283        $defaults = array(
     1284                'input_id'       => $id,
     1285                'input_name'     => $id,
     1286                'input_class'    => '',
     1287                'class'          => '',
     1288                'description'    => '',
     1289                'value_callback' => 'get_settings_field_option',
     1290        );
     1291
     1292        switch ( $callback ) {
     1293                case 'text':
     1294                case 'number':
     1295                case 'email':
     1296                case 'url':
     1297                case 'tel':
     1298                        $defaults['type'] = $callback;
     1299                        $callback = 'render_settings_field_text';
     1300                        break;
     1301                case 'select':
     1302                case 'checkbox':
     1303                case 'radio':
     1304                        $defaults['choices'] = array();
     1305                case 'textarea':
     1306                        $callback = 'render_settings_field_' . $callback;
     1307                        break;
     1308        }
     1309
     1310        $args = wp_parse_args( $args, $defaults );
     1311
     1312        if ( ! isset( $args['label_for'] ) ) {
     1313                $args['label_for'] = $args['input_id'];
     1314        }
     1315
    12701316        $wp_settings_fields[$page][$section][$id] = array('id' => $id, 'title' => $title, 'callback' => $callback, 'args' => $args);
    12711317}
    12721318
     
    13401386                }
    13411387
    13421388                echo '<td>';
    1343                 call_user_func($field['callback'], $field['args']);
     1389
     1390                // Duplicate arguments to not modify globals permanently.
     1391                $field_args = $field['args'];
     1392
     1393                if ( ! empty( $field_args['value_callback'] ) ) {
     1394                        $field_args['value'] = call_user_func( $field_args['value_callback'], $field_args );
     1395                }
     1396
     1397                call_user_func( $field['callback'], $field_args );
     1398
    13441399                echo '</td>';
    13451400                echo '</tr>';
    13461401        }
    13471402}
    13481403
    13491404/**
     1405 * Renders a text input for a settings field.
     1406 *
     1407 * This function is used as a default callback when specifying 'text',
     1408 * 'number', 'email', 'url' or 'tel' for the $callback parameter in
     1409 * `add_settings_field()`.
     1410 *
     1411 * @since 4.8.0
     1412 *
     1413 * @param array $field_args Field arguments. See the documentation for the
     1414 *                          $args parameter of `add_settings_field()` for a
     1415 *                          list of default arguments.
     1416 */
     1417function render_settings_field_text( $field_args ) {
     1418        $type = ! empty( $field_args['type'] ) ? $field_args['type'] : 'text';
     1419
     1420        $id    = ! empty( $field_args['input_id'] ) ? ' id="' . esc_attr( $field_args['input_id'] ) . '"' : '';
     1421        $name  = ! empty( $field_args['input_name'] ) ? ' name="' . esc_attr( $field_args['input_name'] ) . '"' : '';
     1422        $class = ! empty( $field_args['input_class'] ) ? ' class="' . esc_attr( $field_args['input_class'] ) . '"' : '';
     1423        $value = ! empty( $field_args['value'] ) ? ' value="' . esc_attr( $field_args['value'] ) . '"' : '';
     1424
     1425        $description_id = $aria_describedby = '';
     1426        if ( ! empty( $field_args['description'] ) && ! empty( $field_args['input_id'] ) ) {
     1427                $description_id   = ' id="' . $field_args['input_id'] . '-description"';
     1428                $aria_describedby = ' aria-describedby="' . $field_args['input_id'] . '-description"';
     1429        }
     1430
     1431        echo '<input type="' . esc_attr( $type ) . '"' . $id . $name . $class . $value . $aria_describedby . ' />';
     1432
     1433        if ( ! empty( $field_args['description'] ) ) {
     1434                echo '<p' . $description_id . ' class="description">' . $field_args['description'] . '</p>';
     1435        }
     1436}
     1437
     1438/**
     1439 * Renders a textarea input for a settings field.
     1440 *
     1441 * This function is used as a default callback when specifying 'textarea'
     1442 * for the $callback parameter in `add_settings_field()`.
     1443 *
     1444 * @since 4.8.0
     1445 *
     1446 * @param array $field_args Field arguments. See the documentation for the
     1447 *                          $args parameter of `add_settings_field()` for a
     1448 *                          list of default arguments.
     1449 */
     1450function render_settings_field_textarea( $field_args ) {
     1451        //TODO: Implement this.
     1452}
     1453
     1454/**
     1455 * Renders a dropdown input for a settings field.
     1456 *
     1457 * This function is used as a default callback when specifying 'select'
     1458 * for the $callback parameter in `add_settings_field()`.
     1459 *
     1460 * @since 4.8.0
     1461 *
     1462 * @param array $field_args Field arguments. See the documentation for the
     1463 *                          $args parameter of `add_settings_field()` for a
     1464 *                          list of default arguments.
     1465 */
     1466function render_settings_field_select( $field_args ) {
     1467        $id    = ! empty( $field_args['input_id'] ) ? ' id="' . esc_attr( $field_args['input_id'] ) . '"' : '';
     1468        $name  = ! empty( $field_args['input_name'] ) ? ' name="' . esc_attr( $field_args['input_name'] ) . '"' : '';
     1469        $class = ! empty( $field_args['input_class'] ) ? ' class="' . esc_attr( $field_args['input_class'] ) . '"' : '';
     1470
     1471        $choices = ! empty( $field_args['choices'] ) ? $field_args['choices'] : '';
     1472        $current = ! empty( $field_args['value'] ) ? $field_args['value'] : '';
     1473
     1474        $description_id = $aria_describedby = '';
     1475        if ( ! empty( $field_args['description'] ) && ! empty( $field_args['input_id'] ) ) {
     1476                $description_id   = ' id="' . $field_args['input_id'] . '-description"';
     1477                $aria_describedby = ' aria-describedby="' . $field_args['input_id'] . '-description"';
     1478        }
     1479
     1480        echo '<select' . $id . $name . $class . $aria_describedby . '>';
     1481
     1482        foreach ( $choices as $value => $label ) {
     1483                echo '<option value="' . esc_attr( $value ) . '"' . selected( $current, $value, false ) . '>' . esc_html( $label ) . '</option>';
     1484        }
     1485
     1486        echo '</select>';
     1487
     1488        if ( ! empty( $field_args['description'] ) ) {
     1489                echo '<p' . $description_id . ' class="description">' . $field_args['description'] . '</p>';
     1490        }
     1491}
     1492
     1493/**
     1494 * Renders a checkbox input for a settings field.
     1495 *
     1496 * This function is used as a default callback when specifying 'checkbox'
     1497 * for the $callback parameter in `add_settings_field()`.
     1498 *
     1499 * @since 4.8.0
     1500 *
     1501 * @param array $field_args Field arguments. See the documentation for the
     1502 *                          $args parameter of `add_settings_field()` for a
     1503 *                          list of default arguments.
     1504 */
     1505function render_settings_field_checkbox( $field_args ) {
     1506        //TODO: Implement this.
     1507}
     1508
     1509/**
     1510 * Renders a radio input for a settings field.
     1511 *
     1512 * This function is used as a default callback when specifying 'radio'
     1513 * for the $callback parameter in `add_settings_field()`.
     1514 *
     1515 * @since 4.8.0
     1516 *
     1517 * @param array $field_args Field arguments. See the documentation for the
     1518 *                          $args parameter of `add_settings_field()` for a
     1519 *                          list of default arguments.
     1520 */
     1521function render_settings_field_radio( $field_args ) {
     1522        //TODO: Implement this.
     1523}
     1524
     1525/**
     1526 * Retrieves the value for a settings field, based on the field arguments.
     1527 *
     1528 * The function will call `get_option()` based on the 'input_name' argument
     1529 * passed. It will automatically look for the correct key if an array option
     1530 * is used for the field.
     1531 *
     1532 * This is the default callback function used when registering a field with
     1533 * `add_settings_field()`.
     1534 *
     1535 * @since 4.8.0
     1536 *
     1537 * @param array $field_args Field arguments. See the documentation for the
     1538 *                          $args parameter of `add_settings_field()` for a
     1539 *                          list of default arguments.
     1540 * @return mixed The value for the settings field, or null if no value set.
     1541 */
     1542function get_settings_field_option( $field_args ) {
     1543        if ( empty( $field_args['input_name'] ) ) {
     1544                return null;
     1545        }
     1546
     1547        $keys = preg_split( '/\[/', str_replace( ']', '', $field_args['input_name'] ) );
     1548        $base = array_shift( $keys );
     1549
     1550        $value = get_option( $base, null );
     1551        while ( ! empty( $keys ) ) {
     1552                $current_key = array_shift( $keys );
     1553                if ( ! isset( $value[ $current_key ] ) ) {
     1554                        return null;
     1555                }
     1556
     1557                $value = $value[ $current_key ];
     1558        }
     1559
     1560        return $value;
     1561}
     1562
     1563/**
    13501564 * Register a settings error to be displayed to the user
    13511565 *
    13521566 * Part of the Settings API. Use this to show messages to users about settings validation