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…
- A WordPress installation (duh!)
- The latest Socials Ignited plugin (v1.1 at the time of writting)
- A reason to extend the plugin, i.e. some new icons (must be .png files)
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:
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:
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?
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:
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
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:
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:
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.
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:
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!