How to repurpose my tag cloud Flash movie

WP-Cumulus tag cloud plugin

WP-Cumulus is now open source. So instead of going through the documentation below you can download it and have a look inside. See http://wordpress.org/extend/plugins/wp-cumulus/ for more info. You can get the development version which includes the sources from the download page.
To fix an XSS vulnerability, Version 1.23 of the plugin no longer supports calling ‘javascript:’ links from tags. If you need the Flash movie to interface with javascript, I recommend downloading the source files and implementing AS3’s ExternalInterface class to handle communication.

I’ve been getting a lot of questions about my WP-Cumulus WordPress plugin. Many people have asked my whether they can use the Flash movie in their own projects, and how to go about it. Well, here’s how.

When you download the plugin you’ll find it consists of three files. The first, wp-cumulus.php is the actual WordPress plugin. It hooks into WordPress, adds the options panel to the backend, and replaces the WP-CUMULUS tag with the Flash movie. You’ll also find SWFObject, which is used to embed the Flash movie into your page (future version might not use this, as it appears to cause problems for some people).

If you’re looking to repurpose the Flash movie, all you’ll need is the ‘tagcloud.swf’ file. Here’s what you’ll need to know in order to use it.

  1. The movie requires Flash Player 9 or better.
  2. It contains only Latin characters. This short tutorial guides you though the process of adding support for your language.
  3. The movie is set to fill the available Stage size but keep it’s aspect ratio (Flash’s default scaling behavior). It is square, so if you embed it at 800*500 the sphere will be exactly the same size as when you embed at 500*800. With 150px of empty space on two sides.
  4. Landscape aspect ratios work best because text is oriented horizontally.

Flashvars

The movie gets the tags information through ‘flashvars’. See here for more info on flashvars. SWFObject implements flashvars a little differently (see here). The actionscript code inside the movie looks for the flashvars in the root timeline, so if you’re planning on loading the movie inside another Flash movie, just pass the vars to that movie.

The flashvar used to pass the tags info is called “tagcloud”, and contains XML data describing the tags. If it is not passed the movie will look for a file called “tagcloud.xml” in the current path and parse that instead. This was used for testing, but might also prove useful if you’re using the movie outside WordPress.

The XML layout used is:
<tags>
  <a href="http://www.roytanck.com/tag1" style="font-size:9pt;" >Tag name<a>
  <a href="http://www.roytanck.com/tag2" target="_blank" style="font-size:12pt;" >Tag two<a>
  ...
</tags>

The other attributes used in WordPress’ default tag cloud output are not used. The style attribute is searched for numbers using a very crude mechanism. You can simply use

style="12.4"

In order to set the font size to 12.4.

To prevent problems with character encoding, the WordPress plugin passes the tags urlencoded, but your project might not need this. It should work either way.

Here’s a list of currently available flashvars:

NameFormatDescription
modeString: tags|cats|bothTells the movie to expect and display tags, categories or both.
distrString: true|falseIf set to true, the tags are distributed evenly over the sphere’s surface.
tcolorHex color value: 0xff0000 for red.The default tag color
tcolor2Hex color valueSecond tag color. If supplied, tags will get a color from a gradient between both colors based on their popularity.
hicolorHex color valueTag mouseover/hover color
tspeedNumber: percentageDetermines the speed of the sphere’s rotation. The default is 100, higher numbers increase the speed.
tagcloudXML string (urlencoding optional)The tag cloud, XML format described above.
xmlpathPath to load the XML fromURL, defaults to ‘tagcloud.xml’

Per-tag colors

As of version 1.18 you can override the global tag color settings by adding two optional arguments to the tag cloud XML. The ‘color’ and ‘hicolor’ attributes let you control the tags default and hover colors.

<a href="http://www.roytanck.com/tag1" style="font-size:9pt;" color="0xff0000" hicolor="0xffcc00" >Tag name<a>

Example

The following will render a tag cloud with two red tags and a transparent background at 600 by 400 pixels. As always with SWFObject, it will replace a div (here called ‘flashcontent’) in your page. This is the Javascript part only.

