register_sidebar()注册并创建一个新的侧边栏

目录

描述

Builds the definition for a single sidebar and returns the ID. Call on "widgets_init" action.

register_sidebar() 描述

用法

<?php register_sidebar$args ); ?>

Default Usage

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
<?php $args = array(	'name'          => __( 'Sidebar name', 'theme_text_domain' ),	'id'            => 'unique-sidebar-id',	'description'   => '',        'class'         => '',	'before_widget' => '<li id="%1$s" class="widget %2$s">',	'after_widget'  => '</li>',	'before_title'  => '<h2 class="widgettitle">',	'after_title'   => '</h2>' ); ?>

register_sidebar() 用法

参数

args

(string/array) (可选) Builds Sidebar based off of 'name' and 'id' values.

默认值: None

  • name - Sidebar name (default is localized 'Sidebar' and numeric ID).
  • id - Sidebar id - Must be all in lowercase, with no spaces (default is a numeric auto-incremented ID). If you do not set the id argument value, you will get E_USER_NOTICE messages in debug mode, starting with version 4.2.
  • description - Text description of what/where the sidebar is. Shown on widget management screen. (Since 2.9) (default: empty)
  • class - CSS class to assign to the Sidebar in the Appearance -> Widget admin page. This class will only appear in the source of the WordPress Widget admin page. It will not be included in the frontend of your website. Note: The value "sidebar" will be prepended to the class value. For example, a class of "tal" will result in a class value of "sidebar-tal". (default: empty).
  • before_widget - HTML to place before every widget(default: <li id="%1$s" class="widget %2$s">) Note: uses sprintf for variable substitution
  • after_widget - HTML to place after every widget (default: </li>
    ).
  • before_title - HTML to place before every title (default: <h2 class="widgettitle">).
  • after_title - HTML to place after every title (default: </h2>
    ).

The optional args parameter is an associative array that will be passed as a first argument to every active widget callback. (If a string is passed instead of an array, it will be passed through parse_str() to generate an associative array.) The basic use for these arguments is to pass theme-specific HTML tags to wrap the widget and its title.

register_sidebar() 参数

注意

  • With WordPress 3.4.1 there're still some IDs to avoid, that can be found here. Props to "toscho" for building a plugin collecting and listing them.
  • Calling register_sidebar() multiple times to register a number of sidebars is preferable to using register_sidebars() to create a bunch in one go, because it allows you to assign a unique name to each sidebar (eg: “Right Sidebar”, “Left Sidebar”). Although these names only appear in the admin interface it is a best practice to name each sidebar specifically, giving the administrative user some idea as to the context for which each sidebar will be used.
  • The default before/after values are intended for themes that generate a sidebar marked up as a list with h2 titles. This is the convention we recommend for all themes and any theme built in this way can simply register sidebars without worrying about the before/after tags. If, for some compelling reason, a theme cannot be marked up in this way, these tags must be specified when registering sidebars. It is recommended to copy the id and class attributes verbatim so that an internal sprintf call can work and CSS styles can be applied to individual widgets.

register_sidebar() 注意

历史

  • 4.2.0 : Missing id property now triggers E_USER_NOTICE.
  • 2.9.0 : Added description property
  • 添加于 版本: 2.2.0

register_sidebar() 历史

源文件

register_sidebar() 函数的代码位于 wp-includes/widgets.php.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
/**
 * Builds the definition for a single sidebar and returns the ID.
 *
 * 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()
 *
 * @since 2.2.0
 *
 * @global array $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
 *
 * @param array|string $args {
 *     Optional. Array or string of arguments for the sidebar being registered.
 *
 *     @type string $name          The name or title of the sidebar displayed in the Widgets
 *                                 interface. Default 'Sidebar $instance'.
 *     @type string $id            The unique identifier by which the sidebar will be called.
 *                                 Default 'sidebar-$instance'.
 *     @type string $description   Description of the sidebar, displayed in the Widgets interface.
 *                                 Default empty string.
 *     @type string $class         Extra CSS class to assign to the sidebar in the Widgets interface.
 *                                 Default empty.
 *     @type string $before_widget HTML content to prepend to each widget's HTML output when
 *                                 assigned to this sidebar. Default is an opening list item element.
 *     @type string $after_widget  HTML content to append to each widget's HTML output when
 *                                 assigned to this sidebar. Default is a closing list item element.
 *     @type string $before_title  HTML content to prepend to the sidebar title when displayed.
 *                                 Default is an opening h2 element.
 *     @type string $after_title   HTML content to append to the sidebar title when displayed.
 *                                 Default is a closing h2 element.
 * }
 * @return string Sidebar ID added to $wp_registered_sidebars global.
 */
function register_sidebar($args = array()) {
	global $wp_registered_sidebars;

	$i = count($wp_registered_sidebars) + 1;

	$id_is_empty = empty( $args['id'] );

	$defaults = array(
		'name' => sprintf(__('Sidebar %d'), $i ),
		'id' => "sidebar-$i",
		'description' => '',
		'class' => '',
		'before_widget' => '
  • ', 'after_widget' => "
  • ", 'before_title' => '

    ', 'after_title' => "

    ", ); $sidebar = wp_parse_args( $args, $defaults ); if ( $id_is_empty ) { /* translators: 1: the id argument, 2: sidebar name, 3: recommended id value */ _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.' ), 'id', $sidebar['name'], $sidebar['id'] ), '4.2.0' ); } $wp_registered_sidebars[$sidebar['id']] = $sidebar; add_theme_support('widgets'); /** * Fires once a sidebar has been registered. * * @since 3.0.0 * * @param array $sidebar Parsed arguments for the registered sidebar. */ do_action( 'register_sidebar', $sidebar ); return $sidebar['id']; }

    register_sidebar() 源文件

    相关