mirror of
https://github.com/WordPress/WordPress.git
synced 2025-01-25 17:51:27 +01:00
phpdoc for widgets.php. Props jacobsantos. fixes #7661
git-svn-id: http://svn.automattic.com/wordpress/trunk@8960 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
parent
f528acb8df
commit
ab861693c4
@ -35,6 +35,7 @@ $wp_registered_sidebars = array();
|
|||||||
$wp_registered_widgets = array();
|
$wp_registered_widgets = array();
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* Stores the registered widget control (options).
|
||||||
*
|
*
|
||||||
* @global array $wp_registered_widget_controls
|
* @global array $wp_registered_widget_controls
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
@ -170,16 +171,22 @@ function unregister_sidebar( $name ) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Register widget for sidebar with backwards compatibility.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* Allows $name to be an array that accepts either three elements to grab the
|
||||||
|
* first element and the third for the name or just uses the first element of
|
||||||
|
* the array for the name.
|
||||||
|
*
|
||||||
|
* Passes to {@link wp_register_sidebar_widget()} after argument list and
|
||||||
|
* backwards compatibility is complete.
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
* @uses wp_register_sidebar_widget() Passes the compiled arguments.
|
* @uses wp_register_sidebar_widget() Passes the compiled arguments.
|
||||||
*
|
*
|
||||||
* @param string $name
|
* @param string|int $name Widget ID.
|
||||||
* @param callback $output_callback
|
* @param callback $output_callback Run when widget is called.
|
||||||
* @param string $classname
|
* @param string $classname Classname widget option.
|
||||||
|
* @param mixed $params,... Widget parameters.
|
||||||
*/
|
*/
|
||||||
function register_sidebar_widget($name, $output_callback, $classname = '') {
|
function register_sidebar_widget($name, $output_callback, $classname = '') {
|
||||||
// Compat
|
// Compat
|
||||||
@ -203,20 +210,24 @@ function register_sidebar_widget($name, $output_callback, $classname = '') {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Register widget for use in sidebars.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* The default widget option is 'classname' that can be override.
|
||||||
|
*
|
||||||
|
* The function can also be used to unregister widgets when $output_callback
|
||||||
|
* parameter is an empty string.
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @uses $wp_registered_widgets {@internal Missing Description}}
|
* @uses $wp_registered_widgets Uses stored registered widgets.
|
||||||
* @uses $wp_register_widget_defaults {@internal Missing Description}}
|
* @uses $wp_register_widget_defaults Retrieves widget defaults.
|
||||||
*
|
*
|
||||||
* @param int $id {@internal Missing Description}}
|
* @param int|string $id Widget ID.
|
||||||
* @param string $name {@internal Missing Description}}
|
* @param string $name Widget display title.
|
||||||
* @param callback $output_callback {@internal Missing Description}}
|
* @param callback $output_callback Run when widget is called.
|
||||||
* @param array|string $options {@internal Missing Description}}
|
* @param array|string Optional. $options Widget Options.
|
||||||
* @return null Will return if $output_callback is empty
|
* @param mixed $params,... Widget parameters to add to widget.
|
||||||
|
* @return null Will return if $output_callback is empty after removing widget.
|
||||||
*/
|
*/
|
||||||
function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {
|
function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {
|
||||||
global $wp_registered_widgets;
|
global $wp_registered_widgets;
|
||||||
@ -243,14 +254,16 @@ function wp_register_sidebar_widget($id, $name, $output_callback, $options = arr
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Retrieve description for widget.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* When registering widgets, the options can also include 'description' that
|
||||||
|
* describes the widget for display on the widget administration panel or
|
||||||
|
* in the theme.
|
||||||
*
|
*
|
||||||
* @since 2.5.0
|
* @since 2.5.0
|
||||||
*
|
*
|
||||||
* @param unknown_type $id
|
* @param int|string $id Widget ID.
|
||||||
* @return unknown
|
* @return string Widget description, if available. Null on failure to retrieve description.
|
||||||
*/
|
*/
|
||||||
function wp_widget_description( $id ) {
|
function wp_widget_description( $id ) {
|
||||||
if ( !is_scalar($id) )
|
if ( !is_scalar($id) )
|
||||||
@ -269,20 +282,18 @@ function wp_widget_description( $id ) {
|
|||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @param int $id Same as wp_unregister_sidebar_widget()
|
* @param int|string $id Widget ID.
|
||||||
*/
|
*/
|
||||||
function unregister_sidebar_widget($id) {
|
function unregister_sidebar_widget($id) {
|
||||||
return wp_unregister_sidebar_widget($id);
|
return wp_unregister_sidebar_widget($id);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Remove widget from sidebar.
|
||||||
*
|
|
||||||
* {@internal Missing Long Description}}
|
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @param int $id {@internal Missing Description}}
|
* @param int|string $id Widget ID.
|
||||||
*/
|
*/
|
||||||
function wp_unregister_sidebar_widget($id) {
|
function wp_unregister_sidebar_widget($id) {
|
||||||
wp_register_sidebar_widget($id, '', '');
|
wp_register_sidebar_widget($id, '', '');
|
||||||
@ -290,16 +301,21 @@ function wp_unregister_sidebar_widget($id) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Registers widget control callback for customizing options.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* Allows $name to be an array that accepts either three elements to grab the
|
||||||
|
* first element and the third for the name or just uses the first element of
|
||||||
|
* the array for the name.
|
||||||
|
*
|
||||||
|
* Passes to {@link wp_register_widget_control()} after the argument list has
|
||||||
|
* been compiled.
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @param unknown_type $name {@internal Missing Description}}
|
* @param int|string $name Sidebar ID.
|
||||||
* @param unknown_type $control_callback {@internal Missing Description}}
|
* @param callback $control_callback Widget control callback to display and process form.
|
||||||
* @param unknown_type $width {@internal Missing Description}}
|
* @param int $width Widget width.
|
||||||
* @param unknown_type $height {@internal Missing Description}}
|
* @param int $height Widget height.
|
||||||
*/
|
*/
|
||||||
function register_widget_control($name, $control_callback, $width = '', $height = '') {
|
function register_widget_control($name, $control_callback, $width = '', $height = '') {
|
||||||
// Compat
|
// Compat
|
||||||
@ -324,23 +340,23 @@ function register_widget_control($name, $control_callback, $width = '', $height
|
|||||||
call_user_func_array('wp_register_widget_control', $args);
|
call_user_func_array('wp_register_widget_control', $args);
|
||||||
}
|
}
|
||||||
|
|
||||||
/* $options: height, width, id_base
|
|
||||||
* height: never used
|
|
||||||
* width: width of fully expanded control form. Try hard to use the default width.
|
|
||||||
* id_base: for multi-widgets (widgets which allow multiple instances such as the text widget), an id_base must be provided.
|
|
||||||
* the widget id will ennd up looking like {$id_base}-{$unique_number}
|
|
||||||
*/
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Registers widget control callback for customizing options.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* The options contains the 'height', 'width', and 'id_base' keys. The 'height'
|
||||||
|
* option is never used. The 'width' option is the width of the fully expanded
|
||||||
|
* control form, but try hard to use the default width. The 'id_base' is for
|
||||||
|
* multi-widgets (widgets which allow multiple instances such as the text
|
||||||
|
* widget), an id_base must be provided. The widget id will end up looking like
|
||||||
|
* {$id_base}-{$unique_number}.
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @param int $id {@internal Missing Description}}
|
* @param int|string $id Sidebar ID.
|
||||||
* @param string $name {@internal Missing Description}}
|
* @param string $name Sidebar display name.
|
||||||
* @param callback $control_callback {@internal Missing Description}}
|
* @param callback $control_callback Run when sidebar is displayed.
|
||||||
* @param array|string $options {@internal Missing Description}}
|
* @param array|string $options Optional. Widget options. See above long description.
|
||||||
|
* @param mixed $params,... Optional. Additional parameters to add to widget.
|
||||||
*/
|
*/
|
||||||
function wp_register_widget_control($id, $name, $control_callback, $options = array()) {
|
function wp_register_widget_control($id, $name, $control_callback, $options = array()) {
|
||||||
global $wp_registered_widget_controls;
|
global $wp_registered_widget_controls;
|
||||||
@ -377,35 +393,42 @@ function wp_register_widget_control($id, $name, $control_callback, $options = ar
|
|||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
* @see wp_unregister_widget_control()
|
* @see wp_unregister_widget_control()
|
||||||
*
|
*
|
||||||
* @param int $id Widget ID.
|
* @param int|string $id Widget ID.
|
||||||
*/
|
*/
|
||||||
function unregister_widget_control($id) {
|
function unregister_widget_control($id) {
|
||||||
return wp_unregister_widget_control($id);
|
return wp_unregister_widget_control($id);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Remove control callback for widget.
|
||||||
*
|
|
||||||
* {@internal Missing Long Description}}
|
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
* @uses wp_register_widget_control() {@internal Missing Description}}
|
* @uses wp_register_widget_control() Unregisters by using empty callback.
|
||||||
*
|
*
|
||||||
* @param int $id {@internal Missing Description}}
|
* @param int|string $id Widget ID.
|
||||||
*/
|
*/
|
||||||
function wp_unregister_widget_control($id) {
|
function wp_unregister_widget_control($id) {
|
||||||
return wp_register_widget_control($id, '', '');
|
return wp_register_widget_control($id, '', '');
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Display dynamic sidebar.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* By default it displays the default sidebar or 'sidebar-1'. The 'sidebar-1' is
|
||||||
|
* not named by the theme, the actual name is '1', but 'sidebar-' is added to
|
||||||
|
* the registered sidebars for the name. If you named your sidebar 'after-post',
|
||||||
|
* then the parameter $index will still be 'after-post', but the lookup will be
|
||||||
|
* for 'sidebar-after-post'.
|
||||||
|
*
|
||||||
|
* It is confusing for the $index parameter, but just know that it should just
|
||||||
|
* work. When you register the sidebar in the theme, you will use the same name
|
||||||
|
* for this function or "Pay no heed to the man behind the curtain." Just accept
|
||||||
|
* it as an oddity of WordPress sidebar register and display.
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @param unknown_type $index
|
* @param int|string $index Optional, default is 1. Name or ID of dynamic sidebar.
|
||||||
* @return unknown
|
* @return bool True, if widget sidebar was found and called. False if not found or not called.
|
||||||
*/
|
*/
|
||||||
function dynamic_sidebar($index = 1) {
|
function dynamic_sidebar($index = 1) {
|
||||||
global $wp_registered_sidebars, $wp_registered_widgets;
|
global $wp_registered_sidebars, $wp_registered_widgets;
|
||||||
@ -461,14 +484,17 @@ function dynamic_sidebar($index = 1) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Whether widget is registered using callback with widget ID.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* Will only check if both parameters are used. Used to find which sidebar the
|
||||||
|
* widget is located in, but requires that both the callback and the widget ID
|
||||||
|
* be known.
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @param unknown_type $callback
|
* @param callback $callback Widget callback to check.
|
||||||
/* @return mixed false if widget is not active or id of sidebar in which the widget is active
|
* @param int $widget_id Optional, but needed for checking. Widget ID.
|
||||||
|
/* @return mixed false if widget is not active or id of sidebar in which the widget is active.
|
||||||
*/
|
*/
|
||||||
function is_active_widget($callback, $widget_id = false) {
|
function is_active_widget($callback, $widget_id = false) {
|
||||||
global $wp_registered_widgets;
|
global $wp_registered_widgets;
|
||||||
@ -486,13 +512,11 @@ function is_active_widget($callback, $widget_id = false) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Whether the dynamic sidebar is enabled and used by theme.
|
||||||
*
|
|
||||||
* {@internal Missing Long Description}}
|
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
*
|
*
|
||||||
* @return unknown
|
* @return bool True, if using widgets. False, if not using widgets.
|
||||||
*/
|
*/
|
||||||
function is_dynamic_sidebar() {
|
function is_dynamic_sidebar() {
|
||||||
global $wp_registered_widgets, $wp_registered_sidebars;
|
global $wp_registered_widgets, $wp_registered_sidebars;
|
||||||
@ -510,15 +534,16 @@ function is_dynamic_sidebar() {
|
|||||||
/* Internal Functions */
|
/* Internal Functions */
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Retrieve full list of sidebars and their widgets.
|
||||||
*
|
*
|
||||||
* {@internal Missing Long Description}}
|
* Will upgrade sidebar widget list, if needed. Will also save updated list, if
|
||||||
|
* needed.
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
* @access private
|
* @access private
|
||||||
*
|
*
|
||||||
* @param unknown_type $update
|
* @param bool $update Optional, default is true. Whether to save upgrade of widget array list.
|
||||||
* @return unknown
|
* @return array Upgraded list of widgets to version 2 array format.
|
||||||
*/
|
*/
|
||||||
function wp_get_sidebars_widgets($update = true) {
|
function wp_get_sidebars_widgets($update = true) {
|
||||||
global $wp_registered_widgets, $wp_registered_sidebars;
|
global $wp_registered_widgets, $wp_registered_sidebars;
|
||||||
@ -599,29 +624,24 @@ function wp_get_sidebars_widgets($update = true) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Set the sidebar widget option to update sidebars.
|
||||||
*
|
|
||||||
* {@internal Missing Long Description}}
|
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
* @access private
|
* @access private
|
||||||
* @uses update_option()
|
|
||||||
*
|
*
|
||||||
* @param unknown_type $sidebars_widgets
|
* @param array $sidebars_widgets Sidebar widgets and their settings.
|
||||||
*/
|
*/
|
||||||
function wp_set_sidebars_widgets( $sidebars_widgets ) {
|
function wp_set_sidebars_widgets( $sidebars_widgets ) {
|
||||||
update_option( 'sidebars_widgets', $sidebars_widgets );
|
update_option( 'sidebars_widgets', $sidebars_widgets );
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@internal Missing Short Description}}
|
* Retrieve default registered sidebars list.
|
||||||
*
|
|
||||||
* {@internal Missing Long Description}}
|
|
||||||
*
|
*
|
||||||
* @since 2.2.0
|
* @since 2.2.0
|
||||||
* @access private
|
* @access private
|
||||||
*
|
*
|
||||||
* @return unknown
|
* @return array
|
||||||
*/
|
*/
|
||||||
function wp_get_widget_defaults() {
|
function wp_get_widget_defaults() {
|
||||||
global $wp_registered_sidebars;
|
global $wp_registered_sidebars;
|
||||||
|
Loading…
Reference in New Issue
Block a user