GitHub - majic3/tagging at 2f90f27847b2174aadd33eccc83a86eb144e6738

majic3 / tagging Public

forked from mariano/tagging

Notifications You must be signed in to change notification settings
Fork 1
Star 1

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

www.formation-cakephp.com

1 star 7 forks Branches Tags Activity

Star

Notifications

Branches Tags

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
config/sql		config/sql
controllers		controllers
locale		locale
models		models
vendors		vendors
views		views
README		README
tagging_app_controller.php		tagging_app_controller.php
tagging_app_model.php		tagging_app_model.php

Repository files navigation

Multi-model tagging plugin for CakePHP.

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' directory.
	
	1.2. DB tables
	--------------
	Create two db tables as described in tagging/config/sql/tagging.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 code comments for options.
		
3. MANAGING TAGS
=================
Go to URL /admin/tagging: you can add a tag or view existing tags.

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' => false,
				'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>
			...
		</ul>
		
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/tags/view.ctp
	
	Tag data available in $data.
	
	6.2 List tags
	-------------
	Default URL: /tagging/tags
	
	You have to create a view for this action, in {app}/views/tags/index.ctp
	
	Tags 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