Extending the Socials Ignited plugin – part 1

- by Anastis Sourgoutsidis | Posted under: Plugins, Tutorials

So, the world is not enough, and 50+ icons that come bundled with the Socials Ignited plugin just won’t cut it. What do you do? How do you add your icons into the mix? And most importantly, how do you do it without losing any changes when updating?

Well, I promise to show you how, as long as you promise to know some PHP, especially how to manipulate arrays. The rest of the code (hooking onto WordPress filters) is pretty much self explanatory or can be copied verbatim, and even if you don’t fully understand how filters work, you can still get something usable. Of course, the more you know allows you to go one step further…

Prerequisites

v1.1 of the plugin introduced filters for you to hook and extend the list of services and icon sets, so make sure you have at least this version for the rest of the tutorial to work.

Creating a new plugin

So, the first thing we need to do is to create a new plugin. There, we will write the code to manipulate the Socials Ignited plugin, and we will store our new icons, so that they won’t be deleted on a future plugin update.

So, go to your wp-content/plugins directory and create a new folder, named my-socials-ignited

In there create new file, named my-socials-ignited.php and paste in it the following code:

<?php
/*
Plugin Name: My Icons for Socials Ignited
Description: My own icons for the CSSIgniter's Socials Ignited widget
Version: 1.0
License: GPL
Plugin URI: http://www.mydomain.com/my-socials-ignited-icons
Author: Me, myself and I
Author URI: http://www.mydomain.com/
*/
?>
<?php

// Rest of the code goes here...

?>

This is a special header that gives information to WordPress about our little plugin. The minimum required is the first line, Plugin Name: as without it WordPress will never recognize the file as a plugin. The rest of the lines are used by WordPress to display the appropriate information in the Plugins management screen.

The rest of the code of this tutorial should be placed where the // Rest of the code goes here… line is.

Icon sets, variations, sizes, paths, oh my…

If you used the Socials Ignited widget, you must have noticed that you can choose among 2 icon sets, Square and Round. The Round set has two color variations, dark and light, and each variation is available in a 32×32 size.

The Square icon set on the other hand, is only available in one color, default, but comes in three different sizes, 32×32, 48×48 and 64×64.

This is what this hierarchy looks like organized in folders:

Simple stuff, right?

These are all stored inside the plugins folder, inside an /images/ directory. In order to add a new icon, we have to mimic this structure.

Adding a missing icon

So, let’s suppose you really like and use the Round – Dark set of icons, 32×32 in size. But the AddThis icon is missing. Let’s try and add it, shall we?

Y U NO HAV ADDTHIZ IKON?

Let’s go back to our plugin, and create an images folder. In there, create a round folder. In there, create a dark folder. In there create a 32 folder. In there, place your icon. You should have something like this:

What your plugin’s file structure should look like at this point.

Note the icon’s file name. It’s like a slug version of the service’s name, followed by the .png extension. Since there are some exceptions, and some services even have alterative icons, you can see a full list of supported filenames by opening/editing socials-ignited/socials-ignited.php lines 57-114.

They are in the form

'addthis' => _x('AddThis', 'website name', 'cisiw'),

where the left hand side, i.e. addthis is the name that should be used as a file name.

Here is a list of currently supported names/icons:

addthis, amazon, amazon_alt, apple, apple_alt, blogger, behance, delicious, designfloat, designbump, deviantart, digg, dopplr, dribbble, email, evernote, facebook, flickr, forrst, friendfeed, github, github_alt, gplus, grooveshark, gtalk, instagram, lastfm, linkedin, myspace, netvibes, newsvine, orkut, paypal, picasa, pinterest, posterous, reddit, rss, sharethis, skype, soundcloud, spotify, stumble, technorati, tumblr, twitter, twitter_alt, viddler, vimeo, virb, virb_alt, yahoo, yahoo_alt, youtube, youtube_alt, windows, wordpress, zerply

Back to adding our new icon. You’ve created the folders, copied the icon in the right place with the right name, you were probably on a hurry and went ahead and refreshed the Social Igniter’s settings page, but you didn’t see the new icon. What went wrong?

Well, you need to tell our plugin that it needs to look for icons from some other locations as well, by hooking on the cisiw_lookup_paths filter. Paste this in your plugin:

add_filter('cisiw_lookup_paths', 'my_icons_lookup_paths');
function my_icons_lookup_paths($paths)
{
    $paths['dir'][] = plugin_dir_path( __FILE__ );
    $paths['url'][] = plugin_dir_url( __FILE__ );

    return $paths;
}

