Changeset 54247 for trunk/src/wp-admin/includes/template.php

Timestamp:

09/20/2022 09:57:43 AM (3 years ago)

Author:

audrasjb

Message:

Administration: Allow to wrap Settings sections with custom HTML content.

This changeset improves the add_settings_section() function to allow developers to pass extra HTML mark-up to be rendered before and after the settings section. Extra argument $args can now be passed to the function, and is an array that can contain the following items:

• before_section: HTML content to prepend to the section's HTML output. Receives the section's class name provided with the section_class argument via an optional %s placeholder. Default empty.
• after_section: HTML content to append to the section's HTML output. Default empty.
• section_class: The class name to use for the section. Used by before_section if a %s placeholder is present. Default empty.

The HTML passed using these extra arguments is escaped using wp_kses_post() just before rendering. This changeset also provides a set of unit tests for this new feature.

Props griffinjt, nacin, scribu, ross_ritchey, ryan, chriscct7, palmiak, rehanali, costdev, martinkrcho, chaion07, audrasjb, hellofromtonya.
Fixes #17851.

File:

• trunk/src/wp-admin/includes/template.php (modified) (5 diffs)

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

@@ -1562 +1562 @@
  *
  * @since 2.7.0
+ * @since 6.1.0 Added an `$args` parameter for the section's HTML wrapper and class name.
  *
  * @global array $wp_settings_sections Storage array of all settings sections added to admin pages.
@@ -1571 +1572 @@
  *                           'general', 'reading', 'writing', 'discussion', 'media', etc. Create your own using
  *                           add_options_page();
- */
-function add_settings_section( $id, $title, $callback, $page ) {
+ * @param array    $args     {
+ *     Arguments used to create the settings section.
+ *
+ *     @type string $before_section HTML content to prepend to the section's HTML output.
+ *                                  Receives the section's class name as `%s`. Default empty.
+ *     @type string $after_section  HTML content to append to the section's HTML output. Default empty.
+ *     @type string $section_class  The class name to use for the section. Default empty.
+ * }
+ */
+function add_settings_section( $id, $title, $callback, $page, $args = array() ) {
     global $wp_settings_sections;
+
+    $defaults = array(
+        'id'             => $id,
+        'title'          => $title,
+        'callback'       => $callback,
+        'before_section' => '',
+        'after_section'  => '',
+        'section_class'  => '',
+    );
+
+    $section = wp_parse_args( $args, $defaults );
 
     if ( 'misc' === $page ) {
@@ -1601 +1621 @@
     }
 
-    $wp_settings_sections[ $page ][ $id ] = array(
-        'id'       => $id,
-        'title'    => $title,
-        'callback' => $callback,
-    );
+    $wp_settings_sections[ $page ][ $id ] = $section;
 }
 
@@ -1701 +1717 @@
 
     foreach ( (array) $wp_settings_sections[ $page ] as $section ) {
+        if ( '' !== $section['before_section'] ) {
+            if ( '' !== $section['section_class'] ) {
+                echo wp_kses_post( sprintf( $section['before_section'], esc_attr( $section['section_class'] ) ) );
+            } else {
+                echo wp_kses_post( $section['before_section'] );
+            }
+        }
+
         if ( $section['title'] ) {
             echo "<h2>{$section['title']}</h2>\n";
@@ -1715 +1739 @@
         do_settings_fields( $page, $section['id'] );
         echo '</table>';
+
+        if ( '' !== $section['after_section'] ) {
+            echo wp_kses_post( $section['after_section'] );
+        }
     }
 }