Taggable ¶

1. Requirements
2. Key differences with TaggableBehavior extension from YiiExt
3. Public properties
4. Configuration examples
5. Public methods
6. Resources

Behaviour for CActiveRecord that allows to attach tags to a model.

License: The BSD 2-Clause License

Package: ext.Su_MpaK.Taggable.behaviours

Inheritance: class Taggable >> CActiveRecordBehavior >> CModelBehavior >> CBehavior >> CComponent

Version: 1.11.01.01

There are two version tags:

• v1.11.01.01-release - Pure extension code that is ready to be used in project.
• v1.11.01.01-demo - Additionaly contains demo DB schema, demo models, readme file and license.

Requirements ¶

Yii 1.1.1 or above.

Key differences with TaggableBehavior extension from YiiExt ¶

• It uses ActiveRecord model for tag representation
• Interface functions are sligtly different, they are not strictly tied to string parameters. You can pass any number of arguments that can be typecasted to string.

Public properties ¶

tagModel ¶

public string $tagModel

Tag model path alias.

Will be passed as 'class' attribute value to Yii::createComponent().

tagTableTitle ¶

public string $tagTableTitle = 'title'

The field name which contains tag title.

Will be passed to CActiveRecord::getAttribute().

tagRelationTable ¶

public string $tagRelationTable

The name of relation table.

By default will be '{modelTableName}_{tagTableName}'.

tagRelationTableTagFk ¶

public string $tagRelationTableTagFk

The name of attribute in relation table which recalls tag.

By default will be '{tagTableName}Id'.

tagRelationTableModelFk ¶

public string $tagRelationTableModelFk

The name of attribute in relation table which recalls model.

By default will be '{modelTableName}Id'.

tagsSeparator ¶

public string $tagsSeparator = ','

Separator for tags in strings.

Configuration examples ¶

Minimal configuration ¶

class User extends CActiveRecord {
    ...
 
    public function behaviors() {
        return Array(
            'tags' => Array(
                'class' => 'ext.Su_MpaK.Taggable.behaviours.TaggableBehaviour',
 
                // Tag model path alias.
                'tagModel' => 'Tag'
            )
        );
    }
 
    ...
}

Complete configuration ¶

class User extends CActiveRecord {
    ...
  
    public function behaviors() {
        return Array(
            'tags' => Array(
                'class' => 'ext.Su_MpaK.Taggable.behaviours.TaggableBehaviour',
 
                // Tag model path alias.
                'tagModel' => 'Tag',
 
                // The field name which contains tag title.
                'tagTableTitle' => 'title',
 
                // The name of relation table.
                'tagRelationTable' => 'tbl_user_tag',
                 
                // The name of attribute in relation table which recalls tag.
                'tagRelationTableTagFk' => 'tagId',
 
                // The name of attribute in relation table which recalls model.
                'tagRelationTableModelFk' => 'tbl_userId',
 
                // Separator for tags in strings.
                'tagsSeparator' => ','
            )
        );
    }
  
    ...
}

Configuration for different types of tags ¶

class User extends CActiveRecord {
    ...
  
    public function behaviors() {
        return Array(
            'tags' => Array(
                'class' => 'ext.Su_MpaK.Taggable.behaviours.TaggableBehaviour',
  
                // Tag model path alias.
                'tagModel' => 'Tag'
            ),
 
            'categories' => Array(
                'class' => 'ext.Su_MpaK.Taggable.behaviours.TaggableBehaviour',
  
                // Category tag model path alias.
                'tagModel' => 'Category'
            ),
        );
    }
  
    ...
}
 
...
 
$user->tags->add( 'test, test1', 'test2' );
$user->categories->add( 'cat1', Array( 'cat2, cat3', 'cat4' ) );
 
$user->save();
 
...

Public methods ¶

add ¶

public CActiveRecord add( $... )

Attaches tags to model.

Can be called with any number of arguments of any type. Only constraint is that Object arguments should have __toString defined (Not applicable to instances of tag model).

Usage example:

$user->tags->add( 'test', Array( 'admin', 10 ), $user )->save();
 
// This code will attach to the model following tags: 'test', 'admin', '10', 'User_1' ($user->__toString())

get ¶

public CMap get( CDbCriteria $additionalCriteria = null )

Returns all attached to the model tags.

Parameters:

additionalCriteria - Additional DB criteria to filter attached tags. Will be passed to CDbCriteria::mergeWith().

Usage example:

$tagsList = $user->tags->get(); 

has ¶

public bool has( $... )

Checks whether or not specified tags are attached to the model.

Can be called with any number of arguments of any type. Only constraint is that Object arguments should have __toString defined (Not applicable to instances of tag model).

Returns true only if ALL specified tags are attached to the model.

Usage example:

// if tags 'test', 'admin' и '10' are attached to the user
if ( $user->tags->has( 'test', Array( 'admin' ), 10 ) ) {
    ...
}

remove ¶

public CActiveRecord remove( $... )

Detaches specified tags from the model.

Can be called with any number of arguments of any type. Only constraint is that Object arguments should have __toString defined (Not applicable to instances of tag model).

Usage example:

$user->tags->remove( 'test', Array( 'admin', 10 ), $user )->save();
 
// This code will detach from the user follwoing tags: 'test', 'admin', '10', 'User_1' ($user->__toString())

reset ¶

public CActiveRecord reset( void )

Detaches all tags from the model.

Usage example:

$user->tags->reset()->save();

set ¶

public CActiveRecord set( $... )

Attaches to the model specified set of tags that will replace all previous ones.

Can be called with any number of arguments of any type. Only constraint is that Object arguments should have __toString defined (Not applicable to instances of tag model).

Usage example:

// attaching of tags 'test', 'admin', '10'
$user->tags->add( 'test', Array( 'admin', 10 ) );
 
// removing all previously attached tags ('test', 'admin', '10')
// and attaching new ones: 'newTest', 'Array' и 'blah'
$user->tags->set( Array( 'newTest', Array( 11 ) ), 'blah' )->save();

taggedWith ¶

public CActiveRecord taggedWith( $... )

Modifies the model DB criteria in order to find models with any of specidied tags attached.

Can be called with any number of arguments of any type. Only constraint is that Object arguments should have __toString defined (Not applicable to instances of tag model).

Model will be selected if it has AT LEAST ONE of the specified tags attached.

Usage example:

$userList = User::model()->tags->taggedWith( 'test, admin' )->findAll();

__toString ¶

public string __toString( void )

Allows all attached to the model tags to be printed imploded by separator.

// attaching of tags 'test', 'admin', '10'
$user->tags->add( 'test', Array( 'admin', 10 ) );
 
print $user->tags;
 
// will be printed: 'test,admin,10'

Resources ¶

• Forum topic
• GitHub Repository
• Russian documentation

Any feedback will be much appreciated.