Skip to content
/ tagging Public
forked from mariano/tagging

Multi-model tagging plugin for CakePHP (adapted for Wildflower)

www.formation-cakephp.com
1 star 7 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

majic3/tagging

BranchesTags
 
 

Repository files navigation

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

About

Multi-model tagging plugin for CakePHP (adapted for Wildflower)

www.formation-cakephp.com

Resources

Readme
Activity

Stars

1 star

Watchers

2 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • PHP 100.0%