<script type="text/javascript">
var so = new SWFObject("tagcloud.swf", "tagcloud", "600", "400", "7", "#336699");
so.addParam("wmode", "transparent");
so.addVariable("mode", "tags");
so.addVariable("distr", "true");
so.addVariable("tcolor", "0xff0000");
so.addVariable("hicolor", "0x000000");
so.addVariable("tagcloud", "<tags><a href='http://www.roytanck.com/tag1' style='9'>Tag name</a><a href='http://www.roytanck.com/tag2' style='12'>Tag two</a></tags>");
so.write("flashcontent");
</script>

Download (updated!) example files here (38kB).

That’s all there is to it. Of course, this movie was created to fit the needs of the WP-Cumulus plugin. Chances are the way scaling is handled (for instance) does not fit your needs. If this is the case, feel free to contact me about possibly whipping up a custom version.

682 Comments

  1. Can i add acustom xmlpath?

    Comment by Nertus — March 1, 2012 @ 10:40 am

    • Yes, the xmlpath flashvar lets you set the XML’s location. This can also be a script that returns valid XML.

      Comment by Roy — March 5, 2012 @ 9:42 am

  2. Well, thank you very much for this great tag cloud and for the excellent support :)
    I wanted to know if it’s possible to delete the mouseover effect on the tags : or change the rectangle effect.

    Comment by WindCut — March 9, 2012 @ 3:43 am

  3. One more thing,
    When i tried to overwrite this open version with the development version ( needed to embed fonts ) , it didn’t work :( , the swf file is no longer able to render!

    Comment by WindCut — March 9, 2012 @ 4:20 am

    • The font needs to be changed in two places, and the font name needs to match up exactly. Especially on Macs, this may require a bit or tinkering.

      The box effect is in the Tag.as file, and you should be able to remove it by commenting out the right lines.

      Comment by Roy — March 18, 2012 @ 2:30 pm

      • Hi Roy,

        I have the TagCloud implemented in a SharePoint environment which works well but like WindCut would like to remove the rectangle around the element in the ‘cloud’ that is highlighted on mouse over. You responded to WindCut that ‘..box effect is in the Tag.as file..’ Could you elaborate on that as I’ve not been able to work out what that is or where I would find it.

        Regards,

        David

        Comment by David — May 9, 2012 @ 12:19 pm

        • Lines 70 thru 79 in that file create the tag’s background, which is shown on hover. The lineStyle call (73) sets the outline’s properties.

          Comment by Roy — May 24, 2012 @ 11:06 am

  4. Dear Roy,

    In regards to “whipping up a custom version” would it be possible to add a moving picture or video I should say and then have the tag cloud integrated with it?

    Thank you in advance,

    AF

    Comment by Antonio Found — March 23, 2012 @ 11:36 pm

    • Do you mean a video background? Or would the tag cloud need to interact with the video? Sounds interesting! :)

      Comment by Roy — March 26, 2012 @ 9:31 am

      • Yes, I would like the tag cloud to interact with the video. Can we talk about more details?

        Thanks in advance,

        AF

        Comment by Antonio Found — March 26, 2012 @ 6:15 pm

        • Please contact me at [firstname].[lastname]@gmail.com . Thanks.

          Comment by Roy — March 29, 2012 @ 11:28 am

  5. The caching of the tag cloud gave me some headaches. SWF and XML files are cached by default by most browsers. Changes in the XML file became visible when the browser cache was erased by the user. Off course, you don’t want to rely on an end user. A search suggested the following solution:

    Add a random variable to the XML file and SWF file like this:
    “tagcloud.swf?”+Math.random()
    “tagcloud.xml?”+Math.random();

    In my situation, the javascript was set up like this:

    var hasflash=false;
    var so=new SWFObject(“/flash/tagcloud.swf?”+Math.random(),”tagcloud”,”100%”,”100%”,”9″,”#ffffff”);
    so.addParam(“wmode”,”transparent”);
    so.addParam(“swLiveConnect”,”true”);
    so.addParam(“scale”,”exactFit”);
    so.addVariable(“tcolor”,”0x333333″);
    so.addVariable(“tcolor2″,”0x009900″);
    so.addVariable(“hicolor”,”0x000000″);
    so.addVariable(“tspeed”,”200″);
    so.addVariable(“distr”,”true”);
    so.addVariable(“xmlpath”,”/flash/tagcloud.xml?”+Math.random());
    so.write(“tagcloud”);

    This works like a charm. Any change in the XML file is visible immediately after reloading the page by the client.

    Hope this helps anyone struggling with the same issue!

    Peter

    Comment by Peter — April 17, 2012 @ 3:56 pm

  6. Hi,

    I love your wp-cumulus tag, and thank you very much for making it open source.

    I have two questions if that’s ok?

    1) Is it possible to embed this into a html module?

    2) Is it possible to generate one of these from an RSS Feed?

    Many thanks in advance!

    Comment by Helen Davies — May 11, 2012 @ 12:23 pm

    • 1) Yes, and the example files should help you with that.

      2) You’d have to reformat the feed into the XML format that the movie expects. So, with a bit of pre-processing, yes.

      Comment by Roy — May 24, 2012 @ 11:03 am

  7. Hi,

    I’m currently trying to use the tag cloud inside another fla. It’s positioned 3 Layers inside the build. I’ve tried adding the flashvars to the root layer (but not sure that I have this correct – relative AS3 novice). So far I have not been able to get the tagcloud to display. Could you please advise.
    Many thanks.
    Colin

    Comment by Colin Hunter — May 22, 2012 @ 1:51 pm

    • That si nearly impossible to do because the movie wasn’t designed for it. It relies on flashvars and uses the root stage’s dimensions to determine scaling. you’ll have to dig quite deep to re-route all those things. I’ve not attempted this at all, so I won’t be much help I’m afraid.

      Comment by Roy — May 24, 2012 @ 10:54 am

      • That’s a shame, I don’t like the word ‘impossible’ – I believe I could manage the routing through the nested MC’s.. any advice on getting the flashvars into actionscript would help, if at all possible. You’re welcome to use my private email if that feels appropriate. Thanks for the time you give for replies!

        Comment by Colin Hunter — May 25, 2012 @ 12:53 pm

        • oh, PS. I have scaling set up on the main container and feel ok that scaling inside the holding MC from the cumulus fla can work – I’d love to continue to explore the potentials and would be more than willing to share the results in an open source spirit.

          Comment by Colin Hunter — May 25, 2012 @ 12:55 pm

        • Flashvars will land in the main timeline, and I guess you should be able to read them from there, and pass them to the loaded swf as a constructor argument. Please let me know what you come up with.

          Comment by Roy — May 31, 2012 @ 10:48 am

  8. Hi, I had the cloud working fine and have now moved to a new hosting company and the cloud stopped working. the url is http://www.drachsi.com/about-drachsi.htm

    Any suggestions what the problem could be? I test in both Explorer 9 and FireFox 13

    Regards, and thanks for providing this interesting idea.

    Drachsi

    Comment by Drachsi — June 20, 2012 @ 1:47 pm

    • I’m sorry I didn’t respond to this earlier. It seems to working fine now?

      Comment by Roy — July 4, 2012 @ 8:21 pm

  9. hi and first od all, very thanks for this amazing stuff !
    i would like to use it on drupal CMS. how i need to run it ? can someone help me to put it on place ?
    very thanks for your answers…
    regards,

    Comment by gouzdaille — June 29, 2012 @ 2:28 am

    • I think there’s a Drupal port out there, but I can’t seem to remember the project’s name.

      Comment by Roy — July 4, 2012 @ 8:12 pm

  10. Have you considered writing an HTML5 version of this that does not require flash?

    Comment by Steve lloyd — July 1, 2012 @ 11:42 pm

    • Yes, but I find that even with canvas it’s not yet possible to get smooth font scaling like in Flash. Although I’d love for someone to prove me wrong.

      Comment by Roy — July 4, 2012 @ 8:10 pm