GitHub - majic3/tagging at 2245372f9d4b313a920406b8e0bd712d34fe5462

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 13 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' folder.
	
	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.

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 app, 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' => 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>
			...
		</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 $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
	
	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