Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Multi-model tagging plugin for CakePHP

branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README
Multi-model Tagging plugin for CakePHP.

This plugin provides an easy to install solution for tagging any Model of your application.

Features :
* Easy install : download the files and create 2 db tables, no matter how many Models you want to tag.
* To tag a Model, add an input field in your forms : a simple text input or an advanced one with existing tags suggested as you type.
* Includes a Behavior that adds methods to linked Models to find record's tags, related records that share the most tags, etc.
* Build and display tag clouds, with a total control of the tags you want to retrieve and how you want to display them.

1. INSTALLATION
===============

	1.1. Files
	----------
	To install, copy the 'tagging' directory to the 'plugins' folder:
	
	git clone git://github.com/kalt/tagging.git
	
	Or click 'download' and copy the content of the zip file into your 'plugins' folder.
	
	1.2. DB tables
	--------------
	Create two db tables as described in tagging/config/sql/tagging.sql
	
	Or run this in console:
	cake schema run create Tagging -path plugins/tagging/config/sql

2. BASIC SETUP
==============

	2.1. Models
	-----------
	class Article extends AppModel
	{
		var $actsAs = array('Tagging.Taggable');
	}
	
	2.2. Controllers
	----------------
	class ArticlesController extends AppController
	{
		var $helpers = array('Tagging.Tagging');
	}
	
	2.3. Views
	----------
	A single input field for comma-separated tags, in add/edit views.
	
		2.3.a. Classic input
		--------------------
		echo $form->input('tags');
		
		2.3.b. With ajax tag suggestions
		--------------------------------
		echo $tagging->input('tags');

		Requires jQuery in <head>
		
	That's it, you can tag any Model.
	
	See the wiki for more options : http://wiki.github.com/kalt/tagging
		
3. MANAGING TAGS
=================
Enable admin routing in /app/config/core.pp

Go to URL /admin/tagging: you can add a tag or view existing tags.

The default views here are very basic, they just had been baked with the cake "bake" shell.

If any of the default views in this plugin does not meet your needs, create your own and place it 
in your own app folder, in {app}/views/plugins/tagging/{controller name}/{view name}.ctp

For example, if you want to customize the admin list of tags, simply create your own in:
{app}/views/plugins/tagging/tags/admin_index.ctp

4. FINDING TAGS
================

	4.1. Record's tags
	------------------
	class ArticlesController extends AppController
	{
		function view($id)
		{
			$this->Article->id = $id;
			
			$article = $this->Article->read();
			
			$article_tags = $this->Article->findTags();
			
			$this->set(compact('article', 'article_tags')); 
		}
	}
	
	4.2. Record's related records (same Model)
	------------------------------------------
	class ArticlesController extends AppController
	{
		function view($id)
		{
			$this->Article->id = $id;
			
			$article = $this->Article->read();
			
			// Find 5 related Articles :
			$related_articles = $this->Article->findRelated(true, 5);
			
			$this->set(compact('article', 'related_articles')); 
		}
	}
	
	4.3. Record's related records (all Models)
	------------------------------------------
	class ArticlesController extends AppController
	{
		function view($id)
		{
			$this->Article->id = $id;
			
			$article = $this->Article->read();
			
			// Find 5 related Ressources :
			$related_ressources = $this->Article->findRelated(false, 5);
			
			$this->set(compact('article', 'related_ressources')); 
		}
	}
	
