Mit der Methode getTemplateGroup ist es in einem Modul möglich, dem Nutzer im Backend die Auswahl von Templates zu ermöglichen, die im Frontend dann verwendet werden sollen. Damit ist es möglich, eigene Templates zu erstellen und zu verwenden.
Bis Contao 2.8.4 wurden die Templates im Verzeichnis templates des Moduls gesucht und anschließend im Verzeichnis TL_ROOT/templates.
Ab Contao 2.9 wurde auf Grund des Theme-Managers diese Methode erweitert, damit diese nun auch im Template Verzeichnis des Themes gesucht werden.

Hier nun beide Varianten kurz erläutert. Beide funktionieren dabei in Contao 2.9, die erste nur bis Contao 2.8.4

getTemplateGroup in Contao 2.8.x

In Contao 2.8.x (und früher) spielt es keine Rolle, an welcher Stelle man die Auswahl für ein Template einbaut, dass muss nicht beim Anlegen des Frontend Moduls sein.
Beispielsweise wird/wurde im Modul Banner unter dem Punkt Inhalte als erstes eine Kategorie angelegt, in dieser dann kam die Template Auswahl.
Dem Frontend Modul wurde dann eine Kategorie zugewiesen, über diese konnte das Modul dann das gewählte Template erfahren.

Tabellen Angaben

Zum Abspeichern benötigt man natürlich ein Feld in der jeweiligen Tabelle. Hier ein Auszug aus dem Banner Modul.
Für die Kategorie:

CREATE TABLE `tl_banner_category` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `tstamp` int(10) unsigned NOT NULL default '0',
...
  `banner_template` varchar(32) NOT NULL default '', 
...
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Für das Frontend Modul in tl_module:

