WordPress Settings API

gistfile1.txt

https://code.tutsplus.com/tutorials/the-wordpress-settings-api-part-2-sections-fields-and-settings--wp-24619
The Settings API provided by WordPress is a set of funcitons that simplify the process of creating menus, options pages and the saving, validating and retrieving of user input. 

Sections, Fields, and Settings
Fields: individual options that appear on menu pages. It represents a value stored in the WordPress database. 
Sections: logical grouping of fields. 
Settings: registered after you've defined both fields and sections--settings are a combination of the field and the Section to which it belongs. 

Before writing any code, it can be helpful to list out exactly waht you settings you need and what you want them to do:
  • Define a section that will be used to group each field
  • Add fields to the sections they belong to
  • Register the settings with the WordPress API. 
  
Creating the Section
To create a section, you will use the add_settings_section() function. This function required three arguments:
  ID - this is a unique identifier for this section adn will be used to register each field within this section. 
  TITLE - This value is displayed at the top of the page in teh Wordpress Dashboard when users are working with your options
  CALLBACK - this is the name of a function that you'll define that will render text on the screen for the function.
  PAGE -  this value tells WrodPress which page your options should be displayed. 
  
To add your section to the general settings page, add your code to your functions.php file. 

  //Setting Registration -- this function is registered with the 'admin_init' hook
    add_action('admin_init', 'add_settings_page'); // second argument is a callback 
    function add_settings_page() {
      //register section
      add_settings_section(
        'general_settings_section',     //ID
        'General Options',              //Title to be dispalyed
        'get_general_settings_section', // callback 
        'general'                       // Page
      );
    } 
    
  //Section Callbacks -- provides a description for the General Options page, called above 
    function get_general_settingts_section() {
      echo '<p>Select whihc areas of content you wish to display</p>';
    }
    
   
   This added a section to the General Options page (because that's the page we specified). You can add it to a different page under the Settings Menu by passing in a different page title or you can create a new page under the Settings Menu to add it to. Here's a reference for each of the Settings pages and their corresponding key:

General, "general"
Writing, "writing"
Reading, "reading"
Discussion, "discussion"
Media, "media"
Privacy, "privacy"
Permalinks, "permalink"

Adding Fields
To add a settings field, you use the add_settings_field() function which takes 6 parameters (four required, two optoinal):

  ID - ID of the actual field, this is what you will use to reference/save/retreive teh value throughout your theme. 
  TITLE - This is the title that will be displayed to your users to know what this field is for
  CALLBACK - name of the function taht is used to render hte acutal interface element that the users will interact with
  PAGE - says which page teh option should be on.
  SECTION -  This is the ID of the section you created and want to add this field to  (optional)
  ARGUMENTS -  an array of arguments that are passed to the callback function. (optional)
  
  // this field is used for toggling visibility of content elements
    add_settings_field(
     'show_header',         //ID
     'Header',              //Title/lable to left of UI element
     'header_callback',     //callback function name
     'general',             //Page name
     'general_settings_section',  // name of section this field belongs to
     array(                  // array of arguments to pass to the callback (this one is just a description)
      'Activate this setting to display the header'
     )
   );
   
   // Define callback for field (called above)
     function header_callback($args) {
        //$args is only used because our field had a last element of an arguments array
        $field_name = 'show_header'
        $existing_value = get_option($field_name);
        bv_create_richtext_field_form($existing_value, $field_name);
        //creates textarea
     } 
  
    
    
Register Our Settings
In order to get our fields to save to the database, we need to register them with WordPress, all you need to do is use the register_setting() function. This function accepts three arguments (two required, one optional):
    OPTION GROUP -  The name of the group of options, this can be an existing group provided by WP or an ID we specified
    when creatiing a new section 
    OPTION NAME -  ID of the field we're registering
    CALLBACK - required teh anme of a fucntion that will be called prior to saving the data to the database. (optional)
    
//Register settings
  register_setting(
      'general',
      'show_header'
  );
  
  
Reading the API
We've created our options, now we want to be able to read the values and use them throughout our theme. 
To do this, we need to use the get_option() function, this accepts two arguments (one required, one optional). 
  OPTION ID - this is the ID of the field for hte value you're atempting to retreive
  DEFAULT OPTION - this is the value the funtion will return if the function returns an empty value (optional)