API tools faq
paste
grysom

Untitled

grysom
Apr 25th, 2011
56
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 38.06 KB | None | 0 0
raw download clone embed print report
  1. <?php
  2. /**
  3. * API for creating dynamic sidebar without hardcoding functionality into
  4. * themes. Includes both internal WordPress routines and theme use routines.
  5. *
  6. * This functionality was found in a plugin before WordPress 2.2 release which
  7. * included it in the core from that point on.
  8. *
  9. * @link http://codex.wordpress.org/Plugins/WordPress_Widgets WordPress Widgets
  10. * @link http://codex.wordpress.org/Plugins/WordPress_Widgets_Api Widgets API
  11. *
  12. * @package WordPress
  13. * @subpackage Widgets
  14. */
  15.  
  16. /**
  17. * This class must be extended for each widget and WP_Widget::widget(), WP_Widget::update()
  18. * and WP_Widget::form() need to be over-ridden.
  19. *
  20. * @package WordPress
  21. * @subpackage Widgets
  22. * @since 2.8
  23. */
  24. class WP_Widget {
  25.  
  26. var $id_base; // Root id for all widgets of this type.
  27. var $name; // Name for this widget type.
  28. var $widget_options; // Option array passed to wp_register_sidebar_widget()
  29. var $control_options; // Option array passed to wp_register_widget_control()
  30.  
  31. var $number = false; // Unique ID number of the current instance.
  32. var $id = false; // Unique ID string of the current instance (id_base-number)
  33. var $updated = false; // Set true when we update the data after a POST submit - makes sure we don't do it twice.
  34.  
  35. // Member functions that you must over-ride.
  36.  
  37. /** Echo the widget content.
  38. *
  39. * Subclasses should over-ride this function to generate their widget code.
  40. *
  41. * @param array $args Display arguments including before_title, after_title, before_widget, and after_widget.
  42. * @param array $instance The settings for the particular instance of the widget
  43. */
  44. function widget($args, $instance) {
  45. die('function WP_Widget::widget() must be over-ridden in a sub-class.');
  46. }
  47.  
  48. /** Update a particular instance.
  49. *
  50. * This function should check that $new_instance is set correctly.
  51. * The newly calculated value of $instance should be returned.
  52. * If "false" is returned, the instance won't be saved/updated.
  53. *
  54. * @param array $new_instance New settings for this instance as input by the user via form()
  55. * @param array $old_instance Old settings for this instance
  56. * @return array Settings to save or bool false to cancel saving
  57. */
  58. function update($new_instance, $old_instance) {
  59. return $new_instance;
  60. }
  61.  
  62. /** Echo the settings update form
  63. *
  64. * @param array $instance Current settings
  65. */
  66. function form($instance) {
  67. echo '<p class="no-options-widget">' . __('There are no options for this widget.') . '</p>';
  68. return 'noform';
  69. }
  70.  
  71. // Functions you'll need to call.
  72.  
  73. /**
  74. * PHP4 constructor
  75. */
  76. function WP_Widget( $id_base = false, $name, $widget_options = array(), $control_options = array() ) {
  77. $this->__construct( $id_base, $name, $widget_options, $control_options );
  78. }
  79.  
  80. /**
  81. * PHP5 constructor
  82. *
  83. * @param string $id_base Optional Base ID for the widget, lower case,
  84. * if left empty a portion of the widget's class name will be used. Has to be unique.
  85. * @param string $name Name for the widget displayed on the configuration page.
  86. * @param array $widget_options Optional Passed to wp_register_sidebar_widget()
  87. * - description: shown on the configuration page
  88. * - classname
  89. * @param array $control_options Optional Passed to wp_register_widget_control()
  90. * - width: required if more than 250px
  91. * - height: currently not used but may be needed in the future
  92. */
  93. function __construct( $id_base = false, $name, $widget_options = array(), $control_options = array() ) {
  94. $this->id_base = empty($id_base) ? preg_replace( '/(wp_)?widget_/', '', strtolower(get_class($this)) ) : strtolower($id_base);
  95. $this->name = $name;
  96. $this->option_name = 'widget_' . $this->id_base;
  97. $this->widget_options = wp_parse_args( $widget_options, array('classname' => $this->option_name) );
  98. $this->control_options = wp_parse_args( $control_options, array('id_base' => $this->id_base) );
  99. }
  100.  
  101. /**
  102. * Constructs name attributes for use in form() fields
  103. *
  104. * This function should be used in form() methods to create name attributes for fields to be saved by update()
  105. *
  106. * @param string $field_name Field name
  107. * @return string Name attribute for $field_name
  108. */
  109. function get_field_name($field_name) {
  110. return 'widget-' . $this->id_base . '[' . $this->number . '][' . $field_name . ']';
  111. }
  112.  
  113. /**
  114. * Constructs id attributes for use in form() fields
  115. *
  116. * This function should be used in form() methods to create id attributes for fields to be saved by update()
  117. *
  118. * @param string $field_name Field name
  119. * @return string ID attribute for $field_name
  120. */
  121. function get_field_id($field_name) {
  122. return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
  123. }
  124.  
  125. // Private Functions. Don't worry about these.
  126.  
  127. function _register() {
  128. $settings = $this->get_settings();
  129. $empty = true;
  130.  
  131. if ( is_array($settings) ) {
  132. foreach ( array_keys($settings) as $number ) {
  133. if ( is_numeric($number) ) {
  134. $this->_set($number);
  135. $this->_register_one($number);
  136. $empty = false;
  137. }
  138. }
  139. }
  140.  
  141. if ( $empty ) {
  142. // If there are none, we register the widget's existance with a
  143. // generic template
  144. $this->_set(1);
  145. $this->_register_one();
  146. }
  147. }
  148.  
  149. function _set($number) {
  150. $this->number = $number;
  151. $this->id = $this->id_base . '-' . $number;
  152. }
  153.  
  154. function _get_display_callback() {
  155. return array(&$this, 'display_callback');
  156. }
  157.  
  158. function _get_update_callback() {
  159. return array(&$this, 'update_callback');
  160. }
  161.  
  162. function _get_form_callback() {
  163. return array(&$this, 'form_callback');
  164. }
  165.  
  166. /** Generate the actual widget content.
  167. * Just finds the instance and calls widget().
  168. * Do NOT over-ride this function. */
  169. function display_callback( $args, $widget_args = 1 ) {
  170. if ( is_numeric($widget_args) )
  171. $widget_args = array( 'number' => $widget_args );
  172.  
  173. $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
  174. $this->_set( $widget_args['number'] );
  175. $instance = $this->get_settings();
  176.  
  177. if ( array_key_exists( $this->number, $instance ) ) {
  178. $instance = $instance[$this->number];
  179. // filters the widget's settings, return false to stop displaying the widget
  180. $instance = apply_filters('widget_display_callback', $instance, $this, $args);
  181. if ( false !== $instance )
  182. $this->widget($args, $instance);
  183. }
  184. }
  185.  
  186. /** Deal with changed settings.
  187. * Do NOT over-ride this function. */
  188. function update_callback( $widget_args = 1 ) {
  189. global $wp_registered_widgets;
  190.  
  191. if ( is_numeric($widget_args) )
  192. $widget_args = array( 'number' => $widget_args );
  193.  
  194. $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
  195. $all_instances = $this->get_settings();
  196.  
  197. // We need to update the data
  198. if ( $this->updated )
  199. return;
  200.  
  201. $sidebars_widgets = wp_get_sidebars_widgets();
  202.  
  203. if ( isset($_POST['delete_widget']) && $_POST['delete_widget'] ) {
  204. // Delete the settings for this instance of the widget
  205. if ( isset($_POST['the-widget-id']) )
  206. $del_id = $_POST['the-widget-id'];
  207. else
  208. return;
  209.  
  210. if ( isset($wp_registered_widgets[$del_id]['params'][0]['number']) ) {
  211. $number = $wp_registered_widgets[$del_id]['params'][0]['number'];
  212.  
  213. if ( $this->id_base . '-' . $number == $del_id )
  214. unset($all_instances[$number]);
  215. }
  216. } else {
  217. if ( isset($_POST['widget-' . $this->id_base]) && is_array($_POST['widget-' . $this->id_base]) ) {
  218. $settings = $_POST['widget-' . $this->id_base];
  219. } elseif ( isset($_POST['id_base']) && $_POST['id_base'] == $this->id_base ) {
  220. $num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widget_number'];
  221. $settings = array( $num => array() );
  222. } else {
  223. return;
  224. }
  225.  
  226. foreach ( $settings as $number => $new_instance ) {
  227. $new_instance = stripslashes_deep($new_instance);
  228. $this->_set($number);
  229.  
  230. $old_instance = isset($all_instances[$number]) ? $all_instances[$number] : array();
  231.  
  232. $instance = $this->update($new_instance, $old_instance);
  233.  
  234. // filters the widget's settings before saving, return false to cancel saving (keep the old settings if updating)
  235. $instance = apply_filters('widget_update_callback', $instance, $new_instance, $old_instance, $this);
  236. if ( false !== $instance )
  237. $all_instances[$number] = $instance;
  238.  
  239. break; // run only once
  240. }
  241. }
  242.  
  243. $this->save_settings($all_instances);
  244. $this->updated = true;
  245. }
  246.  
  247. /** Generate the control form.
  248. * Do NOT over-ride this function. */
  249. function form_callback( $widget_args = 1 ) {
  250. if ( is_numeric($widget_args) )
  251. $widget_args = array( 'number' => $widget_args );
  252.  
  253. $widget_args = wp_parse_args( $widget_args, array( 'number' => -1 ) );
  254. $all_instances = $this->get_settings();
  255.  
  256. if ( -1 == $widget_args['number'] ) {
  257. // We echo out a form where 'number' can be set later
  258. $this->_set('__i__');
  259. $instance = array();
  260. } else {
  261. $this->_set($widget_args['number']);
  262. $instance = $all_instances[ $widget_args['number'] ];
  263. }
  264.  
  265. // filters the widget admin form before displaying, return false to stop displaying it
  266. $instance = apply_filters('widget_form_callback', $instance, $this);
  267.  
  268. $return = null;
  269. if ( false !== $instance ) {
  270. $return = $this->form($instance);
  271. // add extra fields in the widget form - be sure to set $return to null if you add any
  272. // if the widget has no form the text echoed from the default form method can be hidden using css
  273. do_action_ref_array( 'in_widget_form', array(&$this, &$return, $instance) );
  274. }
  275. return $return;
  276. }
  277.  
  278. /** Helper function: Registers a single instance. */
  279. function _register_one($number = -1) {
  280. wp_register_sidebar_widget( $this->id, $this->name, $this->_get_display_callback(), $this->widget_options, array( 'number' => $number ) );
  281. _register_widget_update_callback( $this->id_base, $this->_get_update_callback(), $this->control_options, array( 'number' => -1 ) );
  282. _register_widget_form_callback( $this->id, $this->name, $this->_get_form_callback(), $this->control_options, array( 'number' => $number ) );
  283. }
  284.  
  285. function save_settings($settings) {
  286. $settings['_multiwidget'] = 1;
  287. update_option( $this->option_name, $settings );
  288. }
  289.  
  290. function get_settings() {
  291. $settings = get_option($this->option_name);
  292.  
  293. if ( false === $settings && isset($this->alt_option_name) )
  294. $settings = get_option($this->alt_option_name);
  295.  
  296. if ( !is_array($settings) )
  297. $settings = array();
  298.  
  299. if ( !array_key_exists('_multiwidget', $settings) ) {
  300. // old format, conver if single widget
  301. $settings = wp_convert_widget_settings($this->id_base, $this->option_name, $settings);
  302. }
  303.  
  304. unset($settings['_multiwidget'], $settings['__i__']);
  305. return $settings;
  306. }
  307. }
  308.  
  309. /**
  310. * Singleton that registers and instantiates WP_Widget classes.
  311. *
  312. * @package WordPress
  313. * @subpackage Widgets
  314. * @since 2.8
  315. */
  316. class WP_Widget_Factory {
  317. var $widgets = array();
  318.  
  319. function WP_Widget_Factory() {
  320. add_action( 'widgets_init', array( &$this, '_register_widgets' ), 100 );
  321. }
  322.  
  323. function register($widget_class) {
  324. $this->widgets[$widget_class] = & new $widget_class();
  325. }
  326.  
  327. function unregister($widget_class) {
  328. if ( isset($this->widgets[$widget_class]) )
  329. unset($this->widgets[$widget_class]);
  330. }
  331.  
  332. function _register_widgets() {
  333. global $wp_registered_widgets;
  334. $keys = array_keys($this->widgets);
  335. $registered = array_keys($wp_registered_widgets);
  336. $registered = array_map('_get_widget_id_base', $registered);
  337.  
  338. foreach ( $keys as $key ) {
  339. // don't register new widget if old widget with the same id is already registered
  340. if ( in_array($this->widgets[$key]->id_base, $registered, true) ) {
  341. unset($this->widgets[$key]);
  342. continue;
  343. }
  344.  
  345. $this->widgets[$key]->_register();
  346. }
  347. }
  348. }
  349.  
  350. /* Global Variables */
  351.  
  352. /** @ignore */
  353. global $wp_registered_sidebars, $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates;
  354.  
  355. /**
  356. * Stores the sidebars, since many themes can have more than one.
  357. *
  358. * @global array $wp_registered_sidebars
  359. * @since 2.2.0
  360. */
  361. $wp_registered_sidebars = array();
  362.  
  363. /**
  364. * Stores the registered widgets.
  365. *
  366. * @global array $wp_registered_widgets
  367. * @since 2.2.0
  368. */
  369. $wp_registered_widgets = array();
  370.  
  371. /**
  372. * Stores the registered widget control (options).
  373. *
  374. * @global array $wp_registered_widget_controls
  375. * @since 2.2.0
  376. */
  377. $wp_registered_widget_controls = array();
  378. $wp_registered_widget_updates = array();
  379.  
  380. /**
  381. * Private
  382. */
  383. $_wp_sidebars_widgets = array();
  384.  
  385. /**
  386. * Private
  387. */
  388. $_wp_deprecated_widgets_callbacks = array(
  389. 'wp_widget_pages',
  390. 'wp_widget_pages_control',
  391. 'wp_widget_calendar',
  392. 'wp_widget_calendar_control',
  393. 'wp_widget_archives',
  394. 'wp_widget_archives_control',
  395. 'wp_widget_links',
  396. 'wp_widget_meta',
  397. 'wp_widget_meta_control',
  398. 'wp_widget_search',
  399. 'wp_widget_recent_entries',
  400. 'wp_widget_recent_entries_control',
  401. 'wp_widget_tag_cloud',
  402. 'wp_widget_tag_cloud_control',
  403. 'wp_widget_categories',
  404. 'wp_widget_categories_control',
  405. 'wp_widget_text',
  406. 'wp_widget_text_control',
  407. 'wp_widget_rss',
  408. 'wp_widget_rss_control',
  409. 'wp_widget_recent_comments',
  410. 'wp_widget_recent_comments_control'
  411. );
  412.  
  413. /* Template tags & API functions */
  414.  
  415. /**
  416. * Register a widget
  417. *
  418. * Registers a WP_Widget widget
  419. *
  420. * @since 2.8.0
  421. *
  422. * @see WP_Widget
  423. * @see WP_Widget_Factory
  424. * @uses WP_Widget_Factory
  425. *
  426. * @param string $widget_class The name of a class that extends WP_Widget
  427. */
  428. function register_widget($widget_class) {
  429. global $wp_widget_factory;
  430.  
  431. $wp_widget_factory->register($widget_class);
  432. }
  433.  
  434. /**
  435. * Unregister a widget
  436. *
  437. * Unregisters a WP_Widget widget. Useful for unregistering default widgets.
  438. * Run within a function hooked to the widgets_init action.
  439. *
  440. * @since 2.8.0
  441. *
  442. * @see WP_Widget
  443. * @see WP_Widget_Factory
  444. * @uses WP_Widget_Factory
  445. *
  446. * @param string $widget_class The name of a class that extends WP_Widget
  447. */
  448. function unregister_widget($widget_class) {
  449. global $wp_widget_factory;
  450.  
  451. $wp_widget_factory->unregister($widget_class);
  452. }
  453.  
  454. /**
  455. * Creates multiple sidebars.
  456. *
  457. * If you wanted to quickly create multiple sidebars for a theme or internally.
  458. * This function will allow you to do so. If you don't pass the 'name' and/or
  459. * 'id' in $args, then they will be built for you.
  460. *
  461. * The default for the name is "Sidebar #", with '#' being replaced with the
  462. * number the sidebar is currently when greater than one. If first sidebar, the
  463. * name will be just "Sidebar". The default for id is "sidebar-" followed by the
  464. * number the sidebar creation is currently at. If the id is provided, and mutliple
  465. * sidebars are being defined, the id will have "-2" appended, and so on.
  466. *
  467. * @since 2.2.0
  468. *
  469. * @see register_sidebar() The second parameter is documented by register_sidebar() and is the same here.
  470. * @uses parse_str() Converts a string to an array to be used in the rest of the function.
  471. * @uses register_sidebar() Sends single sidebar information [name, id] to this
  472. * function to handle building the sidebar.
  473. *
  474. * @param int $number Number of sidebars to create.
  475. * @param string|array $args Builds Sidebar based off of 'name' and 'id' values.
  476. */
  477. function register_sidebars($number = 1, $args = array()) {
  478. global $wp_registered_sidebars;
  479. $number = (int) $number;
  480.  
  481. if ( is_string($args) )
  482. parse_str($args, $args);
  483.  
  484. for ( $i = 1; $i <= $number; $i++ ) {
  485. $_args = $args;
  486.  
  487. if ( $number > 1 )
  488. $_args['name'] = isset($args['name']) ? sprintf($args['name'], $i) : sprintf(__('Sidebar %d'), $i);
  489. else
  490. $_args['name'] = isset($args['name']) ? $args['name'] : __('Sidebar');
  491.  
  492. // Custom specified ID's are suffixed if they exist already.
  493. // Automatically generated sidebar names need to be suffixed regardless starting at -0
  494. if ( isset($args['id']) ) {
  495. $_args['id'] = $args['id'];
  496. $n = 2; // Start at -2 for conflicting custom ID's
  497. while ( isset($wp_registered_sidebars[$_args['id']]) )
  498. $_args['id'] = $args['id'] . '-' . $n++;
  499. } else {
  500. $n = count($wp_registered_sidebars);
  501. do {
  502. $_args['id'] = 'sidebar-' . ++$n;
  503. } while ( isset($wp_registered_sidebars[$_args['id']]) );
  504. }
  505. register_sidebar($_args);
  506. }
  507. }
  508.  
  509. /**
  510. * Builds the definition for a single sidebar and returns the ID.
  511. *
  512. * The $args parameter takes either a string or an array with 'name' and 'id'
  513. * contained in either usage. It will be noted that the values will be applied
  514. * to all sidebars, so if creating more than one, it will be advised to allow
  515. * for WordPress to create the defaults for you.
  516. *
  517. * Example for string would be <code>'name=whatever;id=whatever1'</code> and for
  518. * the array it would be <code>array(
  519. * 'name' => 'whatever',
  520. * 'id' => 'whatever1')</code>.
  521. *
  522. * name - The name of the sidebar, which presumably the title which will be
  523. * displayed.
  524. * id - The unique identifier by which the sidebar will be called by.
  525. * before_widget - The content that will prepended to the widgets when they are
  526. * displayed.
  527. * after_widget - The content that will be appended to the widgets when they are
  528. * displayed.
  529. * before_title - The content that will be prepended to the title when displayed.
  530. * after_title - the content that will be appended to the title when displayed.
  531. *
  532. * <em>Content</em> is assumed to be HTML and should be formatted as such, but
  533. * doesn't have to be.
  534. *
  535. * @since 2.2.0
  536. * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
  537. *
  538. * @param string|array $args Builds Sidebar based off of 'name' and 'id' values
  539. * @return string The sidebar id that was added.
  540. */
  541. function register_sidebar($args = array()) {
  542. global $wp_registered_sidebars;
  543.  
  544. $i = count($wp_registered_sidebars) + 1;
  545.  
  546. $defaults = array(
  547. 'name' => sprintf(__('Sidebar %d'), $i ),
  548. 'id' => "sidebar-$i",
  549. 'description' => '',
  550. 'before_widget' => '<li id="%1$s" class="widget %2$s">',
  551. 'after_widget' => "</li>\n",
  552. 'before_title' => '<h2 class="widgettitle">',
  553. 'after_title' => "</h2>\n",
  554. );
  555.  
  556. $sidebar = wp_parse_args( $args, $defaults );
  557.  
  558. $wp_registered_sidebars[$sidebar['id']] = $sidebar;
  559.  
  560. add_theme_support('widgets');
  561.  
  562. do_action( 'register_sidebar', $sidebar );
  563.  
  564. return $sidebar['id'];
  565. }
  566.  
  567. /**
  568. * Removes a sidebar from the list.
  569. *
  570. * @since 2.2.0
  571. *
  572. * @uses $wp_registered_sidebars Stores the new sidebar in this array by sidebar ID.
  573. *
  574. * @param string $name The ID of the sidebar when it was added.
  575. */
  576. function unregister_sidebar( $name ) {
  577. global $wp_registered_sidebars;
  578.  
  579. if ( isset( $wp_registered_sidebars[$name] ) )
  580. unset( $wp_registered_sidebars[$name] );
  581. }
  582.  
  583. /**
  584. * Register widget for use in sidebars.
  585. *
  586. * The default widget option is 'classname' that can be override.
  587. *
  588. * The function can also be used to unregister widgets when $output_callback
  589. * parameter is an empty string.
  590. *
  591. * @since 2.2.0
  592. *
  593. * @uses $wp_registered_widgets Uses stored registered widgets.
  594. * @uses $wp_register_widget_defaults Retrieves widget defaults.
  595. *
  596. * @param int|string $id Widget ID.
  597. * @param string $name Widget display title.
  598. * @param callback $output_callback Run when widget is called.
  599. * @param array|string Optional. $options Widget Options.
  600. * @param mixed $params,... Widget parameters to add to widget.
  601. * @return null Will return if $output_callback is empty after removing widget.
  602. */
  603. function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) {
  604. global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;
  605.  
  606. $id = strtolower($id);
  607.  
  608. if ( empty($output_callback) ) {
  609. unset($wp_registered_widgets[$id]);
  610. return;
  611. }
  612.  
  613. $id_base = _get_widget_id_base($id);
  614. if ( in_array($output_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($output_callback) ) {
  615. if ( isset($wp_registered_widget_controls[$id]) )
  616. unset($wp_registered_widget_controls[$id]);
  617.  
  618. if ( isset($wp_registered_widget_updates[$id_base]) )
  619. unset($wp_registered_widget_updates[$id_base]);
  620.  
  621. return;
  622. }
  623.  
  624. $defaults = array('classname' => $output_callback);
  625. $options = wp_parse_args($options, $defaults);
  626. $widget = array(
  627. 'name' => $name,
  628. 'id' => $id,
  629. 'callback' => $output_callback,
  630. 'params' => array_slice(func_get_args(), 4)
  631. );
  632. $widget = array_merge($widget, $options);
  633.  
  634. if ( is_callable($output_callback) && ( !isset($wp_registered_widgets[$id]) || did_action( 'widgets_init' ) ) ) {
  635. do_action( 'wp_register_sidebar_widget', $widget );
  636. $wp_registered_widgets[$id] = $widget;
  637. }
  638. }
  639.  
  640. /**
  641. * Retrieve description for widget.
  642. *
  643. * When registering widgets, the options can also include 'description' that
  644. * describes the widget for display on the widget administration panel or
  645. * in the theme.
  646. *
  647. * @since 2.5.0
  648. *
  649. * @param int|string $id Widget ID.
  650. * @return string Widget description, if available. Null on failure to retrieve description.
  651. */
  652. function wp_widget_description( $id ) {
  653. if ( !is_scalar($id) )
  654. return;
  655.  
  656. global $wp_registered_widgets;
  657.  
  658. if ( isset($wp_registered_widgets[$id]['description']) )
  659. return esc_html( $wp_registered_widgets[$id]['description'] );
  660. }
  661.  
  662. /**
  663. * Retrieve description for a sidebar.
  664. *
  665. * When registering sidebars a 'description' parameter can be included that
  666. * describes the sidebar for display on the widget administration panel.
  667. *
  668. * @since 2.9.0
  669. *
  670. * @param int|string $id sidebar ID.
  671. * @return string Sidebar description, if available. Null on failure to retrieve description.
  672. */
  673. function wp_sidebar_description( $id ) {
  674. if ( !is_scalar($id) )
  675. return;
  676.  
  677. global $wp_registered_sidebars;
  678.  
  679. if ( isset($wp_registered_sidebars[$id]['description']) )
  680. return esc_html( $wp_registered_sidebars[$id]['description'] );
  681. }
  682.  
  683.  
  684. /**
  685. * Remove widget from sidebar.
  686. *
  687. * @since 2.2.0
  688. *
  689. * @param int|string $id Widget ID.
  690. */
  691. function wp_unregister_sidebar_widget($id) {
  692. do_action( 'wp_unregister_sidebar_widget', $id );
  693.  
  694. wp_register_sidebar_widget($id, '', '');
  695. wp_unregister_widget_control($id);
  696. }
  697.  
  698. /**
  699. * Registers widget control callback for customizing options.
  700. *
  701. * The options contains the 'height', 'width', and 'id_base' keys. The 'height'
  702. * option is never used. The 'width' option is the width of the fully expanded
  703. * control form, but try hard to use the default width. The 'id_base' is for
  704. * multi-widgets (widgets which allow multiple instances such as the text
  705. * widget), an id_base must be provided. The widget id will end up looking like
  706. * {$id_base}-{$unique_number}.
  707. *
  708. * @since 2.2.0
  709. *
  710. * @param int|string $id Sidebar ID.
  711. * @param string $name Sidebar display name.
  712. * @param callback $control_callback Run when sidebar is displayed.
  713. * @param array|string $options Optional. Widget options. See above long description.
  714. * @param mixed $params,... Optional. Additional parameters to add to widget.
  715. */
  716. function wp_register_widget_control($id, $name, $control_callback, $options = array()) {
  717. global $wp_registered_widget_controls, $wp_registered_widget_updates, $wp_registered_widgets, $_wp_deprecated_widgets_callbacks;
  718.  
  719. $id = strtolower($id);
  720. $id_base = _get_widget_id_base($id);
  721.  
  722. if ( empty($control_callback) ) {
  723. unset($wp_registered_widget_controls[$id]);
  724. unset($wp_registered_widget_updates[$id_base]);
  725. return;
  726. }
  727.  
  728. if ( in_array($control_callback, $_wp_deprecated_widgets_callbacks, true) && !is_callable($control_callback) ) {
  729. if ( isset($wp_registered_widgets[$id]) )
  730. unset($wp_registered_widgets[$id]);
  731.  
  732. return;
  733. }
  734.  
  735. if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )
  736. return;
  737.  
  738. $defaults = array('width' => 250, 'height' => 200 ); // height is never used
  739. $options = wp_parse_args($options, $defaults);
  740. $options['width'] = (int) $options['width'];
  741. $options['height'] = (int) $options['height'];
  742.  
  743. $widget = array(
  744. 'name' => $name,
  745. 'id' => $id,
  746. 'callback' => $control_callback,
  747. 'params' => array_slice(func_get_args(), 4)
  748. );
  749. $widget = array_merge($widget, $options);
  750.  
  751. $wp_registered_widget_controls[$id] = $widget;
  752.  
  753. if ( isset($wp_registered_widget_updates[$id_base]) )
  754. return;
  755.  
  756. if ( isset($widget['params'][0]['number']) )
  757. $widget['params'][0]['number'] = -1;
  758.  
  759. unset($widget['width'], $widget['height'], $widget['name'], $widget['id']);
  760. $wp_registered_widget_updates[$id_base] = $widget;
  761. }
  762.  
  763. function _register_widget_update_callback($id_base, $update_callback, $options = array()) {
  764. global $wp_registered_widget_updates;
  765.  
  766. if ( isset($wp_registered_widget_updates[$id_base]) ) {
  767. if ( empty($update_callback) )
  768. unset($wp_registered_widget_updates[$id_base]);
  769. return;
  770. }
  771.  
  772. $widget = array(
  773. 'callback' => $update_callback,
  774. 'params' => array_slice(func_get_args(), 3)
  775. );
  776.  
  777. $widget = array_merge($widget, $options);
  778. $wp_registered_widget_updates[$id_base] = $widget;
  779. }
  780.  
  781. function _register_widget_form_callback($id, $name, $form_callback, $options = array()) {
  782. global $wp_registered_widget_controls;
  783.  
  784. $id = strtolower($id);
  785.  
  786. if ( empty($form_callback) ) {
  787. unset($wp_registered_widget_controls[$id]);
  788. return;
  789. }
  790.  
  791. if ( isset($wp_registered_widget_controls[$id]) && !did_action( 'widgets_init' ) )
  792. return;
  793.  
  794. $defaults = array('width' => 250, 'height' => 200 );
  795. $options = wp_parse_args($options, $defaults);
  796. $options['width'] = (int) $options['width'];
  797. $options['height'] = (int) $options['height'];
  798.  
  799. $widget = array(
  800. 'name' => $name,
  801. 'id' => $id,
  802. 'callback' => $form_callback,
  803. 'params' => array_slice(func_get_args(), 4)
  804. );
  805. $widget = array_merge($widget, $options);
  806.  
  807. $wp_registered_widget_controls[$id] = $widget;
  808. }
  809.  
  810. /**
  811. * Remove control callback for widget.
  812. *
  813. * @since 2.2.0
  814. * @uses wp_register_widget_control() Unregisters by using empty callback.
  815. *
  816. * @param int|string $id Widget ID.
  817. */
  818. function wp_unregister_widget_control($id) {
  819. return wp_register_widget_control($id, '', '');
  820. }
  821.  
  822. /**
  823. * Display dynamic sidebar.
  824. *
  825. * By default it displays the default sidebar or 'sidebar-1'. The 'sidebar-1' is
  826. * not named by the theme, the actual name is '1', but 'sidebar-' is added to
  827. * the registered sidebars for the name. If you named your sidebar 'after-post',
  828. * then the parameter $index will still be 'after-post', but the lookup will be
  829. * for 'sidebar-after-post'.
  830. *
  831. * It is confusing for the $index parameter, but just know that it should just
  832. * work. When you register the sidebar in the theme, you will use the same name
  833. * for this function or "Pay no heed to the man behind the curtain." Just accept
  834. * it as an oddity of WordPress sidebar register and display.
  835. *
  836. * @since 2.2.0
  837. *
  838. * @param int|string $index Optional, default is 1. Name or ID of dynamic sidebar.
  839. * @return bool True, if widget sidebar was found and called. False if not found or not called.
  840. */
  841. function dynamic_sidebar($index = 1) {
  842. global $wp_registered_sidebars, $wp_registered_widgets;
  843.  
  844. if ( is_int($index) ) {
  845. $index = "sidebar-$index";
  846. } else {
  847. $index = sanitize_title($index);
  848. foreach ( (array) $wp_registered_sidebars as $key => $value ) {
  849. if ( sanitize_title($value['name']) == $index ) {
  850. $index = $key;
  851. break;
  852. }
  853. }
  854. }
  855.  
  856. $sidebars_widgets = wp_get_sidebars_widgets();
  857.  
  858. if ( empty($wp_registered_sidebars[$index]) || !array_key_exists($index, $sidebars_widgets) || !is_array($sidebars_widgets[$index]) || empty($sidebars_widgets[$index]) )
  859. return false;
  860.  
  861. $sidebar = $wp_registered_sidebars[$index];
  862.  
  863. $did_one = false;
  864. foreach ( (array) $sidebars_widgets[$index] as $id ) {
  865.  
  866. if ( !isset($wp_registered_widgets[$id]) ) continue;
  867.  
  868. $params = array_merge(
  869. array( array_merge( $sidebar, array('widget_id' => $id, 'widget_name' => $wp_registered_widgets[$id]['name']) ) ),
  870. (array) $wp_registered_widgets[$id]['params']
  871. );
  872.  
  873. // Substitute HTML id and class attributes into before_widget
  874. $classname_ = '';
  875. foreach ( (array) $wp_registered_widgets[$id]['classname'] as $cn ) {
  876. if ( is_string($cn) )
  877. $classname_ .= '_' . $cn;
  878. elseif ( is_object($cn) )
  879. $classname_ .= '_' . get_class($cn);
  880. }
  881. $classname_ = ltrim($classname_, '_');
  882. $params[0]['before_widget'] = sprintf($params[0]['before_widget'], $id, $classname_);
  883.  
  884. $params = apply_filters( 'dynamic_sidebar_params', $params );
  885.  
  886. $callback = $wp_registered_widgets[$id]['callback'];
  887.  
  888. do_action( 'dynamic_sidebar', $wp_registered_widgets[$id] );
  889.  
  890. if ( is_callable($callback) ) {
  891. call_user_func_array($callback, $params);
  892. $did_one = true;
  893. }
  894. }
  895.  
  896. return $did_one;
  897. }
  898.  
  899. /**
  900. * Whether widget is displayied on the front-end.
  901. *
  902. * Either $callback or $id_base can be used
  903. * $id_base is the first argument when extending WP_Widget class
  904. * Without the optional $widget_id parameter, returns the ID of the first sidebar
  905. * in which the first instance of the widget with the given callback or $id_base is found.
  906. * With the $widget_id parameter, returns the ID of the sidebar where
  907. * the widget with that callback/$id_base AND that ID is found.
  908. *
  909. * NOTE: $widget_id and $id_base are the same for single widgets. To be effective
  910. * this function has to run after widgets have initialized, at action 'init' or later.
  911. *
  912. * @since 2.2.0
  913. *
  914. * @param callback Optional, Widget callback to check.
  915. * @param int $widget_id Optional, but needed for checking. Widget ID.
  916. * @param string $id_base Optional, the base ID of a widget created by extending WP_Widget.
  917. * @param bool $skip_inactive Optional, whether to check in 'wp_inactive_widgets'.
  918. * @return mixed false if widget is not active or id of sidebar in which the widget is active.
  919. */
  920. function is_active_widget($callback = false, $widget_id = false, $id_base = false, $skip_inactive = true) {
  921. global $wp_registered_widgets;
  922.  
  923. $sidebars_widgets = wp_get_sidebars_widgets();
  924.  
  925. if ( is_array($sidebars_widgets) ) {
  926. foreach ( $sidebars_widgets as $sidebar => $widgets ) {
  927. if ( $skip_inactive && 'wp_inactive_widgets' == $sidebar )
  928. continue;
  929.  
  930. if ( is_array($widgets) ) {
  931. foreach ( $widgets as $widget ) {
  932. if ( ( $callback && isset($wp_registered_widgets[$widget]['callback']) && $wp_registered_widgets[$widget]['callback'] == $callback ) || ( $id_base && _get_widget_id_base($widget) == $id_base ) ) {
  933. if ( !$widget_id || $widget_id == $wp_registered_widgets[$widget]['id'] )
  934. return $sidebar;
  935. }
  936. }
  937. }
  938. }
  939. }
  940. return false;
  941. }
  942.  
  943. /**
  944. * Whether the dynamic sidebar is enabled and used by theme.
  945. *
  946. * @since 2.2.0
  947. *
  948. * @return bool True, if using widgets. False, if not using widgets.
  949. */
  950. function is_dynamic_sidebar() {
  951. global $wp_registered_widgets, $wp_registered_sidebars;
  952. $sidebars_widgets = get_option('sidebars_widgets');
  953. foreach ( (array) $wp_registered_sidebars as $index => $sidebar ) {
  954. if ( count($sidebars_widgets[$index]) ) {
  955. foreach ( (array) $sidebars_widgets[$index] as $widget )
  956. if ( array_key_exists($widget, $wp_registered_widgets) )
  957. return true;
  958. }
  959. }
  960. return false;
  961. }
  962.  
  963. /**
  964. * Whether a sidebar is in use.
  965. *
  966. * @since 2.8
  967. *
  968. * @param mixed $index, sidebar name, id or number to check.
  969. * @return bool true if the sidebar is in use, false otherwise.
  970. */
  971. function is_active_sidebar( $index ) {
  972. $index = ( is_int($index) ) ? "sidebar-$index" : sanitize_title($index);
  973. $sidebars_widgets = wp_get_sidebars_widgets();
  974. if ( !empty($sidebars_widgets[$index]) )
  975. return true;
  976.  
  977. return false;
  978. }
  979.  
  980. /* Internal Functions */
  981.  
  982. /**
  983. * Retrieve full list of sidebars and their widgets.
  984. *
  985. * Will upgrade sidebar widget list, if needed. Will also save updated list, if
  986. * needed.
  987. *
  988. * @since 2.2.0
  989. * @access private
  990. *
  991. * @param bool $deprecated. Not used.
  992. * @return array Upgraded list of widgets to version 3 array format when called from the admin.
  993. */
  994. function wp_get_sidebars_widgets($deprecated = true) {
  995. if ( $deprecated !== true )
  996. _deprecated_argument( __FUNCTION__, '2.8.1' );
  997.  
  998. global $wp_registered_widgets, $wp_registered_sidebars, $_wp_sidebars_widgets;
  999.  
  1000. // If loading from front page, consult $_wp_sidebars_widgets rather than options
  1001. // to see if wp_convert_widget_settings() has made manipulations in memory.
  1002. if ( !is_admin() ) {
  1003. if ( empty($_wp_sidebars_widgets) )
  1004. $_wp_sidebars_widgets = get_option('sidebars_widgets', array());
  1005.  
  1006. $sidebars_widgets = $_wp_sidebars_widgets;
  1007. } else {
  1008. $sidebars_widgets = get_option('sidebars_widgets', array());
  1009. $_sidebars_widgets = array();
  1010.  
  1011. if ( isset($sidebars_widgets['wp_inactive_widgets']) || empty($sidebars_widgets) )
  1012. $sidebars_widgets['array_version'] = 3;
  1013. elseif ( !isset($sidebars_widgets['array_version']) )
  1014. $sidebars_widgets['array_version'] = 1;
  1015.  
  1016. switch ( $sidebars_widgets['array_version'] ) {
  1017. case 1 :
  1018. foreach ( (array) $sidebars_widgets as $index => $sidebar )
  1019. if ( is_array($sidebar) )
  1020. foreach ( (array) $sidebar as $i => $name ) {
  1021. $id = strtolower($name);
  1022. if ( isset($wp_registered_widgets[$id]) ) {
  1023. $_sidebars_widgets[$index][$i] = $id;
  1024. continue;
  1025. }
  1026. $id = sanitize_title($name);
  1027. if ( isset($wp_registered_widgets[$id]) ) {
  1028. $_sidebars_widgets[$index][$i] = $id;
  1029. continue;
  1030. }
  1031.  
  1032. $found = false;
  1033.  
  1034. foreach ( $wp_registered_widgets as $widget_id => $widget ) {
  1035. if ( strtolower($widget['name']) == strtolower($name) ) {
  1036. $_sidebars_widgets[$index][$i] = $widget['id'];
  1037. $found = true;
  1038. break;
  1039. } elseif ( sanitize_title($widget['name']) == sanitize_title($name) ) {
  1040. $_sidebars_widgets[$index][$i] = $widget['id'];
  1041. $found = true;
  1042. break;
  1043. }
  1044. }
  1045.  
  1046. if ( $found )
  1047. continue;
  1048.  
  1049. unset($_sidebars_widgets[$index][$i]);
  1050. }
  1051. $_sidebars_widgets['array_version'] = 2;
  1052. $sidebars_widgets = $_sidebars_widgets;
  1053. unset($_sidebars_widgets);
  1054.  
  1055. case 2 :
  1056. $sidebars = array_keys( $wp_registered_sidebars );
  1057. if ( !empty( $sidebars ) ) {
  1058. // Move the known-good ones first
  1059. foreach ( (array) $sidebars as $id ) {
  1060. if ( array_key_exists( $id, $sidebars_widgets ) ) {
  1061. $_sidebars_widgets[$id] = $sidebars_widgets[$id];
  1062. unset($sidebars_widgets[$id], $sidebars[$id]);
  1063. }
  1064. }
  1065.  
  1066. // move the rest to wp_inactive_widgets
  1067. if ( !isset($_sidebars_widgets['wp_inactive_widgets']) )
  1068. $_sidebars_widgets['wp_inactive_widgets'] = array();
  1069.  
  1070. if ( !empty($sidebars_widgets) ) {
  1071. foreach ( $sidebars_widgets as $lost => $val ) {
  1072. if ( is_array($val) )
  1073. $_sidebars_widgets['wp_inactive_widgets'] = array_merge( (array) $_sidebars_widgets['wp_inactive_widgets'], $val );
  1074. }
  1075. }
  1076.  
  1077. $sidebars_widgets = $_sidebars_widgets;
  1078. unset($_sidebars_widgets);
  1079. }
  1080. }
  1081. }
  1082.  
  1083. if ( is_array( $sidebars_widgets ) && isset($sidebars_widgets['array_version']) )
  1084. unset($sidebars_widgets['array_version']);
  1085.  
  1086. $sidebars_widgets = apply_filters('sidebars_widgets', $sidebars_widgets);
  1087. return $sidebars_widgets;
  1088. }
  1089.  
  1090. /**
  1091. * Set the sidebar widget option to update sidebars.
  1092. *
  1093. * @since 2.2.0
  1094. * @access private
  1095. *
  1096. * @param array $sidebars_widgets Sidebar widgets and their settings.
  1097. */
  1098. function wp_set_sidebars_widgets( $sidebars_widgets ) {
  1099. if ( !isset( $sidebars_widgets['array_version'] ) )
  1100. $sidebars_widgets['array_version'] = 3;
  1101. update_option( 'sidebars_widgets', $sidebars_widgets );
  1102. }
  1103.  
  1104. /**
  1105. * Retrieve default registered sidebars list.
  1106. *
  1107. * @since 2.2.0
  1108. * @access private
  1109. *
  1110. * @return array
  1111. */
  1112. function wp_get_widget_defaults() {
  1113. global $wp_registered_sidebars;
  1114.  
  1115. $defaults = array();
  1116.  
  1117. foreach ( (array) $wp_registered_sidebars as $index => $sidebar )
  1118. $defaults[$index] = array();
  1119.  
  1120. return $defaults;
  1121. }
  1122.  
  1123. /**
  1124. * Convert the widget settings from single to multi-widget format.
  1125. *
  1126. * @since 2.8.0
  1127. *
  1128. * @return array
  1129. */
  1130. function wp_convert_widget_settings($base_name, $option_name, $settings) {
  1131. // This test may need expanding.
  1132. $single = $changed = false;
  1133. if ( empty($settings) ) {
  1134. $single = true;
  1135. } else {
  1136. foreach ( array_keys($settings) as $number ) {
  1137. if ( 'number' == $number )
  1138. continue;
  1139. if ( !is_numeric($number) ) {
  1140. $single = true;
  1141. break;
  1142. }
  1143. }
  1144. }
  1145.  
  1146. if ( $single ) {
  1147. $settings = array( 2 => $settings );
  1148.  
  1149. // If loading from the front page, update sidebar in memory but don't save to options
  1150. if ( is_admin() ) {
  1151. $sidebars_widgets = get_option('sidebars_widgets');
  1152. } else {
  1153. if ( empty($GLOBALS['_wp_sidebars_widgets']) )
  1154. $GLOBALS['_wp_sidebars_widgets'] = get_option('sidebars_widgets', array());
  1155. $sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets'];
  1156. }
  1157.  
  1158. foreach ( (array) $sidebars_widgets as $index => $sidebar ) {
  1159. if ( is_array($sidebar) ) {
  1160. foreach ( $sidebar as $i => $name ) {
  1161. if ( $base_name == $name ) {
  1162. $sidebars_widgets[$index][$i] = "$name-2";
  1163. $changed = true;
  1164. break 2;
  1165. }
  1166. }
  1167. }
  1168. }
  1169.  
  1170. if ( is_admin() && $changed )
  1171. update_option('sidebars_widgets', $sidebars_widgets);
  1172. }
  1173.  
  1174. $settings['_multiwidget'] = 1;
  1175. if ( is_admin() )
  1176. update_option( $option_name, $settings );
  1177.  
  1178. return $settings;
  1179. }
  1180.  
  1181. /**
  1182. * Output an arbitrary widget as a template tag
  1183. *
  1184. * @since 2.8
  1185. *
  1186. * @param string $widget the widget's PHP class name (see default-widgets.php)
  1187. * @param array $instance the widget's instance settings
  1188. * @param array $args the widget's sidebar args
  1189. * @return void
  1190. **/
  1191. function the_widget($widget, $instance = array(), $args = array()) {
  1192. global $wp_widget_factory;
  1193.  
  1194. $widget_obj = $wp_widget_factory->widgets[$widget];
  1195. if ( !is_a($widget_obj, 'WP_Widget') )
  1196. return;
  1197.  
  1198. $before_widget = sprintf('<div class="widget %s">', $widget_obj->widget_options['classname']);
  1199. $default_args = array('before_widget' => $before_widget, 'after_widget' => "</div>", 'before_title' => '<h2 class="widgettitle">', 'after_title' => '</h2>');
  1200.  
  1201. $args = wp_parse_args($args, $default_args);
  1202. $instance = wp_parse_args($instance);
  1203.  
  1204. do_action( 'the_widget', $widget, $instance, $args );
  1205.  
  1206. $widget_obj->_set(-1);
  1207. $widget_obj->widget($args, $instance);
  1208. }
  1209.  
  1210. /**
  1211. * Private
  1212. */
  1213. function _get_widget_id_base($id) {
  1214. return preg_replace( '/-[0-9]+$/', '', $id );
  1215. }
Advertisement
Add Comment
Please, Sign In to add comment
Public Pastes
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!