README

About

Adds the possibility to assign tags to individual elements.

System requirements

• Contao 4.13 or newer

Installation & Configuration

• Install via Contao Manager or Composer (composer require numero2/contao-tags)

News

• Add the following code snippet into your news_(full|latest|short|simple).html5 template

  <?php if( $this->tags ): ?>
    <div class="tags">
      <?php foreach( $this->tags as $tag ): ?>
        <?= $tag; ?>
      <?php endforeach; ?>
   </div>
  <?php endif; ?>

• Configure your Newslist or Newsreader front end modules and set a Redirect page for tags (optional)

• Additionally add the News Tag Cloud module anywhere on your page

Events

• Add the following code snippet into your event_(full|list|teaser|upcoming).html5 template

  <?php if( $this->tags ): ?>
    <div class="tags">
      <?php foreach( $this->tags as $tag ): ?>
        <?= $tag; ?>
      <?php endforeach; ?>
   </div>
  <?php endif; ?>

  ⚠️ Note: Contao does not provide any Hooks for the Eventreader module, therefore we need to add some logic at the beginning of our template to parse the Tags correctly.

  <?php
  
  use Contao\ModuleEventReader;
  use Contao\ModuleModel;
  use Contao\System;
  
  $moduleModel = ModuleModel::findOneById(69); // replace with the ID of your actual EventReader module
  $module = new ModuleEventReader($moduleModel);
  
  $tagListener = System::getContainer()->get('numero2_tags.listener.events');
  $event = $tagListener->parseEvent($this->arrData, $module);
  
  $this->tags = $event['tags'];
  $this->tagsRaw = $event['tagsRaw'];
  
  ?>

• Configure your Eventlist or Eventreader front end modules and set a Redirect page for tags (optional)

• Additionally add the Events Tag Cloud module anywhere on your page

Insert-Tags

This extensions comes with a couple of Insert-Tags that can be used to link to a page which will only show entries with matching tags.

A more robust way for the links would be to use the tag's ID instead of its name (which can be changed under System › Tags). So instead of {{tag_link::1::foo}} you could also write {{tag_link::1::69}} (assuming the ID of foo is 69).

For Developers

Integrating a tags field in your own extension

If you want to use the tags for fields in your own Data Containers you can do so by defining the field as follows:

$GLOBALS['TL_DCA']['tl_my_extension']['fields']['my_tags'] = [
    'exclude'           => true
,   'inputType'         => 'select'
,   'foreignKey'        => 'tl_tags.tag'
,   'options_callback'  => ['numero2_tags.listener.data_container.tags', 'getTagOptions']
,   'load_callback'     => [['numero2_tags.listener.data_container.tags', 'loadTags']]
,   'save_callback'     => [['numero2_tags.listener.data_container.tags', 'saveTags']]
,   'eval'              => ['multiple'=>true, 'size'=>8, 'tl_class'=>'clr long tags', 'chosen'=>true]
,   'sql'               => "blob NULL"
,   'relation'          => ['type'=>'hasMany', 'load'=>'eager']
];

foreignKey, options_callbackand save_callbackare mandatory. In the eval section we add a class called tags - this is also needed for the JavaScript handling. There are some more options which can be defined in eval.

Eval-Options

Events

If you want to filter the tags shown in events and/or news, you can use the contao.tags_get_list event to modify the tags that will be used in the templates.

// src/EventListener/TagGetListListener.php
namespace App\EventListener;

use numero2\TagsBundle\Event\TagsEvents;
use numero2\TagsBundle\Event\TagsGetListEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(TagsEvents::TAGS_GET_LIST)]
class TagGetListListener {

    public function __invoke( TagsGetListEvent $event ): void {
        // …
    }
}