Blog

Blog Updates

Add Built-in Widgets to Thesis / WordPress Theme

November 20, 2009 · 13 comments

Post image for Add Built-in Widgets to Thesis / WordPress Theme

Almost anything that can be done with a normal theme can, in almost the same way, be done with Thesis. The main custom functions file (custom_functions.php) is just an extension of Functions.php, the main function file for WordPress themes. So is it possible to add built in widgets with a Thesis skin or customization? Of course!

Note: For Thesis 1.5+ / WordPress 2.8.x

Double Note: If you came here looking how to build a widget into a non-thesis wordpress theme, almost the same tutorial applies. The only difference is you would contain everything in Functions.php.

In this example we’re going to build a simple rss/twitter widget, which will allow the user to input a twitter username and RSS link and have it show up wherever they place said widget.

To begin

First, open up custom_functions.php (found in your thesis install folder/custom). Anywhere after the code already in the file, paste the following:

class my_subscribe_widget extends WP_Widget {

	function my_subscribe_widget() {
		// Construct our widget
	}

	function widget($args, $instance) {
		// Our front end
	}

	function update($new_instance, $old_instance) {
		// Updates our widget
	}

	function form($instance) {
		// Our back end
	}
}

register_widget('my_subscribe_widget');

This is a widget function, bare-bones. Our class name is my_subscribe_widget, which is extending the WP_Widget class to allow us to use its functions and properties. We can now build upon our frame and create a widget that actually has some use.

<?php
class my_subscribe_widget extends WP_Widget {
 function my_subscribe_widget() {
 $widget_ops = array('classname' => 'widget_bu_subscribe', 'description' => 'Add an RSS and twitter link' );
 $this->WP_Widget('my_subscribe_widget', 'RSS/Twitter Links', $widget_ops);
 }

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

 echo $before_widget;
 $title = empty($instance['title']) ? '&nbsp;' : apply_filters('widget_title', $instance['title']);
 $rss_link = empty($instance['rss_link']) ? '&nbsp;' : apply_filters('widget_rss_link', $instance['rss_link']);
 $twitter_link = empty($instance['twitter_link']) ? '&nbsp;' : apply_filters('widget_twitter_link', $instance['twitter_link']);

 if ( !empty( $title ) ) { echo $before_title . $title . $after_title; }; ?>
 <ul>
 <li><a title="Subscribe to the RSS Feed" href="<?php echo $rss_link; ?>">Subscribe to the RSS Feed</a></li>
 <li><a title="Follow on Twitter" href="http://www.twitter.com/<?php echo $twitter_link; ?>">Follow us on Twitter</a></li>
 </ul>

 <?php echo $after_widget;
 }

 function update($new_instance, $old_instance) {
 $instance = $old_instance;
 $instance['title'] = strip_tags($new_instance['title']);
 $instance['rss_link'] = strip_tags($new_instance['rss_link']);
 $instance['twitter_link'] = strip_tags($new_instance['twitter_link']);
 return $instance;
 }

 function form($instance) {
 $rss_default = get_bloginfo('rss2_url');
 $instance = wp_parse_args( (array) $instance, array( 'title' => '', 'rss_link' => $rss_default, 'twitter_link' => '') );
 $title = strip_tags($instance['title']);
 $rss_link = strip_tags($instance['rss_link']);
 $twitter_link = strip_tags($instance['twitter_link']);
?>
<p><label for="<?php echo $this->get_field_id('title'); ?>">Title: <input id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo attribute_escape($title); ?>" /></label></p>
<p><label for="<?php echo $this->get_field_id('rss_link'); ?>">RSS Feed Link: <input id="<?php echo $this->get_field_id('rss_link'); ?>" name="<?php echo $this->get_field_name('rss_link'); ?>" type="text" value="<?php echo attribute_escape($rss_link); ?>" /></label></p>
<p><label for="<?php echo $this->get_field_id('twitter_link'); ?>">Twitter Username: <input id="<?php echo $this->get_field_id('twitter_link'); ?>" name="<?php echo $this->get_field_name('twitter_link'); ?>" type="text" value="<?php echo attribute_escape($twitter_link); ?>" /></label></p>

<?php
 }
}

register_widget('my_subscribe_widget');

That seems like a lot of code but if you sift through it, it should start to make sense. With this code, you now have a fully functional RSS/Twitter widget. You will still need to style it to match your current theme however.

Breaking it Down

If playing with and deciphering code isn’t your thing, lets go ahead and break the code down.

 function my_subscribe_widget() {
 $widget_ops = array('classname' => 'widget_bu_subscribe', 'description' => 'Add an RSS and twitter link' );
 $this->WP_Widget('my_subscribe_widget', 'RSS/Twitter Links', $widget_ops);
 }

Above we are basically naming and describing our widget, while setting its class name. The widget will be named RSS/Twitter Links and will have a short description under it of  Add an RSS and twitter link.

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

 echo $before_widget;
 $title = empty($instance['title']) ? '&nbsp;' : apply_filters('widget_title', $instance['title']);
 $rss_link = empty($instance['rss_link']) ? '&nbsp;' : apply_filters('widget_rss_link', $instance['rss_link']);
 $twitter_link = empty($instance['twitter_link']) ? '&nbsp;' : apply_filters('widget_twitter_link', $instance['twitter_link']);

 if ( !empty( $title ) ) { echo $before_title . $title . $after_title; }; ?>
 <ul>
 <li><a title="Subscribe to the RSS Feed" href="<?php echo $rss_link; ?>">Subscribe to the RSS Feed</a></li>
 <li><a title="Follow on Twitter" href="http://www.twitter.com/<?php echo $twitter_link; ?>">Follow us on Twitter</a></li>
 </ul>

 <?php echo $after_widget;
 }

