66 users Sign-in to change your status

This behavior permits to attach tags to Propel objects. It includes tag-clouds generation and helpers to display these clouds. Behavior

• Repository
• Download package
• Browse source

Developers

Name	Status	Email
Xavier Lacot	lead	gro.tocal <<ta>> reivax

License

Copyright (c) 2007 Xavier Lacot

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Releases for sf 1.2

Version	License	API	Released
0.9.0beta	MIT license	0.9.0beta	22/12/2008

Releases for sf 1.1

Version	License	API	Released
0.9.0beta	MIT license	0.9.0beta	22/12/2008
0.8.1beta	MIT license	0.8.1beta	22/09/2008
0.7.0beta	MIT license	0.7.0beta	16/07/2008
0.6.0beta	MIT license	0.6.0beta	10/05/2008
0.5.0beta	MIT license	0.5.0beta	21/03/2008

Releases for sf 1.0

Version	License	API	Released
0.9.0beta	MIT license	0.9.0beta	22/12/2008
0.8.1beta	MIT license	0.8.1beta	22/09/2008
0.7.0beta	MIT license	0.7.0beta	16/07/2008
0.6.0beta	MIT license	0.6.0beta	10/05/2008
0.5.0beta	MIT license	0.5.0beta	21/03/2008
0.4.0beta	MIT license	0.4.0beta	11/12/2007
0.3.0beta	MIT license	0.3.0beta	02/07/2007
0.2.0beta	MIT license	0.2.0beta	27/06/2007
0.1.0beta	MIT license	0.1.0beta	21/05/2007

Join this plugin team

Other releases

Release 0.9.0 - 22/12/2008

Release 0.8.1 - 22/09/2008

Release 0.7.0 - 16/07/2008

Release 0.6.0 - 10/05/2008

Release 0.5.0 - 21/03/2008

Release 0.4.0 - 11/12/2007

Release 0.3.0 - 02/07/2007

Release 0.2.0 - 27/06/2007

Release 0.1.0 - 21/05/2007

sfPropelActAsTaggableBehaviorPlugin

Introduction

This behavior permits to attach tags to Propel objects. It includes tag-clouds generation and helpers to display these clouds.

Features

• add/remove tag(s) on an object
• multi-tags object search
• multi-models selection
• tag cloud generation
• related tags handling
• unit-tested

Philosophy of the stuff

• taggable objects must have a primary key
• tags are saved when the object is saved, not before
• one object cannot be tagged twice with the same tag. When trying to use twice the same tag on one object, the second tagging will be ignored
• the tags associated to one taggable object are only loaded when necessary. Then they are cached.
• once created, tags never change in the Tag table. When using replaceTag(), a new tag is created id necessary, but the old one is not deleted.

Get it installed

• go to your project's root

• Install the plugin:

   ./symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsTaggableBehaviorPlugin
  

• if not already done, enabled behaviors in config/propel.ini:

   propel.builder.addBehaviors = true
  

• edit the classes that you want to make taggable. For instance, for lib/model/Post.php:

  [php] addTag('toto'); $post->addTag('tata, tutu'); $post->addTag(array('Titi', 'Gros Minet')); $post->save(); ### Retrieving one object's tags It is possible to retrieve tags from a taggable object: [php] getTags(); foreach ($tags as $tag) { echo $tag.'
  '; }

Removing one object's tags

Of course, tags can also be removed:

<?php
$post = PostPeer::retrieveByPk(1);
$post->removeTag('toto');
$post->removeTag('toto, tutu');
$post->removeAllTags();

Tags cloud generation

The plugin also proposes methods and helpers for generating tags cloud:

<?php
// gets the popular tags
$tags = TagPeer::getPopulars();
 
// display the tags cloud. The tags will use the route name "@tag" which tags 
// the request parameter "tags"
echo tag_cloud($tags, '@tag?tags');

The default size of the tag cloud is 100 items, but this value might be tweaked in app.yml:

all:
  tags:
    limit:   50

