dynamic_sidebar( int|string $index = 1 )

Display dynamic sidebar.

Contents

Description Description

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 Parameters

$index

(int|string) (Optional) Index, name or ID of dynamic sidebar.

Default value: 1

Top ↑

Return Return

(bool) True, if widget sidebar was found and called. False if not found or not called.

Top ↑

Source Source

File: wp-includes/widgets.php

634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
function dynamic_sidebar( $index = 1 ) {
    global $wp_registered_sidebars, $wp_registered_widgets;
 
    if ( is_int( $index ) ) {
        $index = "sidebar-$index";
    } else {
        $index = sanitize_title( $index );
        foreach ( (array) $wp_registered_sidebars as $key => $value ) {
            if ( sanitize_title( $value['name'] ) == $index ) {
                $index = $key;
                break;
            }
        }
    }
 
    $sidebars_widgets = wp_get_sidebars_widgets();
    if ( empty( $wp_registered_sidebars[ $index ] ) || empty( $sidebars_widgets[ $index ] ) || ! is_array( $sidebars_widgets[ $index ] ) ) {
        /** This action is documented in wp-includes/widget.php */
        do_action( 'dynamic_sidebar_before', $index, false );
        /** This action is documented in wp-includes/widget.php */
        do_action( 'dynamic_sidebar_after', $index, false );
        /** This filter is documented in wp-includes/widget.php */
        return apply_filters( 'dynamic_sidebar_has_widgets', false, $index );
    }
 
    /**
     * Fires before widgets are rendered in a dynamic sidebar.
     *
     * Note: The action also fires for empty sidebars, and on both the front end
     * and back end, including the Inactive Widgets sidebar on the Widgets screen.
     *
     * @since 3.9.0
     *
     * @param int|string $index       Index, name, or ID of the dynamic sidebar.
     * @param bool       $has_widgets Whether the sidebar is populated with widgets.
     *                                Default true.
     */
    do_action( 'dynamic_sidebar_before', $index, true );
    $sidebar = $wp_registered_sidebars[ $index ];
 
    $did_one = false;
    foreach ( (array) $sidebars_widgets[ $index ] as $id ) {
 
        if ( ! isset( $wp_registered_widgets[ $id ] ) ) {
            continue;
        }
 
        $params = array_merge(
            array(
                array_merge(
                    $sidebar,
                    array(
                        'widget_id'   => $id,
                        'widget_name' => $wp_registered_widgets[ $id ]['name'],
                    )
                ),
            ),
            (array) $wp_registered_widgets[ $id ]['params']
        );
 
        // Substitute HTML id and class attributes into before_widget
        $classname_ = '';
        foreach ( (array) $wp_registered_widgets[ $id ]['classname'] as $cn ) {
            if ( is_string( $cn ) ) {
                $classname_ .= '_' . $cn;
            } elseif ( is_object( $cn ) ) {
                $classname_ .= '_' . get_class( $cn );
            }
        }
        $classname_                 = ltrim( $classname_, '_' );
        $params[0]['before_widget'] = sprintf( $params[0]['before_widget'], $id, $classname_ );
 
        /**
         * Filters the parameters passed to a widget's display callback.
         *
         * Note: The filter is evaluated on both the front end and back end,
         * including for the Inactive Widgets sidebar on the Widgets screen.
         *
         * @since 2.5.0
         *
         * @see register_sidebar()
         *
         * @param array $params {
         *     @type array $args  {
         *         An array of widget display arguments.
         *
         *         @type string $name          Name of the sidebar the widget is assigned to.
         *         @type string $id            ID of the sidebar the widget is assigned to.
         *         @type string $description   The sidebar description.
         *         @type string $class         CSS class applied to the sidebar container.
         *         @type string $before_widget HTML markup to prepend to each widget in the sidebar.
         *         @type string $after_widget  HTML markup to append to each widget in the sidebar.
         *         @type string $before_title  HTML markup to prepend to the widget title when displayed.
         *         @type string $after_title   HTML markup to append to the widget title when displayed.
         *         @type string $widget_id     ID of the widget.
         *         @type string $widget_name   Name of the widget.
         *     }
         *     @type array $widget_args {
         *         An array of multi-widget arguments.
         *
         *         @type int $number Number increment used for multiples of the same widget.
         *     }
         * }
         */
        $params = apply_filters( 'dynamic_sidebar_params', $params );
 
        $callback = $wp_registered_widgets[ $id ]['callback'];
 
        /**
         * Fires before a widget's display callback is called.
         *
         * Note: The action fires on both the front end and back end, including
         * for widgets in the Inactive Widgets sidebar on the Widgets screen.
         *
         * The action is not fired for empty sidebars.
         *
         * @since 3.0.0
         *
         * @param array $widget_id {
         *     An associative array of widget arguments.
         *
         *     @type string $name                Name of the widget.
         *     @type string $id                  Widget ID.
         *     @type array|callable $callback    When the hook is fired on the front end, $callback is an array
         *                                       containing the widget object. Fired on the back end, $callback
         *                                       is 'wp_widget_control', see $_callback.
         *     @type array          $params      An associative array of multi-widget arguments.
         *     @type string         $classname   CSS class applied to the widget container.
         *     @type string         $description The widget description.
         *     @type array          $_callback   When the hook is fired on the back end, $_callback is populated
         *                                       with an array containing the widget object, see $callback.
         * }
         */
        do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] );
 
        if ( is_callable( $callback ) ) {
            call_user_func_array( $callback, $params );
            $did_one = true;
        }
    }
 
    /**
     * Fires after widgets are rendered in a dynamic sidebar.
     *
     * Note: The action also fires for empty sidebars, and on both the front end
     * and back end, including the Inactive Widgets sidebar on the Widgets screen.
     *
     * @since 3.9.0
     *
     * @param int|string $index       Index, name, or ID of the dynamic sidebar.
     * @param bool       $has_widgets Whether the sidebar is populated with widgets.
     *                                Default true.
     */
    do_action( 'dynamic_sidebar_after', $index, true );
 
    /**
     * Filters whether a sidebar has widgets.
     *
     * Note: The filter is also evaluated for empty sidebars, and on both the front end
     * and back end, including the Inactive Widgets sidebar on the Widgets screen.
     *
     * @since 3.9.0
     *
     * @param bool       $did_one Whether at least one widget was rendered in the sidebar.
     *                            Default false.
     * @param int|string $index   Index, name, or ID of the dynamic sidebar.
     */
    return apply_filters( 'dynamic_sidebar_has_widgets', $did_one, $index );
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
2.2.0 Introduced.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/formatting.php: sanitize_title()

