Make an ‘AddThis’ sharing widget for PyroCMS

In this article we’ll learn to make a widget for PyroCMS. This article will teach you the basics of making a PyroCMS widget and we’ll make our own, ready to use AddThis sharing widget along the tutorial.

Before we begin, here’s a little intro:
1) PyroCMS – It’s a ‘Content Management System’ built on ‘CodeIgniter‘ MVC framework written in PHP.

2) AddThis: AddThis is a bookmarking and sharing service, it provides an API with which you can share the content on your blogs or websites across 300+ social networks. Using AddThis is a breeze!

Here are the prerequisites:
1) PyroCMS (well, obviously!). You can get PyroCMS from here. Even though it is built on CI, you won’t need CI installed in your server for Pyro to run.

2) PHP knowledge: Of course, you need to be fairly well in PHP programming. You don’t have to be extremely good at CodeIgniter, just the basics would do.

Like any other MVC framework or CMS, PyroCMS too requires us to follow a folder structure to store our widget’s files and also a naming convention while naming our code files. We have to store our widget files in a folder inside the ‘widgets’ folder which can be found as follows:
web-root or www (depending upon your server)
— pyrocms (pyrocms installation)
—- addons
—- widgets
—- <our widget’s folder>

Lets start with our AddThis widget. Make a new folder for our widget and name it as add_this. The folder should be named carefully, as its name is going to reflect in our widget’s code. We’ll see it very soon. For now make sure the folder structure is as follows:
— widgets (follow from above)
—- add_this

Make a PHP file and name it as ‘add_this.php’. Notice how we have named it exactly what we’ve named our widget’s folder.

Here’s the code for the add_this.php file:

[php]
<?php if (!defined(‘BASEPATH’)) exit(‘No direct script access allowed’);
/**
* @package PyroCMS
* @subpackage Pyro_social! – Social Widget
* @author Rutwick Gangurde
* @author_url http://www.blog.rutwick.com
* @modified –
*
* Share your content across your social network
*/

class Widget_Add_this extends Widgets
{
public $title = ‘Pyro Social!’;
public $description = ‘Share your content across your network’;
public $author = ‘Rutwick’;
public $website = ‘http://www.blog.rutwick.com’;
public $version = ‘1.0’;

public $fields = array(
array(
‘field’ => ‘twitter_username’,
‘label’ => ‘Twitter Handle’
)
);

public function run($options)
{
return $options;
}
}
?>
[/php]

Notice the class name above. We named our folder add_this, then we named our main file as add_this.php, and now we named our main class as ‘Widget_Add_this’ (don’t miss the prefix ‘Widget_’ and the uppercase A). The class should extend the ‘Widgets’ class. So if you create a new widget later, say ‘xyz rocks’, then you should name your folder as xyz_rocks, and the main file as xyz_rocks.php, while the class as Widget_Xyz_rocks. People with some experience in CI know this strict naming convention that should be followed. The first few commented lines are some basic information about our widget. You can put anything you want here, it doesn’t affect our code!

Next are the public variables:
1) $title: Title for our widget. Name it wisely as the name should depict the purpose of the widget. It shows up in the widget listing area inside your website’s control panel.
2) $description: A short description of what our widget does.
3) $author: Your name here!
4) $website: Your website or your widgets webpage.
5) $version: The widget’s version.

These variables should be named like this, do not rename them to whatever you want!

The ‘$fields’ array holds all the information about the input fields that we want in our widget’s configuration area. Our widget will require the user of the widget to enter his twitter handle in a textfield while installing the widget. The inner array has two variables, ‘field’ and ‘label’. ‘field’ corresponds to ‘name’ attribute of the input field. And ‘label’ is a label for that field. Every single sub array corresponds to a new form element. That means if our widget requires 4 form input fields, there will be 4 sub arrays. The $fields array is required only if we want some configuration input for our widget. The function run is the main function where the major processing of our widget will happen. It takes in an argument, $options, which is an array that has our input values (while configuring the widget) and stores them for later use. This function should not be renamed.

