Unvollständiger Artikel: dieser Artikel ist noch nicht sauber bearbeitet. Bitte erweitere ihn und entferne erst anschliessend diesen Hinweis.

Mit der Methode getTemplateGroup ist es in einem Modul möglich, im Backend die Auswahl von Templates dem Nutzer 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 nun zu sehen, ein Select Feld, welches als Default das Template "mod_banner_list_all" nimmt, gesucht werden Templates die beginnen mit "mod_banner_list_" und enden mit ".tpl", die Endung kann dabei hier nicht angegeben werden.
In dem Fall wird vom Framework zuerst im Verzeichnis "templates" vom Modul gesucht, und dann im Verzeichnis "TL_ROOT/templates". Liegen im letzterem Templates mit gleichem Namen werden diese bevorzugt. Damit wurde die Möglichkeit geschaffen, updatesichere Templates anzulegen auch für Module die keine Auswahlmöglichkeit bieten.
Der Name wird nach Auswahl und Speicherung in der Datenbank abgelegt und kann un 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 ermmittelbaren 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, habe ich auch mal dargestellt, die würde wie oben beschrieben funktionieren.
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)
	{
	    return $this->getTemplateGroup('mod_banner_list_', $dc->activeRecord->pid);
	}  
}

Hier wieder zu sehen die Suche nach Templates die beginnen 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

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 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.

Falls wirklich jemand wissen will wie das geht, schaut in den Quelltext vom Core, oder gebt mir Bescheid, dann versuche ich einen kurzen Abriss hier reinzusetzen, der ist dann aber ungetestet.

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