How do I use is_active_widget?

Question

This is the manual page: http://codex.wordpress.org/Function_Reference/is_active_widget

And this is the code: http://core.trac.wordpress.org/browser/tags/3.2.1/wp-includes/widgets.php

But I'm still struggling to understand how to use this function. Perhaps I am using it right, but something I can't think of is wrong. But more surely, I need to know what this means:

1) "callback" - I assumed this was the name of the Widget class. Am I right?

2) widget id, what is this?

3) id base, what is it?

4) "Whether to check in 'wp_inactive_widgets'." What is wp_inactive_widgets?

I really feel like the manual isn't explaining these things.

Here's something that I put together which does not work!

function cbs_register_widgets() {
    register_widget( 'cbs_map_widget' );
}

add_action( 'widgets_init', 'cbs_register_widgets' );

function cbs_enqueue_resources() {

    if ( is_active_widget( 'cbs_map_widget' ) ) {
        wp_enqueue_script( 'fancybox-js', plugins_url( '/fancybox/jquery.fancybox-1.3.4.pack.js', __FILE__), array( 'jquery' ), '1.3.4' );
        wp_enqueue_style( 'fancybox-css', plugins_url( '/fancybox/jquery.fancybox-1.3.4.js', __FILE__ ), '', '1.3.4' );
    }

    wp_enqueue_script( 'cbs-widgets-js', plugins_url( '/js/cbs-widgets.js', __FILE__ ), array( 'jquery' ) );
    wp_enqueue_style( 'cbs-widgets-css', plugins_url( '/css/style.css', __FILE__ ) );

}

add_action( 'template_redirect', 'cbs_enqueue_resources' );

The enqueueing in itself works, it is the is_active_widget that doesn't work. The widget itself works too, and displays correctly. Just the fancybox js that's missing....

Here's my implementation of one of the answers I got below, it does not work either:

class cbs_map_widget extends WP_Widget
{
    function cbs_map_widget()
    {
        $ops = array('classname' => 'cbs-map-widget', 'description' => 'Visar en karta över Chalmers område där lokaler som används av Sällskapet har markerats.');

        $this->WP_Widget('cbs-map-widget', 'CBS kartwidget', $ops);
    }

    function widget($args, $instance)
    {
        extract($args);

        echo $before_widget;

        echo '<div class="overline">text</div>';
        echo '<a href="#" class="cbs-map-widget"><img src="' . plugins_url( '/images/map.png', __FILE__ ) . '" title="" /></a>';

        echo $after_widget;

        add_action('wp_enqueue_scripts', array(&$this, 'js'));
    }

    function js()
    {
        if ( is_active_widget(false, false, $this->id_base, true) ) {
            wp_enqueue_script( 'fancybox-js', plugins_url( '/fancybox/jquery.fancybox-1.3.4.pack.js', __FILE__), array( 'jquery' ), '1.3.4' );
            wp_enqueue_style( 'fancybox-css', plugins_url( '/fancybox/jquery.fancybox-1.3.4.js', __FILE__ ), '', '1.3.4' );
        }
    }

}

Answer 1

You should make the check inside the widget class, unless you don't have a choice. The example in the codex is pretty much what you're looking for:

class cbs_map_widget extends WP_Widget{

  function cbs_map_widget(){
    $this->WP_Widget('cbsmaps', __('Widget Name'), array('classname' => 'cbsmaps', 'description' => __('whatever')));
    ...   
    add_action('wp_enqueue_scripts', array(&$this, 'js'));
  }

  function js(){

    if ( is_active_widget(false, false, $this->id_base, true) ) {
       // enqueue your scripts;
    }           

  }


  ...

}

The $widget_id parameter is useful when you need to include your scripts only for a specific widget instance. For example when you have two cbs_map_widget widgets and want to include custom javascript for each of them.

The $callback argument is useful when you need to do the check outside the widget class (like you did above), but try to avoid it if you can do your check inside the class.

The other arguments are pretty much self explanatory (id_base is basically a "widget class indentifier", and the $skip_inactive is whether to check inactive widgets as well - should be true because I don't think you want to do that)...

---

Edit: How to find the $widget_id (A widget instance ID)

Again, you don't need this unless you specifically want to check if a certain widget instance is active. Personally I use this method because I can access the instance options too:

 ...
 function js(){

    // we need to process all instances because this function gets to run only once
    $widget_settings = get_option($this->option_name);

    foreach((array)$widget_settings as $instance => $options){

      // identify instance
      $id = "{$this->id_base}-{$instance}";

      // check if it's our instance
      if(!is_active_widget(false, $id, $this->id_base)) continue; // not active

      // instance is active
      // access the widget instance options here, you may need them to do your checks
      if($options['yourwidgetoption']) {
         // do stuff 
      } 
    }

 }
 ...