dynamic_sidebar

Display dynamic sidebar.

Description

dynamic_sidebar( (int) $index = 1 ); 

By default this displays the default sidebar or sidebar-1.. If your theme specifies the id or 'name' parameter for its registered sidebars you can pass an id or name as the $index parameter. Otherwise, you can pass in a numerical index to display the sidebar at that index.

Parameters (1)

0. $index — Optional. (int) => 1
Optional, default is 1. Index, name or ID of dynamic sidebar.

Usage

  1. if ( !function_exists( 'dynamic_sidebar' ) ) { 
  2. require_once ABSPATH . WPINC . '/widgets.php'; 
  3.  
  4. // Optional, default is 1. Index, name or ID of dynamic sidebar. 
  5. $index = 1; 
  6.  
  7. // NOTICE! Understand what this does before running. 
  8. $result = dynamic_sidebar($index); 
  9.  

Defined (1)

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

/wp-includes/widgets.php  
  1. function dynamic_sidebar( $index = 1 ) { 
  2. global $wp_registered_sidebars, $wp_registered_widgets; 
  3.  
  4. if ( is_int( $index ) ) { 
  5. $index = "sidebar-$index"; 
  6. } else { 
  7. $index = sanitize_title( $index ); 
  8. foreach ( (array) $wp_registered_sidebars as $key => $value ) { 
  9. if ( sanitize_title( $value['name'] ) == $index ) { 
  10. $index = $key; 
  11. break; 
  12.  
  13. $sidebars_widgets = wp_get_sidebars_widgets(); 
  14. if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) { 
  15. /** This action is documented in wp-includes/widget.php */ 
  16. do_action( 'dynamic_sidebar_before', $index, false ); 
  17. /** This action is documented in wp-includes/widget.php */ 
  18. do_action( 'dynamic_sidebar_after', $index, false ); 
  19. /** This filter is documented in wp-includes/widget.php */ 
  20. return apply_filters( 'dynamic_sidebar_has_widgets', false, $index ); 
  21.  
  22. /** 
  23. * Fires before widgets are rendered in a dynamic sidebar. 
  24. * Note: The action also fires for empty sidebars, and on both the front end 
  25. * and back end, including the Inactive Widgets sidebar on the Widgets screen. 
  26. * @since 3.9.0 
  27. * @param int|string $index Index, name, or ID of the dynamic sidebar. 
  28. * @param bool $has_widgets Whether the sidebar is populated with widgets. 
  29. * Default true. 
  30. */ 
  31. do_action( 'dynamic_sidebar_before', $index, true ); 
  32. $sidebar = $wp_registered_sidebars[$index]; 
  33.  
  34. $did_one = false; 
  35. foreach ( (array) $sidebars_widgets[$index] as $id ) { 
  36.  
  37. if ( !isset($wp_registered_widgets[$id]) ) continue; 
  38.  
  39. $params = array_merge( 
  40. array( array_merge( $sidebar, array('widget_id' => $id, 'widget_name' => $wp_registered_widgets[$id]['name']) ) ),  
  41. (array) $wp_registered_widgets[$id]['params'] 
  42. ); 
  43.  
  44. // Substitute HTML id and class attributes into before_widget 
  45. $classname_ = ''; 
  46. foreach ( (array) $wp_registered_widgets[$id]['classname'] as $cn ) { 
  47. if ( is_string($cn) ) 
  48. $classname_ .= '_' . $cn; 
  49. elseif ( is_object($cn) ) 
  50. $classname_ .= '_' . get_class($cn); 
  51. $classname_ = ltrim($classname_, '_'); 
  52. $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_); 
  53.  
  54. /** 
  55. * Filters the parameters passed to a widget's display callback. 
  56. * Note: The filter is evaluated on both the front end and back end,  
  57. * including for the Inactive Widgets sidebar on the Widgets screen. 
  58. * @since 2.5.0 
  59. * @see register_sidebar() 
  60. * @param array $params { 
  61. * @type array $args { 
  62. * An array of widget display arguments. 
  63. * @type string $name Name of the sidebar the widget is assigned to. 
  64. * @type string $id ID of the sidebar the widget is assigned to. 
  65. * @type string $description The sidebar description. 
  66. * @type string $class CSS class applied to the sidebar container. 
  67. * @type string $before_widget HTML markup to prepend to each widget in the sidebar. 
  68. * @type string $after_widget HTML markup to append to each widget in the sidebar. 
  69. * @type string $before_title HTML markup to prepend to the widget title when displayed. 
  70. * @type string $after_title HTML markup to append to the widget title when displayed. 
  71. * @type string $widget_id ID of the widget. 
  72. * @type string $widget_name Name of the widget. 
  73. * } 
  74. * @type array $widget_args { 
  75. * An array of multi-widget arguments. 
  76. * @type int $number Number increment used for multiples of the same widget. 
  77. * } 
  78. * } 
  79. */ 
  80. $params = apply_filters( 'dynamic_sidebar_params', $params ); 
  81.  
  82. $callback = $wp_registered_widgets[$id]['callback']; 
  83.  
  84. /** 
  85. * Fires before a widget's display callback is called. 
  86. * Note: The action fires on both the front end and back end, including 
  87. * for widgets in the Inactive Widgets sidebar on the Widgets screen. 
  88. * The action is not fired for empty sidebars. 
  89. * @since 3.0.0 
  90. * @param array $widget_id { 
  91. * An associative array of widget arguments. 
  92. * @type string $name Name of the widget. 
  93. * @type string $id Widget ID. 
  94. * @type array|callable $callback When the hook is fired on the front end, $callback is an array 
  95. * containing the widget object. Fired on the back end, $callback 
  96. * is 'wp_widget_control', see $_callback. 
  97. * @type array $params An associative array of multi-widget arguments. 
  98. * @type string $classname CSS class applied to the widget container. 
  99. * @type string $description The widget description. 
  100. * @type array $_callback When the hook is fired on the back end, $_callback is populated 
  101. * with an array containing the widget object, see $callback. 
  102. * } 
  103. */ 
  104. do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] ); 
  105.  
  106. if ( is_callable($callback) ) { 
  107. call_user_func_array($callback, $params); 
  108. $did_one = true; 
  109.  
  110. /** 
  111. * Fires after widgets are rendered in a dynamic sidebar. 
  112. * Note: The action also fires for empty sidebars, and on both the front end 
  113. * and back end, including the Inactive Widgets sidebar on the Widgets screen. 
  114. * @since 3.9.0 
  115. * @param int|string $index Index, name, or ID of the dynamic sidebar. 
  116. * @param bool $has_widgets Whether the sidebar is populated with widgets. 
  117. * Default true. 
  118. */ 
  119. do_action( 'dynamic_sidebar_after', $index, true ); 
  120.  
  121. /** 
  122. * Filters whether a sidebar has widgets. 
  123. * Note: The filter is also evaluated for empty sidebars, and on both the front end 
  124. * and back end, including the Inactive Widgets sidebar on the Widgets screen. 
  125. * @since 3.9.0 
  126. * @param bool $did_one Whether at least one widget was rendered in the sidebar. 
  127. * Default false. 
  128. * @param int|string $index Index, name, or ID of the dynamic sidebar. 
  129. */ 
  130. return apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index );