CREATE TABLE `tl_module` (
...
  `banner_categories` varchar(255) NOT NULL default '',
...
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Dieses Felder müssen nun über die DCA Datei gesteuert werden.

DCA Angaben

In der DCA, hier "tl_banner_category.php", erfolgte nun im Abschnitt "fields" dieser Teil:

	'banner_template'            => array
	(
           'label'                   => &$GLOBALS['TL_LANG']['tl_banner_category']['banner_template'],
           'default'                 => 'mod_banner_list_all',
           'exclude'                 => true,
           'inputType'               => 'select',
           'options'                 => $this->getTemplateGroup('mod_banner_list_'),
           'eval'                    => array('tl_class'=>'w50')
	),

Hier ist nun ein Select Feld zu sehen, welches als Default das Template "mod_banner_list_all" nimmt. Gesucht werden Templates, welche mit "mod_banner_list_" beginnen und mit ".tpl" enden. Die Endung kann dabei hier nicht angegeben werden.
In dem Fall wird vom Framework zuerst im Verzeichnis "templates" vom Modul gesucht, anschließend im Verzeichnis "TL_ROOT/templates". Liegen im letzterem Templates mit gleichem Namen werden diese bevorzugt. Damit wurde die Möglichkeit geschaffen, updatesichere Templates auch für Module anzulegen, die keine Auswahlmöglichkeit bieten.
Der Name wird nach Auswahl und Speicherung in der Datenbank abgelegt und kann nun vom Frontend Modul ausgelesen werden.

Zuvor muss im Frontend Modul natürlich die Kategorie abgelegt werden, dazu auch hier eine DCA Field Angabe:

/**
 * Add fields to tl_module
 */ 
$GLOBALS['TL_DCA']['tl_module']['fields']['banner_categories'] = array
(
	'label'                   => &$GLOBALS['TL_LANG']['tl_module']['banner_categories'],
	'exclude'                 => true,
	'inputType'               => 'checkbox',
	'foreignKey'              => 'tl_banner_category.title',
	'eval'                    => array('multiple'=>true, 'mandatory'=>true)
);

Hier als Checkbox, da es die Möglichkeit geben sollte, mehrere Kategorien zu wählen.

Frontend Modul

Das Frontend Modul schaut nun per SQL nach, welches Template verwendet werden soll. Um beim Beispiel Banner Modul zu bleiben: erst wird die Kategorie ermittelt und damit dann das Template.
Wenn der Name des Templates vom Default abweicht, muss innerhalb der eigenen Methode "compile" das neue Template aktiviert werden.
Hier mal kurze Code Sequenzen, die das Ganze etwas deutlicher machen sollten.

class ModuleBanner extends Module
{
 
	/**
	 * Template
	 * @var string
	 */
	protected $strTemplate = 'mod_banner_list_all'; // Das Default Template wie in der DCA definiert
....
        /**
	 * Generate module
	 */
	protected function compile()
	{
            // Contao legt checkbox Felder als serialisiertes Array ab in der DB (darin die IDs der Kategorien)
            $this->arrBannerCategories = deserialize($this->banner_categories, true);  
 
...
            $objBanners = $this->Database->prepare("SELECT TLB.id FROM tl_banner AS TLB "
	                                            . " LEFT JOIN tl_banner_category ON (tl_banner_category.id=TLB.pid)"
	                                            . " WHERE pid IN(" . implode(',', $this->arrBannerCategories) . ")"
                                                    // und noch viel mehr, aber hier nicht wichtig :-)
					 ->execute();
...
 
 
            //Wenn nötig, dann neues Template aktivieren
	    if (($objBanners->banner_template != $this->strTemplate) && ($objBanners->banner_template != '')) 
            {
	              $this->strTemplate = $objBanners->banner_template;
	              $this->Template = new FrontendTemplate($this->strTemplate);
	    }
 
        }
 
}

So bekommt also das Frontend Modul über einige Ecken den Namen des Templates.

Natürlich kann man die Template Auswahl direkt im Frontend Modul machen. Das und die Änderung für Contao 2.9 zeigt der nächste Abschnitt.

getTemplateGroup in Contao 2.9.x

In Contao 2.9 ist es möglich in der Theme Konfiguration ein eigenes Template Verzeichnis zu definieren. Technisch gesehen ist es ein Unterverzeichnis von "TL_ROOT/templates". Da diese Templates sich auf das Theme beziehen, muss auch die Auswahl innerhalb eines ermittelbaren Themes erfolgen. Am einfachsten gehts das direkt im Frontend Modul. (Diese werden ja nun innerhalb eines Themes angelegt)

Tabellen Angaben

Hierzu braucht nur im Modul ein Feld angelegt werden.

-- 
-- Table `tl_module`
-- 
CREATE TABLE `tl_module` (
  `banner_template` varchar(32) NOT NULL default '',
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

DCA Angaben

In der DCA, hier "tl_module.php", erfolgte nun im Abschnitt "fields" dieser Teil:

$GLOBALS['TL_DCA']['tl_module']['fields']['banner_template'] = array
(
    'label'                   => &$GLOBALS['TL_LANG']['tl_module']['banner_template'],
    'default'                 => 'mod_banner_list_all',
    'exclude'                 => true,
    'inputType'               => 'select',
    //'options'                 => $this->getTemplateGroup('mod_banner_list_'), // Das wäre die alte Variante
    'options_callback'        => array('tl_module_banner', 'getBannerTemplates')
);

Die alte Variante (hier auskommentiert) ist hier auch dargestellt, welche wie oben beschrieben funktionieren würde.
Bei der neuen Variante ist zu sehen, dass ein "options_callback" nötig ist. Grund ist, dass die Methode "getTemplateGroup" einen optionalen zweiten Parameter neuerdings versteht. Dieser Parameter ist die Theme-ID. Da diese aber hier nicht zur Verfügung steht, holt man sich diese per callback:

class tl_module_banner	extends Backend 
{
	/**
	 * Template over theme id
	 */
	public function getBannerTemplates(DataContainer $dc)
	{
            if (version_compare(VERSION.BUILD, '2.9.0', '>=')) {
	        return $this->getTemplateGroup('mod_banner_list_', $dc->activeRecord->pid);
            } else {
                return $this->getTemplateGroup('mod_banner_list_');
            }
	}  
}

Hier wieder zu sehen, beginnt die Suche nach Templates mit "mod_banner_list_". Hier wird nun in folgender Reihenfolge gesucht:

1. Verzeichnis templates des Moduls
2. Verzeichnis TL_ROOT/templates (nicht rekursiv!)
3. Im Template Verzeichnis des Themes, z.b. TL_ROOT/templates/mein_theme/meine_templates

Achtung: Werden gleichnamige Template Dateien gefunden, wird nur das zuletzt gefundene angezeigt bezogen auf die oben gezeigten Reihenfolge. Das Theme Verzeichnis hat also die höchste Priorität.

Im obigen Beispiel wurde noch ein Versionsvergleich eingebaut. Somit arbeitet diese Methode sowohl in Contao 2.8 als auch in Contao 2.9.

Frontend Modul

Das Frontend Modul bekommt hier durch das Framework die Felder aus tl_module automatisch, dazu braucht es also keine SQL Abfrage. Daher verkürzt sich die Sache sehr.
Hier mal kurze Code Sequenzen, die das Ganze etwas deutlicher machen sollten.

class ModuleBanner extends Module
{
	/**
	 * Template
	 * @var string
	 */
	protected $strTemplate = 'mod_banner_list_all';  // Default wie in DCA definiert
 
        /**
	 * Generate module
	 */
	protected function compile()
	{
....
             if (($this->banner_template != $this->strTemplate) && ($this->banner_template != '')) 
             {
                $this->strTemplate = $this->banner_template;
                $this->Template = new FrontendTemplate($this->strTemplate);
             }
....
        }
}

getTemplateGroup ab Contao 4.8 (abwärtskompatibel)

public function getTemplates($dc)
{
	if(version_compare(VERSION.BUILD, '2.9.0', '>=') && version_compare(VERSION.BUILD, '4.8.0', '<'))
	{
		// Den 2. Parameter gibt es nur ab Contao 2.9 bis 4.7
		return $this->getTemplateGroup('mail_trainerlizenzen_', $dc->activeRecord->id);
	}
	else
	{
		// Ohne 2. Parameter bis Contao 2.8 und ab Contao 4.8
		return $this->getTemplateGroup('mail_trainerlizenzen_');
	}
}

getTemplateGroup in Contao 2.9.x und CE

Bei Content Elementen in Artikel sieht das Ganze wieder komplizierter aus. Das Grundprinzip ist aber das gleiche. Es wird über Artikel und Seitenstruktur ermittelt, in welchem Theme sich dieses CE befindet und mit der Theme ID wird dann wie bei der Modul Variante wieder nach Templates gesucht.

Hier beispielsweise ein Auszug aus dem DCA der Contao-internen Galerie:

public function getGalleryTemplates(DataContainer $dc)
{
	// Ermitteln der Seiten ID
	$objArticle = $this->Database->prepare("SELECT pid FROM tl_article WHERE id=?")
								 ->limit(1)
								 ->execute($dc->activeRecord->pid);
 
	// Vererbung der Seiteneigenschaften
	$objPage = $this->getPageDetails($objArticle->pid);
 
	// Ermitteln der Theme ID
	$objLayout = $this->Database->prepare("SELECT pid FROM tl_layout WHERE id=?")
								->limit(1)
								->execute($objPage->layout);
 
	// Alle verfügbaren Galerie-Templates anzeigen
	return $this->getTemplateGroup('gallery_', $objLayout->pid);
}

--BugBuster 14:23, 15. Jul. 2010 (CEST)