WP Widgets API – Adding Classes and Unique IDs

Categories: Blog, Development, WordPress
Tags: , , , , , ,

Apr 4
2011

As a widget developer you’ll soon realize, if you haven’t already, that not all WordPress themes are created equal. At times, styling your widget could mean a long and confusing combination of nested CSS selectors.

To make life easier on yourself, your users and for the sake of flexibility why not add a unique ID and/or class to the HTML output of your widget so it can be styled with ease. The best part is that it’s not only simple to do the WordPress Widgets API can help.

If you look at the widgets.php file in the wp-includes folder you’ll see that the WP_Widget class has the following property declarations:

var $id_base; // Root id for all widgets of this type.
var $name; // Name for this widget type.
var $widget_options; // Option array passed to wp_register_sidebar_widget()
var $control_options; // Option array passed to wp_register_widget_control()

var $number = false; // Unique ID number of the current instance.
var $id = false; // Unique ID string of the current instance (id_base-number)
var $updated = false; // Set true when we update the data after a POST submit - makes sure we don't do it twice.

Depending on your needs you could use the $id_base, $name, $number or $id to add a class or unique ID attribute value.

Example

Let’s assume that our widget outputs something simple like the following:

<div>
 <ul>
  <li>Item One</li>
  <li>Item Two</li>
  <li>Item Three</li>
  <li>Item Four</li>
 </ul>
</div>

If we assign a unique ID to the opening DIV tag styling the list would be a snap. Since this is a simple output and we should only need one unique ID let’s use the $id from the Widget class.

<?php
// Generate a unique ID
$unique_id = $this->id;

// Show the list
?>
<div id="<?php echo $unique_id; ?>">
 <ul>
  <li>Item One</li>
  <li>Item Two</li>
  <li>Item Three</li>
  <li>Item Four</li>
 </ul>
</div>
<?php // ... and our widget code continues ?>

It’s that simple.

If your $base_id for your widget is too long for your tastes – or you just don’t want to use it you can always generate the ID based on the $number, which is unique in each instance of of your widget.

<?php
// Generate a unique ID
$unique_id = 'my-widget-' . $this->number;

// Show the list
?>
<div id="<?php echo $unique_id; ?>">
 <ul>
  <li>Item One</li>
  <li>Item Two</li>
  <li>Item Three</li>
  <li>Item Four</li>
 </ul>
</div>
<?php // … and our widget code continues ?>

Classes work just the same. Assume for our example code that we want to use our widget in two areas on our site. However, in the first instance we want to alternate the background color for each list item. We want to do the same thing in the other instance of our widget but we want to use a different color.

<?php
// Generate a unique class
$unique_class = 'alt-' . $this->number;

// Show the list
?>
<ul>
 <li>Item One</li>
 <li class="<?php echo $unique_class; ?>">Item Two</li>
 <li>Item Three</li>
 <li class="<?php echo $unique_class; ?>">Item Four</li>
</ul>
<?php // … and our widget code continues ?>

Now we could easily and quickly style the background color for our alternate list items.

/* First Widget Instance */
.alt-1{ background-color: #cde; }

/* Second Widget Instance */
.alt-2{ background-color: #edd; }

Obviously these examples are trivial and if this was our actual output there would be easier methods to style the output using just one unique ID and/or one class name. The idea here is to show how to generate the unique IDs and classes so you can use them in more complex situations.

Quick Note

When using the $number or $id property of the WP_Widget class you should be aware that these are not generated when the widget is dropped into the widget area. You must click on the ‘Save’ button or reload the widget page.

 

Comments

Leave a comment

 
  • Jun 8, 2011
    @ 6:57AM

    Doddy says:

    $this->number;

    return: __i__

    Any idea?

     
  • Jun 8, 2011
    @ 12:48PM

    Dan says:

    If the widget is returning __i__ it’s most likely because you simply dragged your widget into the widget area and then checked the output. Try clicking the ‘Save’ button on the widget. Or reload the admin widgets page.

    Let me know if that works for you or not.

     
  • Leave a comment

    Read comments

     



    Please do not submit your comment more than once. It will appear once it has been approved.