Contrary to what I originally thought when I released WP-Cumulus, it seems most people prefer to use it on their blog’s sidebar. I estimate that at least 80% of users use the widget. But the plugin still has two other ways to embed the movie into your blog, and version 1.20 greatly improves the most important of those. Shortcodes can be incredibly useful, and version 1.20 of my plugin now properly supports them.
WordPress 2.5 introduced an API that allows us plugin creators to easily create square bracket ‘tags’ that users can type into blog posts and pages to trigger plugin output. WP-Cumulus has used something similar since day one, but the official shortcodes API allows for a lot more flexibility.
The most important change is that you can pass parameters. For Cumulus, this means you can override your default settings each time you embed a tag cloud into a post. Lets assume you’ve set up the non-widget version of the tag cloud to be 500 pixels wide. You can now use the following shortcode to display it at 300 pixels.
If you’d instead like a cloud with red tags and a transparent background, here’s the code for that:
Here is a complete list of the attributes WP-Cumulus currently supports:
|Attribute||Used for||Possible values||Example|
|width||Width of the tag cloud||Number of pixels (positive integer)||width=”300″|
|height||Height of the tag cloud||Number of pixels (positive integer)||height=”240″|
|tcolor||Tag color||HEX color value without the ‘#’ prefix||tcolor=”ffcc00″|
|tcolor2||Tag color for less important tags||HEX color value without the ‘#’ prefix||tcolor2=”cc9900″|
|hicolor||Tag highlight color||HEX color value without the ‘#’ prefix||hicolor=”ffffff”|
|bgcolor||Tag cloud background color||HEX color value without the ‘#’ prefix||bgcolor=”333333″|
|speed||Rotation speed||Precentage, higher means faster||speed=”150″|
|trans||Background transparency||“true” or “false”||trans=”true”|
|distr||Even tag distributions along sphere||“true” or “false”||distr=”true”|
|args||Argments to be passed to the ‘wp_tag_cloud’ function (experimental, use at own risk)||URL encoded string||args=”smallest=10″|
|mode||Tag/Category mode||“tags”, “cats” or “both”||mode=”tags”|
By using any of these attributes, you override the values entered under ‘Settings->WP Cumulus”. These serve as the defaults used when using the shortcode, so simply entering
into a post will result in a tag cloud with those settings. If you have only one cloud inside a post or page it’s probably best to change the main settings. The attributes listed above will allow you to have multiple clouds inside posts, all with different settings.
WordPress 2.5 and up
Please note that since the shortcodes API was introduced in WordPress 2.5, none of this will work on older versions. The new lowercase shortcodes replace the old
one. That still works for now, but is ‘deprecated’ for blogs running WP 2.5 or newer.