Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
260 lines (198 sloc) 7.32 KB
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