FatCloud by NetLife

About FatCloud

FatCloud renders graphically rich tag clouds using Flash layered on top of regular HTML tag clouds, inheriting their properties, including text, URLs, size and DOM tab index.

When FatCloud draws an SWF, it leaves the original HTML tag cloud in tact, ensuring search engine indexability and web accessability.

How to use FatCloud

In JavaScript:

Include the FatCloud.js somewhere in your HTML page before you insert any FatCloud objects.
```
<script type="text/javascript" src="FatCloud.js"></script>
```

Create a tag cloud in HTML. For example:

<div id="myCloud">
	<a href="one" style="font-size:1em">One</a>
	<a href="two" style="font-size:1.5em">Two</a>
</div>

Insert some inline JavaScript anywhere in your document (ideally, for neatness, directly after the tag cloud HTML):
```
<script type="text/javascript"> ... </script>
```

Inside aforesaid script block, create a new FatCloud object:

// syntax: var myVar = new FatCloud(id_of_tag_cloud, name_of_skin);
var myCloud=new FatCloud('myCloud', 'Wordle');

Set skin options (check FatCloud.xml for individual skin options):

myCloud.options.textAngle='Horizontal';
myCloud.options.colorScheme='Aqua';

If FatCloud.swf isn't in the same directory as your HTML file, at some point, set the fatCloud.SWF value to its URL (relative URLs are OK):
```
fatCloud.SWF='path/to/FatCloud.swf';
```

In PHP:

If you use PHP to generate your FatCloud, you'll be able to take advantage of FatCloud's built-in server-side caching system. This can dramatically increase performance in tag clouds which have high client-side CPU costs (such as the Wordle skin).

The PHP method is the prefered method to generate FatClouds. You should only use JavaScript if you're on a server without PHP support.

Include the FatCloud.js and FatCloud.php files in your PHP page before you insert any FatCloud objects.
```
<?php require_once('FatCloud.php'); ?>
<script type="text/javascript" src="FatCloud.js"></script>
```

Create a tag cloud in HTML. For example:

<div id="myCloud">
	<a href="one" style="font-size:1em">One</a>
	<a href="two" style="font-size:1.5em">Two</a>
</div>

Insert a pair of PHP delimiters anywhere in your document (ideally, for neatness, directly after the tag cloud HTML):
```
<?php ... ?>
```
If FatCloud.swf isn't in the same directory as your PHP file, inside your PHP delimiters, set the FatCloud::$SWF value to its URL (relative URLs are OK):
```
FatCloud::$SWF = 'path/to/FatCloud.swf';
```

Create a new FatCloud object:

// syntax: $myCloud = new FatCloud(id_of_tag_cloud, name_of_skin);
$myCloud = new FatCloud('myCloud', 'Wordle');

Set skin options (check FatCloud.xml for individual skin options):

$myCloud->options['textAngle'] = 'Horizontal';
$myCloud->options['colorScheme'] = 'Aqua';

Echo your FatCloud object to generate the FatCloud JavaScript code which creates the SWF object.
```
echo $myCloud;
```

Skin Caching Options

When FatCloud skins have performed lengthy calculations, it can use an AJAX call to store the results on the server. By default, results are stored in a single file FatCloud.sc in the same directory as FatCloud.php. If you have disk access permission issues, you can instead store results in a single MySQL text field. This option is available regardless of which method you use (PHP or JavaScript) to generate your clouds.

To enable MySQL skin cache storage, set the following values:

FatCloud::$dbHost='hostname';
FatCloud::$dbUser='username';
FatCloud::$dbPass='password';
FatCloud::$dbName='database_name';
FatCloud::$dbTable='table_name';
FatCloud::$dbKeyField='tables_primary_key_field';
FatCloud::$dbKeyValue='unique_id_of_row';
FatCloud::$dbValueField='text_field_to_store_cache';

Skin Development

Making new skins for FatCloud is fairly straightforward. Most of the tiresome to-and-fro between the DOM and AS3 platforms is taken care of. Before you start, make sure:

You're familiar with object-orientated ActionScript 3 coding
You understand DTDs and well-formed XML
You have a copy of Adobe Flash CS4 or later installed
All the fonts listed in FatCloud.xml are installed on your computer

You don't need to know JavaScript or PHP to write skins for FatCloud, but it'll probably help to have some background.

Every FatCloud skin is an extension of the FatCloudSkin ActionScript 3 class, and part of the Skins package. The SimpleSkin class contains all the necessary elements of a working FatCloud skin, so it's the best place to start looking for what to do. When you think you're done, compile FatCloud.fla and off you go!

Here are a few important points to remember:

Every skin needs to be registered in FatCloud.xml in order to be recognised by GUIs like WordPress, and to supply defaults to the SWF. Add your skin and its options to the <skins /> section of FatCloud.xml as per the embedded DTD.
Because Flash only compiles SWFs with classes explicitly declared at design-time, you need to declare a dummy variable with your skin's class name somewhere in the main program. There's a section set aside at the top of FatCloud.as for this purpose.
FatCloud will set the stage.stageWidth and stage.stageHeight properties before instantiating your skin. Use this properties to help lay out your graphics.
Your skin needs a render() function, which is called when the cloud is first displayed, and whenever it's resized. Try to avoid unnecessary re-rendering – your class's .firstRender boolean property will help here.
The tags you need to render are all in the FatCloud.tags array. Each tag object has a label property as a string of the tag's value, and a scale property between 0 (smallest) and 1 (largest).
Skin options set at runtime are available from the FatCloud.options object, eg. FatCloud.options.textAngle etc. Don't worry about the user skipping options; defaults will be loaded from FatCloud.xml prior to instantiation.
The XML file's font list is loaded into the FatCloud.fonts array. Many fonts have internal names which differ from their visible names, so when assigning fonts to text fields, rather than simply using a font string, use FatCloud.fontName(FatCloud.fonts[x]) instead. This function will attempt to retrieve the internal name of the font, reducing the chance of a runtime error.
Your skin's tag focus needs to be synchronised with the DOM's focussed tag in order to function properly. Listen for the receiveDOMTagEvent event in your skin's root namespace, and call the tagFocus(), tagBlur() and tagSelect() functions when necessary. This isn't as hard as it sounds – check out the SimpleSkin class for clarification.

GUI Development

FatCloud can be run stand-alone or as a WordPress plugin, but you can also write a GUI for virtually any framework. Such development is beyond the scope of this manual, but you can check out the code of the wp_tag_cloud.php file for some good pointers.

If you use a PHPDoc-enabled IDE such as NetBeans or Eclipse, you can navigate fairly swiftly through the FatCloud::$skins and FatCloud::$fonts arrays; these two variables contain virtually all the information (parsed from FatCloud.xml when you include FatCloud.php) that you'll need.