WordPress Widget: progress bar

Published on 16 octobre 2013

I’m still getting to know WordPress features and so far I’m happy on how it works as well as a little bit frustrated. WordPress is perfect if you want an out-of-the-box solution for blogging, but it can be not so nice to tweak and play with… Thankfully the WP community is huge and you can find examples and documentation on almost every problem.

I’m a versatile person, which explains the non consistence of the topics of this blog, but I also like to be organized (at least I try)…So I wanted a small thingy to see how I’m progressing on my current projects/topics of interests.

 

What we want to achieve

The idea is to display a widget on the right sidebar of the theme, that contains the name of a task and its progression. In WordPress, widgets and plugins aren’t exactly the same:

  • Plugins are to WordPress what extensions are to Chrome, which means that they can be quite a lot of things, but generaly only the admin can modify their settings
  • Widgets are small visual components that allow you to quickly display information. Generaly widgets are based on plugins (except for WP default widgets)

I decided to take a full widget approach, so I will not use plugin settings page nor any other plugin specific functions. Everything will be done within the widget administration page.

General overview

Things we need to create:

  1. The administration form, available in the Appearance > Widget menu of the administrator dashboard

  2. Retrieve settings of the widget from the database

  3. Save settings

  4. Retrieve widget settings

  5. Display the plugin

Creating the widget

Useful resources: WordPress Widget API. If you’re not familiar with the way that WordPress works, it’a very good place to start.

The first step to create a new WordPress widget is to add a .php file in your wp-content/plugins ftp directory. My widget name is « workinprogress », don’t forget to replace that by « YourOwnWidgetName ». You have to inssert a mandatory header in this file. Sould look like this:

<?php
/* Plugin Name: Work in progress
Plugin URI: geeksperiment.com
Description: Adding progress bars to a sidebar widget
Version: 1.0
Author: edg
Author URI: geeksperiment.com  */
?>

You can also add copyright informations, you can find examples of what it looks like.

Ok, lets start by creating the widget class and then register the widget with WordPress:

/* Register widget with WordPress.	*/

function __construct() {

   parent::__construct(

   'workinprogress', // Base ID

   'WorkInProgress', // Name

    array( 'description' => __( 'Adding progress bars to a sidebar widget', 'text_domain' ), ) // Args

    );}

}//end of WIP class

//This adds your widget to your template	

// register widget	

function register_WorkInProgress() {

	register_widget( 'WorkInProgress' );

	add_action( 'widgets_init', 'register_WorkInProgress' );

}

2 .Getting settings (back-end side)

The form is created, the inputs can be filled, but won’t be saved nor used by the widget just now. To get previously saved data, we complete the form function like so:

* @see WP_Widget::form()	 

* @param array $instance Previously saved values from database.	 */		

	public function form( $instance ) {

	//allows admin to change widget name			

		if ( isset( $instance['title'])) {

			$title = $instance[ 'title' ];

			}			

		else {

			$title = __( 'Work in Progress', 'text_domain' );

			}		

//retrieves the previsously created tasks		

		$taskName = isset ($instance['taskName']) ? $instance['taskName'] : 'None';

		$taskProgress = isset ($instance['taskProgress']) ? $instance['taskProgress'] : 0;

//HTML content of the back end widget

// .............</code></pre>
  

For now the widget (after been activated via the « Installed plugins » menu) should look like this:

widget_screen_big

3. Saving settings

After getting and displaying the settings of the task, we implement the modification and update. Add an update function to the WorkInProgress class:

 * @see WP_Widget::update()		 

 * @param array $new_instance Values just sent to be saved.

 * @param array $old_instance Previously saved values from database.

 * @return array Updated safe values to be saved.*/

public function update( $new_instance, $old_instance ) {

	$instance = $old_instance;

	$instance['title'] = (!empty($new_instance['title']))? strip_tags( $new_instance['title'] ) : $instance['title'];

	$instance['taskName'] = (!empty( $new_instance['taskName']))? strip_tags($new_instance['taskName'] ): $instance['taskName'] ;

	$instance['taskProgress'] = (!empty( $new_instance['taskProgress'])) ? strip_tags($new_instance['taskProgress'] ): $instance['taskProgress'] ;

	return $new_instance;		

}

The back-end is completed, the widget can now by managed by an admin.

4. & 5. Actually showing the widget

Add one last function to the class. The function uses the current values of the params of the current $instance:

* The following is the CORE of your widget

* @see WP_Widget::widget()

* @param array $args     Widget arguments.

* @param array $instance Saved values from database.*/

public function widget( $args, $instance ) {

//definition of the arguments (variables) of the widget

	$title = apply_filters( 'widget_title', $instance['title'] );

	$taskName = isset ($instance['taskName']) ? $instance['taskName'] : 'Not much';

	$taskProgress = isset ($instance['taskProgress']) ? $instance['taskProgress'] : '100';

	echo $args['before_widget'];

	if (!empty($title )) {

		echo $args['before_title'] . $title . $args['after_title']; //displays the title

	}

	echo '</pre>

<h3>'.$taskName.'</h3>

<div class="pb-wrapper"></div>

';

echo $args['after_widget'];

}

That’s it, the widget is done…but there is still nothing on the page… I choosed to display a progress bar as a span included in a div, with the span’s width reprensenting the progress value. A few reasons for that: I wanted something simple to begin with, so I didn’t want to bother including all jQuery files and I wanted to use an image to make fun stuff (and see if my css wasn’t too rusty).

 

To actually see the widget on the page you just have to add css properties in your general styles.css file or if you prefer in a widget.css file located in the same path as the php file.

After doing so, add this line to the register_WorkInProgress function:

  wp_enqueue_style( 'wip', plugins_url( "widget.css", __FILE__ ), array(), '1' );}

Any feedback is welcomed! 🙂

comments powered by Disqus