The Tag class is a set of tools for adding, removing, editing, and displaying tags on objects. It is used throughout HUB installations for adding tags to such things as resources, users, events, and more.

When properly extended, Tags gives you all of the basic functions you need for managing and retrieving tag records in the database table.

All tags are stored within a single table called "#__tags". The information that associates a particular tag to a specific user, event or group, is stored in a table called "#__tags_object". Storing the association data separate from the tag itself allows for a tag to be represented once but be connected to multiple items. If that tag is ever changed for any reason, it will be represented the same regardless of what object it is attached to.

The #__tags_object table stores, among other things, such data as the unique ID of the tag, the unique ID of the object being tagged, and what component (or, potentially, table) that object belongs to.

Here we have two entries that both link to a tag with an ID of "6" and both with object IDs of "77". One entry is a resource and the other is an event. The "tbl" field is the most important distinguishing factor; This allows us to have multiple objects with the same object ID, linking to the same tag but not create a conflict.

To use Tags, create an extension of the class. In this example, we're adding tags to our "com_example" objects.

<?php
namespace Components\Example\Models;

use Components\Tags\Models\Cloud;

require_once \Component::path('com_tags') . DS . 'models' . DS . 'cloud.php';

class Tags extends Cloud
{
	/**
	 * Object type, used for linking objects (such as resources) to tags
	 * 
	 * @var string
	 */
	protected $_scope = 'example';
}

Assign to $_scope the name to be used to uniquely identify tag data as belonging to your specific component.

Once the class is created and in place, it can be included and instantiated

Create/Update

// Retrieve posted tags (comma delimitated string)
$tags = Request::getVar('tags', '');

// Instantiate the tagging class
$cloud = new \Components\Examples\Models\Tags($object_id);

// Tag the object
// $user_id will typically be the current logged in user or User::get('id);
$cloud->setTags($tags, $user_id);

This method is the same for both adding tags to a previously untagged object and updating the existing list of tags on an object.

Read

render('string')

Returns a string of comma-separated tags.

// Instantiate the tagging class
$et = new \Components\Examples\Models\Tags($object_id);

// Get a tag cloud (HTML List)
echo $et->render('string');

will give:

My Tag, Your Tag, Their Tag

render()

Returns a tag cloud, derived of a an HTML list. Each tag is linked to the Tags component and comprises one list item. A CSS class of "tags" on the list allows for styling.

// Instantiate the tagging class
$et = new \Components\Examples\Models\Tags($object_id);

// Get a tag cloud (HTML List)
echo $et->render();

will give:

<ol class="tags">
	<li><a class="tag" href="/tags/mytag">My Tag</a></li>
	<li><a class="tag" href="/tags/yourtag">Your Tag</a></li>
	<li><a class="tag" href="/tags/theirtag">Their Tag</a></li>
</ol>

render('array')

Returns an array of associative arrays.

// Instantiate the tagging class
$et = new \Components\Examples\Modes\lTags($object_id);

// Get a tag cloud (HTML List)
$tags = $et->render('array');
print_r($tags);

will give:

Array ( 
	[0] => Array ( 
			[tag] => 'mytag'
			[raw_tag] => 'My Tag'
			[tagger_id] => 32
			[admin] => 0
	) 
	[1] => Array ( 
			[tag] => 'yourtag'
			[raw_tag] => 'Your Tag'
			[tagger_id] => 32
			[admin] => 0
	)
	[2] => Array ( 
			[tag] => 'theirtag'
			[raw_tag] => 'Their Tag'
			[tagger_id] => 32
			[admin] => 0
		)
)

To make adding tags and editing a list of existing tags in a form, HUBzero offers a Tag Editor plugin. To use the plugin in a view, do the following:

// Trigger the event
$tf = Event::trigger( 'hubzer.onGetMultiEntry', array(array('tags','tags','actags','',$tags)) );

// Output
if (count($tf) > 0) {
	echo $tf[0];
} else {
	echo '<input type="text" name="tags" value="'. $this->escape($tags) .'" />';
}

The first parameter passed ('tags') tells the plugin that you wish to display a tags autocompleter. The nest parameter is the name of the input field. The third is the ID of the input field. The fourth is any CSS class you wish to assign to the input. The $tags variable here must be a string of comma-separated tags.