

flf flashcloud for Coppermine - version 1.1

requires COPPERMINE version 1.5.2(tell me, if it works with older versions)
(  Rev >7225 required for search page inclusion )
==============================================================================================================
brickware - released free of charge
==============================================================================================================
This plugin is released free of charge under the Attribution-Noncommercial-Share Alike 3.0 Unported License.
I coded this plugin, because I had fun doing it, not because I want to make money out of it.
However, writing good code is a time consuming effort that limits the time you can 
spend with your loved ones. I share the work, because I believe it can be of good use 
to others so that they can spend an afternoon with their partners or kids instead
of writing something similar themselves.

I'm not asking for something in return. But if you do like this plugin and want to 
appreciate a little bit of the time I put into it, my son would be happy if you could add
to his LEGO(tm) collection. So I call this plugin "brickware" - send him some of your used 
(but preferably still usable!) LEGO(tm) parts, modules, anything. A single brick will do just 
the same as the big Millenium Falcon in mint condition ;-).
So if you have some unused LEGO(tm) bricks (parts from the LEGO(tm) space collection preferrably) 
that you want to give freely in appreciation for the use of this plugin, please send them with regular mail to:

	Florian Lechner
	29589255
	Packstation 103
	D-85057 Ingolstadt
	Germany

Leave your email-address and I'll send you a thank-you picture of your bricks in action.
==============================================================================================================
Credits
==============================================================================================================
- The original tagCloud was taken from http://downloads.wordpress.org/plugin/wp-cumulus.zip, Author: Roy Tanck
  http://www.roytanck.com. The original flash source file is packed with this plugin as required by the author.
- The basic font size distribution algorithm was found on 
  http://www.php.de/php-fortgeschrittene/44928-tag-cloud-algorithmus-fuer-schriftgroessye.html and created by
  http://simbo.de

==============================================================================================================
History
==============================================================================================================
v1.1	[B] fixed a wrong link to the include file
        [A] you can now show the cloud on the regular coppermine search page (requires coppermine version >1.5.2 Rev7225)
		[B] fixed the link to the readme file
v1.0	[A] Initial release	  


[A] = Added new feature
[B] = Bugfix (fix something that wasn't working as expected)
[C] = Cosmetical fix (layout, typo etc.)
[D] = Documentation improvements
[M] = Maintenance works
[O] = Optimization of code
[S] = Security fix (issues that are related to security)

==============================================================================================================
Installation & Configuration
==============================================================================================================
Install plugin with COPPERMINE Plugin Manager.
Edit configuration before first running the tool!
Make sure, the file /plugins/flf_flashcloud/cloud_data.xml is writable by your webserver user. Depending on your 
webserver setup change the rights to '0775' or '0777'. When you install with the plugin manager, 
this step should not be necessary.

If you want to use the new hook-mechanism to show the cloud on the search page, you have to download the most
current developer version of coppermine, as the publicly released version does not offer this plugin support yet.
If you don't want to upgrade your entire system, you can also hack the file "search.php" the following way:

Add the following lines at the position where you want to include the cloud:
    $text = CPGPluginAPI::filter('searchtag_include', $text);
	echo $text;
	
Make sure, you set the configuration accordingly.


==============================================================================================================
Upgrading
=============================================================================================================
not applicable
  
==============================================================================================================
What it does
=============================================================================================================
This plugin generates a web 2.0 style moving flash cloud of all the tags to the images insided your database.
The tags of all images are counted and weighed with an logarithmic algorithm to get a proper distribution 
(tags that are counted more are given a bigger font etc.)
In total, there are up to 10 distinguished sizes (it's always up to your specific tag distribution). Play around
with the parameters in the configuration settings a bit to see the different effects (max size, min size, threshold
etc.) You can define a specific color for each of the 10 sizes. (Color 10 being the color for the biggest font, 1 
for the smalles font). Additionally you can define one highlight color, when you hover over a tag.

Currently, there is only one big system-wide tag cloud from all your images in your library. Because of this, 
I added a function to where you can define, whether you want to hide tags from private files, i.e. files 
that are in a protected album.

If you have many images with many tags you will have thousands of items to cope with. The cloud will not be much use 
then, so I added a function where you can set the minimum amount of images that must have the same tag, before the
tag is added to the cloud. Experiment with it. Start out with 2 if you have a lot of images and see how your cloud
looks.

Upon clicking of a file, the coppermine search function is triggered, so even if you click on a tag of an image
that you are normally not allowed to see, you won't see the image after that.

The tag cloud can be generated on demand (via the plugin manager) or updated any time a picture is uploaded.

To display the cloud, you have three ways to show the cloud
a) make use of the "main_page_layout" Coppermine setting
   Enter the value "flashcloud" along the string in the proper position to display the cloud. For example:
   breadcrumb/catlist/alblist/random,2/lastup,2/flashcloud
   will let you see the cloud listed as the last entry of your startpage.
b) You can reference in your own theme to a page, that only consists of the cloud page. Just call
	http://<yoursite><yourpathtocoppermine>/index.php?file=flf_flashcloud/testdrive
	For an example come visist www.lounge-lizard.org/cms/coppermine/index.php?file=flf_flashcloud/testdrive
c) Use the parameter to display the cloud on the Coppermine search-page. You can decided whether you want to 
   display the cloud below or above the search text fields. Note: This feature requires a new hook that had not
   been implemented in the publicy release 1.5.2-code. Please upgrade to the latest Coppermine version from SVN,
   to have code revision 7225 or higher.
==============================================================================================================
Things on my To-Do-List
==============================================================================================================
- Think of a way how to generate user-specific clouds including tags for images only the specific user may see

==============================================================================================================

 2010 Florian Lechner - http://lounge-lizard.org/cms

flf histotag by http://lounge-lizard.org is licensed under a Attribution-Noncommercial-Share Alike 3.0 Unported License.
visit http://creativecommons.org/licenses/by-nc-nd/3.0/ for more details.