When you click on a tag in a tag cloud, you will want to get a list of objects that have been tagged with that tag. But sometimes, it happens that this tag is so popular that you can not find the resource you were searching for. Related-tags clouds are helpful for refining your request, as they provide a way to add an other tag to the request:

<?php
// get the tags related to "toto" and "tutu", for the model "Post" only
$tags = TagPeer::getRelatedTags('toto,tutu', array('model' => 'Post'));
 
// displays the related tags cloud, using the route "@post_tags" with the 
// request parameter "tags"
echo related_tag_cloud($tags, '@post_tags?tags=', 'toto,tutu');

Specialize your tag clouds

The tag retrival mecanism is fully based on Criterias, so it is easy to pass several restrictions. For instance, for retrieving popular tags over posts created in March 2007:

<?php
$c = new Criteria();
$c->addJoin(PostPeer::ID, TaggingPeer::TAGGABLE_ID);
$c->add(PostPeer::CREATED_AT, '2007-03%', Criteria::LIKE);
$tags = TagPeer::getPopulars($c, array('model' => 'Post'));
echo tag_cloud($tags, '@tag?tags=');

Avoid performance problems

In case you want to display a long list of taggable objects with their associated tags, you might want first to preload these objects's tags: it avoids to load tags per object, and gets all tags in a few requests.

<?php
$posts = TagPeer::getTaggedWith('toto,tutu', array('model' => 'Post'));
sfPropelActAsTaggableBehavior::preloadTags($posts);
 
foreach ($posts as $post)
{
  echo $post-getTitle();
 
  // won't require one request at each loop, as tags have been preloaded.
  var_dump($post-getTags());
}

Plugin internals

The plugin associates a parameterHolder to Propel objects, with 3 disjoin namespaces: * tags: tags that have been attached to the object, but not yet saved. Contract: tags are disjoin of (saved_tags union removed_tags) * saved_tags: tags that are presently saved in the database. Contract: removed_tags are disjoin of (tags union saved_tags) * removed_tags: tags that are presently saved in the database, but which will be removed at the next save(). Contract: removed_tags are disjoin of (tags union saved_tags)

When required, the saved_tags namespace is filled with the tags previously present in the database. The tagging methods have an action on these three namespaces, which are serialized in the database after the Propel object gets saved.

What is done when adding a tag ?

• if the tag is present in the "removed_tags" namespace, the tagging request is interpreted as a tag-removal revert. The tag is then deleted front the "removed_tags" request, and brought back into "saved_tags".
• else, if the tag is not present in the "saved_tags" namespace, add it to the "tags" one.

What is done when removing a tag ?

• if the tag has not yet been saved, simply remove it from the "tags" namespace.
• if he has been saved, remove it from the "saved_tags" namespace, and add it to the "removed_tags" one.

API

The behavior implement the following methods: * addTag($tagname) - Adds one or several tags to an object * getTags() - Returns the list of the tags attached to the object * hasTag($tag = null) - Returns true if the object has a tag. If a tag ar an array of tags is passed in second parameter, checks if these tags are attached to the object * removeTag($tagname) - Removes a tag or a set of tags from the object. * replaceTag($tagname, $replacement = null) - Replaces a tag with an other one.

The behavior class also implement the following method, which is a facility for preloading all the tags for a set of taggable objects * preloadTags($objects) - Preload tags for a set of objects

Unit testing

The plugin has been deeply unit-tested, if not fully. The tests are located in test/unit/sfPropelActAsTaggableBehaviorTest.php. If you want to run them: * install the plugin * configure a model for using it, for instance "Post" * copy the test file to /path/to/your/project/test/unit/sfPropelActAsTaggableBehaviorTest.php * edit this file and modify line 3:

     define('TEST_CLASS', 'Post');

• run the tests:

   ./symfony test-unit sfPropelActAsTaggableBehavior
  

License and credits

This plugin has been developed by Xavier Lacot and is licensed under the MIT license. Thanks to Tristan Rivoallan for the improvement suggestions.

Todo

• abstract primary keys handling. For the moment, primary keys are supposed to be named "ID"
• improve TagsHelpers (particularly, routing logic)