Getting the Most out of the Wolfe Candy Tag Cloud Generator

Introduction

The Tag Cloud generator creates a tag cloud at the point in a page or post that it is required using short code.

Settings can be set using short-code arguments. If provided then these will also override any default settings so that a tag cloud can be altered on a post by post or page by page basis.

Settings

The following are the default settings that influence how a tag cloud is created and displayed. These settings can be overridden by passing short-code arguments or POST URL arguments.

Installation

Follow the usual Wordpress instructions to install the plugin files. Either copy a ZIP archive of the plugin folder contents into the Wordpress plugins folder or install it directly from the Wordpress repositiory.

Shortcode

Use [tag-cloud] to show a tag cloud using default settings, short-code args, POST or GET URL args e.g. https://.....page.php?[arg]=xxxx.

Use [tag-cloud [arg1]="xxxxxxxx" [arg2]="xxxxxxxx"] to use short-code args.

style_box_color="LightGrey" : specify as text or hex

style_border_color="darkblue" : specify as text or hex

style_border_width="1px" : specify as pixels

style_box_width="75%" : specify as % to allow for mobile themes

style_box_padding="2px" : specify as pixels

style_font_color="#4F5AA1" : must be in hex if it needs to be randomised or shaded

style_min_font_size=10

style_max_font_size=35 : Increasing this will make the text larger, decreasing will make it smaller

style_set_font="" : set a font for all tags or else they will be randomly selected between "Arial", "Arial Narrow", "Times", "Helvetica", "Calibri", "Verdana", "Courier", "Candara", "Geneva", "Optima", "Cambria", "Garamond", "Didot", "Perpetua", "Copper Plate". NB: defaults to "Arial" if font specified is not supported by the browser.

style_random=true : randomise with italics and bold text

style_shade_spread=25 : if "random shade" is true then this is the random rgb value spread of the shading - this only works if color is specified in hex format

style_shade_random=true : randomise the text shade/tints

style_color_random=true : choose random base color

style_multi_random=true : choose random base color each time

style_tag_separator=" " : the characters that divide each tab

list_random=true : list in a random order or in the array order

list_vertical=true : include vertical text

list_use_ratings=false : use ratings in an array to specify size (false = random)

list_max=100 : max number of tags to be displayed

return_url="current" : URL of return page for links - blank for no link, "current" if return to current page

tag_list_mode="" : specify the taxonomy to use. The default is "post_tag" but can be set for any taxonomy.

Recommendations

This plugin can make use of the Wolfe Candy Tool Suite framework. If active, the Settings/Wolfe Candy Settings provides and interface where all the shortcode settings are configurable via the Admin dashboard.

Wordpress Developers

The tag cloud is a class that is initiated using $tag_cloud = new WlfC_TagCloud;. The args listed in the shortcode above are available $tag_cloud->[arg]. In addition to these, the following are available programatically:

$tag_cloud->SetDefaults($_atts); to be called within any shortcode function and passes the shortcode arguments through.

$tag_cloud->GetDefaults(); returns an array of factory defaults and setting options that can be used in a shortcode function e.g. $atts = shortcode_atts( $tag_cloud->GetDefaults(), $_atts );.

The main list of tags is stored in $tag_cloud->tag_list;. This is an array in the following format so you can pass the tag array directly to the class.

$tag_cloud->tag_list = array(
@nbsp; 'tag1'=>array('link'=>'URL1', 'rating'=>'10'),
@nbsp; 'tag2'=>array('link'=>'URL2', 'rating'=>'5'),
@nbsp; 'tag3'=>array('link'=>'URL3', 'rating'=>'9'),
@nbsp; 'tag4'=>array('link'=>'URL4', 'rating'=>'9')
);

$tag_cloud->AddTag('[name]','[rating]','[link]'); is used to add a tag to the list. This can also be used to start a list. [rating] and [link] are optional.

$tag_cloud->GetSelected(); function sets the argument $tag_cloud->selected_tag; as the name of the last tag selected which can be used programmatically locally to process a clicked tag.

$tag_cloud->SetURL(); sets the $tag_cloud->return_url to the current page - which is the same as setting it to "current"

$tag_cloud->SetWPTags([taxonomy]); returns an array in tag cloud format of all Word Press tags and links for the specific taxonomy (e.g. "post_tag" or "category"). This means it can be used to tag cloud all types of custom post objects. The taxonomoy defaults to "post_tag". It returns unassigned tags . It also resets the $tag_cloud->tag_list; to be the Word Press Tags array.

$tag_cloud->GetHTML(); returns the HTML code for the tag cloud. It is blank if the tag array is empty.

$tag_cloud->color_name_to_hex("color") is a utility function in the class to turn text colors into hex values

$tag_cloud->strRGB("hex", "r") is a utility function in the class to return either the r, g or b element of a hex colour

$tag_cloud->random_base_color() is a utility function in the class to return a random hex colour

$tag_cloud->random_color("hex") is a utility function in the class to return a random shade of a specified hex colour

The Small Print....

This plugin software is released under the GPLv2 (or later) GNU General Public License from the Free Software Foundation. Please check restrictions on commercial use or purchase a commercial license.

Donate if you are able to so that the plugins can be maintained and enhanced - especially if you use it and find it useful! Feature enhancements can be paid for or requested (BTW they are considered high priority when coming from a donator!). If everyone donated just $1 for every download they use, it keeps the development going!

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

This plugin comes without support unless the licence or enhanced support is explicitly stated as provided.

The plugin is installed at the user's own risk. No liability is accepted for any damage to data or any consequential damage whatsoever when using this plugin. In any event this is strictly limited to the annual license fee paid.

Do not expect the code to be top quality. Much of the designs evolve from MVP and often there is redundant code in the files. Most of the code is commented but isnt always consistent. Some of the functions are not as optimised as they could be or the code as well written or structured as it could be. Some chunks of code are commented out for future use. Tinker with it all at your own peril.

However the code is written with passion - and it works!

Please provide honest feedback and ratings so that the plugin user commmunity can grow.

Any support issues, feature requests or queries can be emailed to Wolfecandy@ruralcheshire.co.uk. A response is not guaranteed but our head developer, Jrack Wolfe is keen to hear from you.