The cisiw_lookup_paths filter passes a two-element array to our hooked function. The $paths['dir'] element is itself an array containing a list of local paths that the plugin uses in order to know where to look for icons, and whether they exist or not. The $paths['url'] element is again an array, only this time it contains a list of URLs that are used to output the icons’ URLs. Both local and URL paths in the $paths array need to be absolute, and the rest of the structure is created automatically. You do remember what we said about the /images/set/variation/size/icon.png structure, don’t you?

Make sure you set both paths, as their (implied) numeric indexes must match in order to properly determine and handle icons.

Save your file, and refresh the Socials Ignited settings page. You should now see the new icon:

Hooray!

That’s it really. Assuming you have entered a URL for the AddThis service, and you have you widget showing the Round – Dark – 32×32 icons, you should see the AddThis icon among the others.

Adding a new service

So, our list of 50+ social networks is not enough, and you want to add a one we missed (or we didn’t care to add). How do you do it? It’s quite easy actually. What you’ve done so far with the plugin serves as the basis for adding icons to ANY service (social network).

Let’s say that we want to add an icon for the imaginary social network that I have built, AnastisBook. We, again, want to add the icon in the Round – Dark – 32×32 icon set. Go on and rename your icon to anastisbook.png and place it in my-socials-ignited/images/round/dark/32/anastisbook.png alongside the addthis.png icon (if you opted to add it).

Of course, it won’t show up just yet, as Socials Ignited doesn’t know anything about AnastisBook. What we need to do, is hook onto the cisiw_services filter and add our service to the list of the allowed ones.

add_filter('cisiw_services', 'my_icons_add_services');
function my_icons_add_services($services)
{
    $my_services = array(
        'anastisbook' => 'AnastisBook'
    );

    $services = array_merge($services, $my_services);
    return $services;
}

The $services array contains a list of key-value entries, where the key is the service’s slug name, and the value is the actual name that will be printed on the settings page. Make sure the key contains only letters, numbers, dashes and underscores, as it will map to the filename of the icon. You DON’T want to have illegal character issues with the filesystem.

Anyway, we create a new array, $my_services and we add an element with key ‘anastisbook‘ and value ‘AnastisBook‘. The value can also be internationalized like __(‘AnastisBook’, ‘plugin_domain’) if you put some more effort into the plugin.

Then, we merge the original $services array with our own $my_services and we return the resulting array. AnastisBook should now be in the list of available services.

If you need to clear things up a bit, you can even remove some services. All you need to do is unset() a service from the original $services array before merging. For example, in order to remove the Amazon service, you’d have:

add_filter('cisiw_services', 'my_icons_add_services');
function my_icons_add_services($services)
{
    $my_services = array(
        'anastisbook' => 'AnastisBook'
    );

    unset($services['amazon']);

    $services = array_merge($services, $my_services);
    return $services;
}

End of part 1

This concludes the first part of the tutorial. In the next (and probably last) part, I’ll show you how to add your own icon sets, variations, as well as explain some limitation and issues that you may encounter.

Until then, happy coding!

[UPDATE 4 Jan. 2012] Part 2 is now available!

4 thoughts on “Extending the Socials Ignited plugin – part 1

  1. Hello, I’ve become stuck while following this tutorial, in the section regarding directory and url paths for adding a new icon. Could you please share some example code for what I need to add to the section:
    $paths['dir'][] = plugin_dir_path( __FILE__ );
    $paths['url'][] = plugin_dir_url( __FILE__ );

    Thank you kindly.

    • Hi there,
      you can copy/paste the example my_icons_lookup_paths() function as is (along with the add_filter() statement) and it should work, as long as you follow the directory structure that the plugin already uses.

      If I could give a better example, i guess it would be:

      add_filter('cisiw_lookup_paths', 'my_icons_lookup_paths');
      function my_icons_lookup_paths($paths)
      {
          $paths['dir'][] = '/home/user/public_html/wp-content/plugins/your_socials_ignited_extension/';
          $paths['url'][] = 'http://www.example.com/wp-content/plugins/your_socials_ignited_extension/';
       
          return $paths;
      }

      However the example given into the tutorial should work by itself for most cases, provided that your icons are stored within your extension plugin.

      Please note that I don’t really remember if the path and url need a trailing slash, so please try both.

      Hope this helps :)

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>