dmTagPlugin

• In a console, from your project root dir, run:

git clone git://github.com/diem-project/dmTagPlugin.git plugins/dmTagPlugin  

• In config/ProjectConfiguration.class.php, add dmTagPlugin to the list of enabled plugins:

class ProjectConfiguration extends dmProjectConfiguration
{  
  public function setup()  
  {  
    parent::setup();  
 
    $this->enablePlugins(array(  
      // your enabled plugins  
      'dmTagPlugin'  
    ));  

• In a console, from your project root dir, run:

php symfony doctrine:generate-migrations-diff  

php symfony doctrine:migrate  

php symfony dm:setup  

DmTaggable Doctrine behavior

Declare a model as taggable

Article:  
  actAs:  
    DmTaggable:  
  columns:  
    title: { type: string(255) }  

As for any schema modification, you now need to run doctrine migrations, then dm:setup.

Managing Tags

We can manage the tags a record has by using a few simple functions.

• getTags() - Get the record tags
• hasTags() - Tells whether the record has tags
• getNbTags() - Get the number of tags the record has
• setTags() - Set the tags by specifying a list of tags separated by commas.
• addTags() - Add new tags to the existing set of tags by specifying a list of tags separated by commas.
• removeTags() - Remove tags from the existing set of tags by specifying a list of tags separated by commas.
• removeAllTags() - Remove all tags from the existing record.

Below we'll show examples of how we can use each of the above methods described.

Set Tags

We can easily set the tags by using the setTags() method. This method completely removes any existing tags then adds the tags you've specified. Below is an example.

$article = new Article();
$article->title = 'This is a sample article';  
 
$article->setTags('2010, symfony, doctrine')->save();  

Now internally setting that tags string would create any DmTag records that don't already exist in the database, and it would synchronize the associations between the Article and the DmTag records.

Adding Tags

We can add to the existing set of tags by using the addTags() method.

$article->addTags('new tag, diem')->save();

This will not affect any existing tag associations. It will only add new tags to the Article.

Removing Tags

Now if we wanted to remove an existing tag we can simply use the removeTags() method.

$article->removeTags('diem')->save();

Removing all Tags

Sometimes we may want to simply remove all the tags from a record. This can be done by using the removeAllTags() method.

$article->removeAllTags()->save();

All of the above methods of managing your tags don't persist the changes to the database until we call the save() method. Internally this method is adding/removing DmTag instances from the collection of Tags in the relationship. So the collection is not saved until we call save().

Related records

Records are related when they share at least one tag.

$article1->addTags('test')->save();
$article2->addTags('test')->save();  
 
// returns a collection of Article containing article2  
$article1->getRelatedRecords();  
 
// returns a collection of Article containing article1  
$article2->getRelatedRecords();  

Tagged records

We can get all records of a model, which have a given tag.
For example, to get all Article records which have the tag "release", we can do:

// Find the "release" tag
$tag = dmDb::table('DmTag')->findOneByName('release');  
// Get all articles tagged with "release"  
$articles = $tag->getRelatedRecords('Article');  

You can also get the doctrine query and fetch the records by yourself:

$query = $tag->getRelatedRecordsQuery('Article');
$articles = $query->where('r.is_active = ?', true)->fetchArray();  

Popular tags

Sometimes we may want to get all the tags that are the most popular across our content. This can be done easily enough by using the DmTagTable method named getPopularTags().

$tags = Doctrine::getTable('DmTag')->getPopularTags();

This returns a collection of DmTag instances with some additional aggregate data which calculates the number of time the tags have been used across all models, and how many times it has been used total across all models. The names of the added keys for our examples are the following.

• num_article
• total_num

By default the getPopularTags() methods returns the count for all models the behavior is enabled on. If we want to limit the models it returns results for then we can specify a single model to get the popular tags for or an array of models.

If we had the behavior enabled on multiple models. For example one other model named Photo. We could get the popular tags for one of the single model.

$tags = Doctrine::getTable('DmTag')->getPopularTags('Photo');

Or if you wanted to get the tags for multiple models you can specify an array.

$tags = Doctrine::getTable('DmTag')->getPopularTags(array('Article', 'Photo'));

Admin

Manage all tags

An admin interface is available in the Content->Tag menu.

Add tags to a record

If you have, let's say, an "Article" model which is taggable:

Article:  
  actAs:  
    DmTaggable:  
  columns:  
    title: { type: string(255) }  

You want to be able to apply tags to each article on the article admin interface.
It's possible by adding the "tags" field in the form configuration:
apps/admin/modules/article/config/generator.yml

      form:  
        display:  
          NONE: [title, tags]  

You should now have a autocompleter in the article admin forms, to help you applying existing and new tags to each article:

Front Pages & Widgets

List page

A dmTag/list page has been automatically created. You can find it the pages tree, in the front left panel.

List widget

To add a widget containing all tags inside, find the tag/list widget in the front "Add" menu, take it and drop it to the page.

Popular widget

To add a widget containing all popular tags, find the tag/popular widget in the front "Add" menu, take it and drop it to the page.

Show page

Also, each tag has a dmTag/show page to represent it.

Show widget

To add a widget containing the current tag for a dmTag/show page, find the tag/show widget in the front "Add" menu, take it and drop it to the page.

Create a widget to show articles related to a tag

Add a "listByTag" component to your article module in
config/dm/modules.yml

    article:  
      page:             true  
      components:  
        listByTag:      { filters: dmTag }  

Then generate the component by clicking the refresh button in the front tool bar.
Then, find the article/listByTag widget in the front "Add" menu, take it and drop it to the tag/show page.

Access the tag we filter with

When using a filtered list, the object we filter with is available in the component method, and the partial.
apps/front/modules/article/actions/components.class.php

public function executeListByTag()
{  
  // $this->dmTag;  
 
  $query = $this->getListQuery();  
 
  $this->articlePager = $this->getPager($query);  
}  

apps/front/modules/article/templates/_listByTag.php

// $dmTag;

Use tags to enhance the search engine

Diem internal search engine uses the HTML keywords meta tag to calculate page relevance. By using your records tags in the page keywords, you can improve a lot your search engine efficiency.
Suppose we have a "Article" model which act as DmTaggable. In your admin, open "Seo->Automatic Seo", then the "Article" tab. In the keywords input, add "%article.tags_string%":