frontendThe actual widget function will be what is displayed on the front end. In this occasion, we are first grabbing our instances from what the user set on the back end. We pull the title, RSS link, and Twitter link into respected variables. We create a title (if there is one) and then proceed with our RSS / Twitter list. We echo (print) out our variables in their correct locations to create our links. Since we only want the user to input a Twitter username, we only echo that variable out after http://www.twitter.com/ .

function update($new_instance, $old_instance) {
 $instance = $old_instance;
 $instance['title'] = strip_tags($new_instance['title']);
 $instance['rss_link'] = strip_tags($new_instance['rss_link']);
 $instance['twitter_link'] = strip_tags($new_instance['twitter_link']);
 return $instance;
 }

In this function we are updating our data from the back end. Just make sure all option entries match up in titles.

 function form($instance) {
 $rss_default = get_bloginfo('rss2_url');
 $instance = wp_parse_args( (array) $instance, array( 'title' => '', 'rss_link' => $rss_default, 'twitter_link' => '') );
 $title = strip_tags($instance['title']);
 $rss_link = strip_tags($instance['rss_link']);
 $twitter_link = strip_tags($instance['twitter_link']);
?>
<p><label for="<?php echo $this->get_field_id('title'); ?>">Title: <input id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo attribute_escape($title); ?>" /></label></p>
<p><label for="<?php echo $this->get_field_id('rss_link'); ?>">RSS Feed Link: <input id="<?php echo $this->get_field_id('rss_link'); ?>" name="<?php echo $this->get_field_name('rss_link'); ?>" type="text" value="<?php echo attribute_escape($rss_link); ?>" /></label></p>
<p><label for="<?php echo $this->get_field_id('twitter_link'); ?>">Twitter Username: <input id="<?php echo $this->get_field_id('twitter_link'); ?>" name="<?php echo $this->get_field_name('twitter_link'); ?>" type="text" value="<?php echo attribute_escape($twitter_link); ?>" /></label></p>

<?php
}

rss-twitterFinally we are creating our back end form. This is what the user sees on the widget section of their dashboard after they add it to a sidebar (see image). First we create a variable called $rss_default, which grabs in the current RSS feed. This saves the user time and enters that value as the default RSS link value once the widget is added. Of course they are free to change it afterwords We put our default values into $instance (where you can see $rss_default being used, and everything else blank). We pull our instances into separate variables to use in the form.

Then we build our actual user input form. We label and title our fields for usability, and echo any values that might be in the fields. We are only using input fields here but if you need different types of input, there are plenty more. Check other widgets to see what you can or cannot do easily.

Hope everyone kept up! If you have any questions or comments, leave them below.

{ 9 comments… read them below or add one }

Kory Mathewson January 23, 2010 at 4:28 pm

Fantastic tutorial on widget building, very simple instructions… excited to try my hand at it.
.-= Kory Mathewson´s last blog ..Bloggers’ Day at the Art Gallery of Alberta =-.

Reply

Rick Anderson February 21, 2010 at 1:59 pm

So I’ve tried making a widget on a client’s thesis installation (Thesis 1.6, WordPress 2.92) . In this widget the client can select a class that they want to be applied to the widget. The classes are contained in a dropdown list. When they select the class and hit save the page renders correctly (that is the class is applied to the li.widget. Unfortunately when they hit save the option in the drop down box reverts to the default – even thought the page itself renders properly.

Do you have a suggestion for making the option selected from the drop down persistent in the widget option dialog?

Reply

Matt Hodder February 22, 2010 at 12:59 am

Hey Rick, I guess you would just want to add a conditional in the <option> tags that would go something like:

<option <?php if ($value) echo 'selected="selected"'; ?>>

Reply

Mark Shingleton July 13, 2010 at 12:48 am

That’s a really useful walk through for creating a widget. Thanks for taking the time to put that together. Just saved me a load of hassle. :)

Reply

Viet August 17, 2010 at 3:08 pm

I am using Thesis 1.7 and Wordpress 3.0 and I want to create a simple widget to paste Facebook Like Box code and display it, should I can do ?

Reply

HollyRobsonf April 14, 2011 at 8:02 am

Hey – I am certainly happy to find this. Good job!

Reply

SmashinGeeks April 25, 2011 at 12:11 am

Hey Matt,
As we are creating new theme for SmashinGeeks built on Thesis, we wanted the same piece of code and you just published it here. Thanks..

Reply

Matt Hodder April 25, 2011 at 12:19 am

Awesome.. Glad I could help!

Reply

chris glover September 19, 2011 at 6:16 pm

Why do only the first 12 of my widgets work on my thesis theme? I wanted to use the text widget more than once, too.
Thank you for any help you can give.

Reply

{ 4 trackbacks }

Leave a Comment