5. TAG CLOUDS
=============

	5.1. Tag Cloud (Model specific)
	--------------------------------
	class ArticlesController extends AppController
	{
		function index()
		{
			$articles  = $this->Article->paginate();
			$tag_cloud = $this->Article->tagCloud();
			
			$this->set(compact('articles', 'tag_cloud')); 
		}
	}
	
	5.2. Tag Cloud (all Models)
	---------------------------
	class AppController extends Controller
	{
		var $uses = array('Tagging.Tag');
	
		function beforeRender()
		{
			$main_tag_cloud = $this->Tag->tagCloud();
			
			$this->set(compact('main_tag_cloud')); 
		}
	}
	
	5.3. Displaying tag clouds
	--------------------------
	
		5.3.a. Basic display
		--------------------
		echo $tagging->generateCloud($tag_cloud);
		
		Will output:
		<ul>
			<li><a href="/tagging/tags/view/tag1-slug" class="tag-size-7">Tag 1</a></li>
			<li><a href="/tagging/tags/view/tag2-slug" class="tag-size-2">Tag 2</a></li>
			<li><a href="/tagging/tags/view/tag3-slug" class="tag-size-5">Tag 3</a></li>
			...
		</ul>
		
		Note the 'tag-size-x' CSS class (with x, the 'scale factor', between 1 and 7 by default).
		
		5.3.b. Format cloud items with an element
		-----------------------------------------
		echo $tagging->generateCloud($tag_cloud, array('element' => 'cloud_item'));
		
		Element in views/elements/cloud_item.ctp:
		3 predefined values available :
		- $data: tag array
		- $scale: scale factor, from 1 to $options['max_scale'] (defaults to 7)
		- $percentage: scale factor from 0 to 100.
		
		<a href="/tagging/tags/view/<?php echo $data['Tag']['id']; ?>" style="font-size:<?php echo $scale; ?>em;">
			<?php echo $data['Tag']['name']; ?>
		</a>
		
		Will output:
		<ul>
			<li><a href="/tagging/tags/view/1" style="font-size:7em">Tag 1</a></li>
			<li><a href="/tagging/tags/view/2" style="font-size:2em">Tag 2</a></li>
			<li><a href="/tagging/tags/view/3" style="font-size:5em">Tag 3</a></li>
			...
		</ul>
	
		5.3.c. All output options
		-------------------------
		echo $tagging->generateCloud($tag_cloud, array(
			'max_scale' => 10,            // CSS class max scale
			'linkClass' => 'size-class-', // CSS class name prefix
			'element' => false,           // Element, see above
			'type' => 'div',              // Type of output 
			'id' => 'tag-cloud',          // DOM id for top level 'type'
			'class' => 'cloud',           // CSS class for top level 'type'
			'itemType' => 'span',         // type of item output
			'itemClass' => 'cloud-item',  // CSS class for items of type 'itemType'
			'url' => array(               // URL params
				'plugin' => null,
				'controller' => 'mytags',
				'action' => 'read',
				'pass' => array('id', 'slug'),
				'admin' => false
			)
		));
		
		Will output:
		<div id="tag-cloud" class="cloud">
			<span class="cloud-item"><a href="/mytags/read/1/tag1-slug" class="size-class-10">Tag 1</a></span>
			<span class="cloud-item"><a href="/mytags/read/2/tag2-slug" class="size-class-3">Tag 2</a></span>
			<span class="cloud-item"><a href="/mytags/read/3/tag3-slug" class="size-class-7">Tag 3</a></span>
			...
		</div>
		
6. BROWSING TAGS
================

	6.1 View tag
	------------
	Default URL: /tagging/tags/view/ followed by tag id, tag slug, or both in any order.
	
	You have to create a view for this action, in {app}/views/plugins/tagging/tags/view.ctp
	
	Tag data available in $tag.
	Paginated tagged records data available in $data.
	
	6.2 List tags
	-------------
	Default URL: /tagging/tags
	
	You have to create a view for this action, in {app}/views/plugins/tagging/tags/index.ctp
	
	Tag cloud data available in $data.

7. TRANSLATIONS
===============

	Available languages :
	- English
	- French
	Defaults to English.
	
	To change (for French for example), add this line in your app/config/bootstrap.php :
	Configure::write('Config.language', 'fre');
	
	To add a translation, open the file /tagging/locale/tagging.pot in PoEdit or equivalent, then save the 
	translation to /tagging/locale/{your language}/LC_MESSAGES/tagging.po 	
Something went wrong with that request. Please try again.