Sanitizes a title, or returns a fallback title.
wp-includes/plugin.php: do_action()

Execute functions hooked on a specific action hook.
wp-includes/plugin.php: apply_filters()

Call the functions added to a filter hook.
wp-includes/widgets.php: wp_get_sidebars_widgets()

Retrieve full list of sidebars and their widget instance IDs.
wp-includes/widgets.php: dynamic_sidebar_before

Fires before widgets are rendered in a dynamic sidebar.
wp-includes/widgets.php: dynamic_sidebar_after

Fires after widgets are rendered in a dynamic sidebar.
wp-includes/widgets.php: dynamic_sidebar_has_widgets

Filters whether a sidebar has widgets.
wp-includes/widgets.php: dynamic_sidebar_params

Filters the parameters passed to a widget’s display callback.
wp-includes/widgets.php: dynamic_sidebar

Fires before a widget’s display callback is called.
Show 4 more uses Hide more uses

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Here is the recommended use of this function:

    1
    2
    3
    4
    5
    <?php if ( is_active_sidebar( 'left-sidebar' ) ) : ?>
        <ul id="sidebar">
            <?php dynamic_sidebar( 'left-sidebar' ); ?>
        </ul>
    <?php endif; ?>
    1
    2
    3
    <ul id="sidebar">
        <?php dynamic_sidebar( 'right-sidebar' ); ?>
    </ul>
    1
    2
    3
    4
    5
    6
    <ul id="sidebar">
    <?php if ( ! dynamic_sidebar() ) : ?>
        <li>{static sidebar item 1}</li>
        <li>{static sidebar item 2}</li>
    <?php endif; ?>
    </ul>

You must log in before being able to contribute a note or feedback.