register_sidebar

Builds the definition for a single sidebar and returns the ID.

Description

(string) register_sidebar( (array) $args = array() ); 

Accepts either a string or an array and then parses that against a set of default arguments for the new sidebar. WordPress will automatically generate a sidebar ID and name based on the current number of registered sidebars if those arguments are not included.

When allowing for automatic generation of the name and ID parameters, keep in mind that the incrementor for your sidebar can change over time depending on what other plugins and themes are installed.

If theme support for widgets has not yet been added when this function is called, it will be automatically enabled through the use of add_theme_support()

Returns (string)

Sidebar ID added to $wp_registered_sidebars global.

Parameters (1)

0. $args — Optional. (array) => array()
Array or string of arguments for the sidebar being registered.

Options

  • name (string) => 'Sidebar $instance'

    The name or title of the sidebar displayed in the Widgets interface.

  • id (string) => 'sidebar-$instance'

    The unique identifier by which the sidebar will be called.

  • description (string) => string

    Description of the sidebar, displayed in the Widgets interface.

  • class (string) => ''

    Extra CSS class to assign to the sidebar in the Widgets interface.

  • before_widget (string) => is an opening list item element

    HTML content to prepend to each widget's HTML output when assigned to this sidebar.

  • after_widget (string) => is a closing list item element

    HTML content to append to each widget's HTML output when assigned to this sidebar.

  • before_title (string) => is an opening h2 element

    HTML content to prepend to the sidebar title when displayed.

array(

    /**
     * The name or title of the sidebar displayed in the Widgets interface.
     *
     * @type string
     * @default 'Sidebar $instance'
     */
    'name' => 'Sidebar $instance',

    /**
     * The unique identifier by which the sidebar will be called.
     *
     * @type string
     * @default 'sidebar-$instance'
     */
    'id' => 'sidebar-$instance',

    /**
     * Description of the sidebar, displayed in the Widgets interface.
     *
     * @type string
     * @default string
     */
    'description' => string,

    /**
     * Extra CSS class to assign to the sidebar in the Widgets interface.
     *
     * @type string
     * @default ''
     */
    'class' => '',

    /**
     * HTML content to prepend to each widget's HTML output when assigned to this sidebar.
     *
     * @type string
     * @default is an opening list item element
     */
    'before_widget' => is an opening list item element,

    /**
     * HTML content to append to each widget's HTML output when assigned to this sidebar.
     *
     * @type string
     * @default is a closing list item element
     */
    'after_widget' => is a closing list item element,

    /**
     * HTML content to prepend to the sidebar title when displayed.
     *
     * @type string
     * @default is an opening h2 element
     */
    'before_title' => is an opening h2 element
);        


Usage

  1. if ( !function_exists( 'register_sidebar' ) ) { 
  2. require_once ABSPATH . WPINC . '/widgets.php'; 
  3.  
  4. // Optional. Array or string of arguments for the sidebar being registered. 
  5. $args = array( 
  6. 'name' => 'Sidebar $instance', 
  7. 'id' => 'sidebar-$instance', 
  8. 'description' => string, 
  9. 'class' => '', 
  10. 'before_widget' => is an opening list item element, 
  11. 'after_widget' => is a closing list item element, 
  12. 'before_title' => is an opening h2 element 
  13. ); 
  14.  
  15. // NOTICE! Understand what this does before running. 
  16. $result = register_sidebar($args); 
  17.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/widgets.php  
  1. function register_sidebar($args = array()) { 
  2. global $wp_registered_sidebars; 
  3.  
  4. $i = count($wp_registered_sidebars) + 1; 
  5.  
  6. $id_is_empty = empty( $args['id'] ); 
  7.  
  8. $defaults = array( 
  9. 'name' => sprintf(__('Sidebar %d'), $i ),  
  10. 'id' => "sidebar-$i",  
  11. 'description' => '',  
  12. 'class' => '',  
  13. 'before_widget' => '<li id="%1$s" class="widget %2$s">',  
  14. 'after_widget' => "</li>\n",  
  15. 'before_title' => '<h2 class="widgettitle">',  
  16. 'after_title' => "</h2>\n",  
  17. ); 
  18.  
  19. $sidebar = wp_parse_args( $args, $defaults ); 
  20.  
  21. if ( $id_is_empty ) { 
  22. /** translators: 1: the id argument, 2: sidebar name, 3: recommended id value */ 
  23. _doing_it_wrong( __FUNCTION__, sprintf( __( 'No %1$s was set in the arguments array for the "%2$s" sidebar. Defaulting to "%3$s". Manually set the %1$s to "%3$s" to silence this notice and keep existing sidebar content.' ), '<code>id</code>', $sidebar['name'], $sidebar['id'] ), '4.2.0' ); 
  24.  
  25. $wp_registered_sidebars[$sidebar['id']] = $sidebar; 
  26.  
  27. add_theme_support('widgets'); 
  28.  
  29. /** 
  30. * Fires once a sidebar has been registered. 
  31. * @since 3.0.0 
  32. * @param array $sidebar Parsed arguments for the registered sidebar. 
  33. */ 
  34. do_action( 'register_sidebar', $sidebar ); 
  35.  
  36. return $sidebar['id'];