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 }