How to use WP-Cumulus shortcodes
WP Cumulus Flash tag cloud by Roy Tanck and Luke Morton requires Flash Player 9 or better.
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.
Shortcodes
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.
[wp-cumulus ]
If you’d instead like a cloud with red tags and a transparent background, here’s the code for that:
[wp-cumulus tcolor="ff0000" tcolor2="ff0000" trans="true"]
Supported attributes
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) | ”300″ |
height | Height of the tag cloud | Number of pixels (positive integer) | ”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” |
Default values
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 [wp-cumulus]
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 [WP-CUMULUS]
one. That still works for now, but is ‘deprecated’ for blogs running WP 2.5 or newer.
Share this post: on Twitter on Facebook on Google+
Tags: attributes, shortcodes, tag cloud, tutorial, WP-Cumulus
thank’s..for tutorials..
Comment by Hakim — January 6, 2010 @ 4:48 am
Can I use this tag cloud in tumblr?
Comment by tek penny — January 14, 2010 @ 12:03 pm
Tek penny, I’m not sure. I have tutorials available for anyone willing to attempt this, but I haven’t looked at it myself.
Comment by Roy — January 21, 2010 @ 9:47 am
Hi Roy,
I would like to try myself, where can I find the tutorials?
thanks a lot
Comment by tek penny — January 21, 2010 @ 10:32 am
tek penny: here. Please keep me posted!
Comment by Roy — January 21, 2010 @ 10:37 am