Make a subfolder inside the add_this folder. Name it as ‘views’. This folder should be named ‘views’, you cannot name it anything else. This folder will be searched for the views of our widget. Make 2 new PHP files in this folder. Name them as ‘form.php’ and ‘display.php’.
The ‘form.php’ file constructs the display of the widget’s configuration area. When our widget is selected to be installed, this form will be displayed for configuring our widget.

form.php:
[html]
<ul>
<li class="even">
<label>Twitter Handle</label>
<?php echo form_input(‘twitter_username’, $options[‘twitter_username’]); ?>
</li>
</ul>
[/html]

There’s a very little code in this file. It should be an unordered list of form elements that we require for our widget’s inputs (if any). The ‘li’ elements can have classes ‘even’ or ‘odd’ (for some reason even I don’t know!). Notice the line, ‘echo form_input(…)’. This will output an html form element ‘input type=’text”. The parameter $options[‘twitter_username’] corresponds to ‘name’ in our $fields array and it will become the name attribute of this input type.

The display.php file is responsible for the actual output of the widget on the webpage we use it on.

display.php:
[html]
<script type=’text/javascript’ src=’http://s7.addthis.com/js/250/addthis_widget.js’></script>
<div class=’addthis_toolbox addthis_default_style’ style=’background-color:#C6E2FF;padding-top:3px; height:23px !important; border:1px solid #88ACE0; width:75% !important;’>
<span style=’font-size:11px;’><a class=’addthis_button_email’ style=’margin:0 10px 0 5px;’>&nbsp;email</a></span>
<span style=’font-size:11px;’><a class=’addthis_button_print’ style=’margin-right:20px;’>&nbsp;print</a></span>
<a class=’addthis_button_facebook_like’ style=’margin-right:20px;’></a>
<a class=’addthis_button_tweet’ style=’margin-right:20px;’ tw:via="<?php ($options[‘twitter_username’])?$options[‘twitter_username’]:’PyreThis!’; ?>"></a>
<a class=’addthis_button_digg’></a>
<a class=’addthis_button_googlebuzz’></a>
<a class=’addthis_button_google’></a>
<span style=’font-size:11px;’><a class=’addthis_button_expanded’>&nbsp;share</a></span>
</div>
[/html]

This code includes a call to the AddThis API, and the code for the various social networking buttons that AddThis provides us with. You can go to AddThis.com, choose your own buttons, and copy the code from there to use in our widget. All the code is put in a div that forms a bar, with all our buttons neatly arranged in it. You can give your own styles to this div, but do not change the class names of the div and the a tags inside the div. These classes are required for the API to work.

At the time of writing this article, one problem with including Javascript code was that, if you have a very long Javascript code snippet for adding some feature to your widget, you’d have to put the entire code within the <script> tags! That means, if you are using an image slider, the entire image slider JS code would come in the script tags! You can put the JS code in a file at some remote location and give its path as src to the script tags, but you cannot include your libraries in the widget’s folder itself (if someone finds out a better way to do this, please let me know!)

Now its time to see our widget in action! If you followed the steps properly and got all the files in place along with the proper naming conventions, then head on to the control panel of your website. Click on the Content tab, select the Widgets tab to see all the available widgets. You’ll see our widget listed over here.

Drag our widget and drop it in the ‘Unsorted’ area on the right under the title ‘Available Areas’. It should open up our widget’s configuration area.

Now enter a title for the widget, and enter your twitter handle. The title textbox comes by default for every widget, whereas the Twitter handle textbox was coded by us. Click on ‘Save’. The widget will close and will be replaced with this:

Copy the code ‘{pyro:widgets:instance id=”1″}’. Edit the page you want the widget to appear on, and paste this code on it.

Save the page. Now visit your website, and open the page you had put the widget instance on.

If all went well, you should see the share bar as above. I hope you followed the tutorial properly with all the naming conventions taken care of. This article should give you a head-start on making widgets for PyroCMS. In case of any queries, doubts, suggestions to improve the tutorial, please feel free to drop a comment. Or you can contact me at: mail@rutwick.com, @tweetrut.

Thanks fellas!