Function and usage of add_settings_field() in wordpress

Question

Answers ( 1 )

    0
    2024-01-05T12:36:05+00:00

    The add_settings_field() function in WordPress is a crucial tool for developers looking to add new fields to a settings page within the WordPress admin area. It's part of the Settings API, which provides a standardized way for creating and managing settings in WordPress themes and plugins. Here's a detailed explanation of how this function works and an example of its usage.

    Function:

    add_settings_field()

    Description:

    • Purpose: This function is used to add a new field to a section of a settings page.
    • Context: It's a part of the WordPress Settings API and is typically used to create custom settings in themes or plugins.
    • Display: The fields created by this function are displayed using do_settings_fields() within do_settings_sections().
    • Field Content: The content of the field (such as input boxes, checkboxes, etc.) is generated by a callback function specified in the parameters.

    Parameters:

    1. $id (string, required):

      • Description: The slug-name used to identify the field. This is used in the 'id' attribute of HTML tags.
      • Usage: It's important for ensuring the uniqueness of the field ID within the page.
    2. $title (string, required):

      • Description: The formatted title of the field, which is displayed as the label for the field during output.
      • Usage: It provides a human-readable name for the setting field.
    3. $callback (callable, required):

      • Description: A function that fills the field with the desired form inputs. This function should echo its output, not return it.
      • Usage: This is where the HTML for the input field is generated. Use get_option() within this function to retrieve existing values.
    4. $page (string, required):

      • Description: The slug-name of the settings page on which to show the section (e.g., 'general', 'reading', 'writing').
      • Usage: Determines where this setting field will be displayed in the WordPress admin area.
    5. $section (string, optional):

      • Default: 'default'
      • Description: The slug-name of the section of the settings page in which to show the box.
      • Usage: Used for organizing fields into different sections of the settings page.
    6. $args (array, optional):

      • Default: array()
      • Description: Extra arguments that get passed to the callback function. Useful for customizing the field output.
        • label_for: If provided, the setting title will be wrapped in a <label> element with its 'for' attribute set to this value.
        • class: CSS class to be added to the <tr> element when the field is output.

    Sample Usage:

    Here's a simple example of how to use add_settings_field():

    function custom_settings_init() {
        // Register a new setting for "reading" page
        register_setting('reading', 'custom_setting_name');
    
        // Add a new section to the "reading" page
        add_settings_section(
            'custom_settings_section',
            'Custom Settings Section',
            'custom_settings_section_callback',
            'reading'
        );
    
        // Add the field to the new section
        add_settings_field(
            'custom_setting_field',
            'Custom Setting',
            'custom_setting_callback',
            'reading',
            'custom_settings_section'
        );
    }
    
    function custom_settings_section_callback() {
        echo '<p>Custom settings section description</p>';
    }
    
    function custom_setting_callback() {
        // Get the current value of the setting
        $value = get_option('custom_setting_name');
        // Display the field
        echo "<input type='text' name='custom_setting_name' value='" . esc_attr($value) . "' />";
    }
    
    add_action('admin_init', 'custom_settings_init');
    

    In this example, a new setting field is added to the "reading" settings page of WordPress. The field is part of a custom section, and it includes a text input where the value can be entered and saved.

Leave an answer