MetaModels Interfaces

Die MetaModels Interfaces bilden die Basis der Interfaces und ermöglichen den Zugriff auf ein MetaModel bis hin zum einzelnen Item.

Viele Arbeiten bei dem Einsatz bzw. Verwendung der Interfaces konzentrieren sich auf die Abfrage vorhandener Daten eines MetaModel. Hier folgt der Aufbau analog dem Aufbau einer Abfrage oder Auflistung über das Contentelement bzw. Frontend-Modul mit

Zudem können über die Interfaces eines MetaModel auch verschiedene Objekte (MetaModel, Attribut, Item) auch erstellt, die Werte verändert oder Eigenschaften abgefragt werden wie Anzahl oder Sprache.

MetaModelsServiceContainer Interface:

Mit dem MetaModelsServiceContainer Interface kann eine Verbindung zu MetaModels aufgebaut werden. Dies ist zum Beispiel notwendig, wenn auf MetaModel außerhalb eines MetaModel-Templates zugegriffen werden soll.

Für einen Zugriff benötigt man einen „Service Container“, den man sich z.B. im globalen Scope holen kann

$container = $this->getContainer();

Anschließend kann mit einem Interface darauf zugegriffen werden - z.B.:

$factory = $container->getFactory();
bzw.
$factory = $this->getContainer()->get('metamodels.factory');

Mit dem Zugriff über $GLOBALS kann in eigenen Templates und Programmierungen leicht auf den Service-Container zugegriffen werden. Andere Möglichkeiten wären über Events wie z.B. „MetaModelsEvents::SUBSYSTEM_BOOT“.

Aktuelle Informationen unter: IMetaModelsServiceContainer

Interfaces:

getFactory()
gibt den Zugriff auf MetaModels zurück

getAttributeFactory()
gibt den Zugriff auf die Attribute zurück

getFilterFactory()
gibt den Zugriff auf die Filter zurück

getRenderSettingFactory()
gibt den Zugriff auf die Render-Einstellungen zurück

getEventDispatcher()
gibt den Zugriff auf die Event-Dispatcher zurück

getDatabase()
gibt den Zugriff auf die Datenbank zurück

getCache()
gibt den Zugriff auf die Cache zurück

setService($service, $serviceName = null)
fügt einen eigenen Service dem Container hinzu

getService($serviceName)
gibt den Zugriff auf einen Service mit dem übergebenen Namen zurück

ServiceContainerAware Interface:

Mit dem ServiceContainerAware Interface kann man Zugriff auf den Service-Container erhalten oder einen neuen Service-Container zuweisen.

Aktuelle Informationen unter: IServiceContainerAware

Interfaces:

setServiceContainer(IMetaModelsServiceContainer $serviceContainer)
setzt den zu verwendenden Service-Container

getServiceContainer()
gibt den Service-Container zurück

Factory Interface:

Mit dem Factory Interface können Instanzen eines MetaModel erstellt und bestimmte Eigenschafen abgefragt werden.

Die Erstellung eines neuen MetaModel ist nicht vorgesehen - wenn auch möglich - da für die Erstellung sehr komplexe Parameter mit übergeben werden müssten und die Erstellung auf die Arbeit aus dem Backend ausgerichtet ist.

Aktuelle Informationen unter: IFactory

Interfaces:

getMetaModel($modelName);
erstellt eine MetaModel-Instanz mit dem übergebenen Namen

translateIdToMetaModelName($modelId);
gibt den Namen zu einer MetaModel-ID zurück

collectNames();
gibt alle MetaModel-Namen als Array zurück

getServiceContainer();
gibt den Service-Container zurück

Warnung

Die Methoden byTableName, byId und getAllTables wurden in der Version 2.0 entfernt

byTableName($strTableName);
Methode getMetaModel($modelName); verwenden

byId($intMetaModelId);
Methode getMetaModel($modelName); mit translateIdToMetaModelName($modelId); verwenden

getAllTables();
Methode collectNames(); verwenden

MetaModel Interface:

Mit dem MetaModel-Interface können Eigenschaften einer MetaModel-Instanz abgefragt bzw. beeinflusst werden.

Zunächst muss eine MetaModels-Instanz über die ID bzw. den Namen eines MetaModel erzeugt werden siehe Factory Interface:)

$model = \MetaModels\IFactory::getMetaModel($modelName);

bzw. inklusive des Service-Containers:

1<?php
2$modelId = 42;
3
4/** @var $container */
5$factory   = $this->getContainer()->get('metamodels.factory');
6$modelName = $factory->translateIdToMetaModelName($modelId);
7$model     = $factory->getMetaModel($modelName);

Anschließend kann eine Eigenschaft abgefragt oder gesetzt werden - z.B. die Abfrage aller vorhandenen Attribute:

$attributes = $metaModel->getAttributes();

Aktuelle Informationen unter: IMetaModel

Interfaces:

Warnung

Die Methoden getServiceContainer ist deprecated - bitte als Service einbinden

getServiceContainer()
gibt den Service-Container zurück

get($strKey)
gibt die Konfigurationseinstellungen zurück

getTableName()
gibt die Tabellen-Namen des instanzierten MetaModel zurück

getName()
gibt die Namen des instanzierten MetaModel zurück

Warnung

Die Methoden isTranslated ist deprecated - bitte ITranslatedMetaModel verwenden

isTranslated()
prüft, ob das instanzierten MetaModel Übersetzungen erstellen kann

hasVariants()
prüft, ob das instanzierten MetaModel Varianten erstellen kann

Warnung

Die Methoden getAvailableLanguages ist deprecated - bitte ITranslatedMetaModel verwenden

getAvailableLanguages()
gibt alle Sprachcodes als Array des instanzierten MetaModel zurück

Warnung

Die Methoden getFallbackLanguage ist deprecated - bitte ITranslatedMetaModel verwenden

getFallbackLanguage()
gibt den Sprachcode der Fallbacksprache des instanzierten MetaModel zurück

Warnung

Die Methoden getActiveLanguage ist deprecated - bitte ITranslatedMetaModel verwenden

getActiveLanguage()
gibt den Sprachcode der aktiven Sprache des instanzierten MetaModel zurück

addAttribute(IAttribute $attribute)
fügt ein Attribut in die interne Liste der Attribute ein

hasAttribute($attributeName)
prüft, ob ein Attribut mit dem gegebenen Namen in der internen Liste der Attribute vorhanden ist

getAttributes()
gibt ein Array mit allen Attributen des instanzierten MetaModel zurück

getInVariantAttributes()
gibt ein Array mit den Attributen des instanzierten MetaModel zurück welche nicht als Varianten definiert sind

getAttribute($attributeName)
gibt die Instanz des Attributes mit dem gegebenen Attributnamen zurück

getAttributeById($id)
gibt die Instanz des Attributes mit der gegebenen Attribut-ID zurück

findById($id, $attrOnly = [])
gibt das Item mit der gegebenen ID zurück; optional kann ein Array mit Attributnamen angegben werden, deren Werte zurück zu gegeben werden sollen

getEmptyFilter()
erzeugt ein „leeres“ Filterobjekt ohne Filterregeln

Warnung

Die Methode prepareFilter ist deprecated - bitte Filter-Setting-Factory verwenden

prepareFilter($filterSettings, $filterUrl)
erzeugt ein Filterobjekt aus einer gegebenen Filter-ID und einem optionalen Array mit Filterparametern z.B. für die Übernahme von GET-Werten aus einer URL

findByFilter( $filter, $sortBy = '', $offset = 0, $limit = 0, $sortOrder = 'ASC', $attrOnly = [] )
gibt die Items zurück, welche mit einem gegebenen Filter in dem instanzierten MetaModel ermittelt werden - neben den Parametern der Sortierung, Offset, Limit und Sortierrichtung, kann ein Array mit Attributnamen angegeben werden, deren Werte zurück zu gegeben werden sollen

getIdsFromFilter( $filter, $sortBy = '', $offset = 0, $limit = 0, $sortOrder = 'ASC' )
gibt die IDs der Items zurück, welche mit einem gegebenen Filter in dem instanzierten MetaModel ermittelt werden - die Parametern der Sortierung, Offset, Limit und Sortierrichtung können angegeben werden

getCount($filter)
gibt die Anzahl der Items zurück, die nach einem gegebenen Filter ermittelt werden

findVariantBase($filter)
gibt alle Items einer Varianten-Basis zürück, die nach einem gegebenen Filter ermittelt werden

findVariants($ids, $filter)
gibt alle Varianten-Items eines Arrays mit IDs und einem gegebenen Filter zurück

findVariantsWithBase($ids, $filter)
gibt alle Varianten-Items eines Arrays mit IDs und einem gegebenen Filter zurück; die Abfrage unterscheidet nicht zwischen Items einer Varianten-Basis und -Items

getAttributeOptions($attribute, $filter = null)
gibt alle Optionen eines gegebenen Attributs zurück; Optional kann ein Filter angegeben werden

saveItem($item, $timestamp = null)
speichert ein gegebenes Item bzw. es wird ein neues Item erzeugt, wenn keine ID mit übergeben wurde

delete($item)
löscht ein gegebenes Item

Warnung

Die Methode getView ist deprecated - bitte Render-Setting-Factory verwenden

getView($viewId = 0)
gibt die Instanz der Render-Einstellungen des instanzierten MetaModel zurück

Translated MetaModel Interface:

Bemerkung

Das Feature steht ab MM 2.2 zur Verfügung.

Mit dem Translated-MetaModel-Interface können die Sprachvorgaben eines übersetzten MetaModel abgefragt oder gesetzt werden.

Bis zur Version MM 2.1 konnte aktuelle Sprache eines übersetzten MetaModel nur über das (temporäre) Setzen von $GLOBALS['TL_LANGUAGE'] erreicht werden. Mit dem Interface ist das Setzen der Sprache des MetaModel unabhängig von der Backendsprache von Contao möglich.

Soll zum Beispiel bei einem übersetzten MetaModel ein Item in einer bestimmten Sprache gespeichert werden, kann die Sprache über den Sprachcode (de, en, fr, ..) wie folgt gesetzt werden:

$model->selectLanguage('de');

Eine Typprüfung kann wie folgt implementiert werden:

1<?php
2
3use MetaModels\ITranslatedMetaModel;
4
5if ($model instanceof ITranslatedMetaModel) {
6    // make anything...
7}

Ab MetaModels 2.2 müssen die folgenden Interfaces verwendet werden:

Interfaces:

getLanguages()
ermittelt alle Sprachcodes, die in diesem MetaModel als für die Übersetzung verfügbar markiert wurden

getMainLanguage()
ermittelt den Sprachcode, der in diesem MetaModel als Fallback-Sprache markiert wurde

getLanguage()
ermittelt den aktuellen Sprachcode

selectLanguage($activeLanguage)
setzt die neue, aktive Sprache und gibt den vorherigen Sprachcode zurück

Items Interface:

Mit dem Items-Interface können Eigenschaften der Items abgefragt werden.

Zunächst muss eine MetaModels-Instanz über die ID oder dem Namen eines MetaModel erzeugt und anschließend z.B. über einen Filter eine Liste von Items ermittelt werden.

$items = $model->findByFilter($filter);

Anschließend kann eine Eigenschaft abgefragt werden - z.B. die Abfrage zur Anzahl aller vorhandenen Items:

$amountItems = $items->getCount();

Aktuelle Informationen unter: IItems

Interfaces:

getItem()
gibt das aktuelle Item zurück

getCount()
gibt die Anzahl der Items zurück

first()
setzt den Zeiger auf das erste Element der Items

prev()
setzt den Zeiger auf das nächste Element der Items

last()
setzt den Zeiger auf das letzte Element der Items

reset()
resettet das aktuelle Ergebnis

getClass()
gibt die CSS-Klasse des aktuellen Items zurück (first, last, even, odd)

parseValue($outputFormat = 'text', $settings = null)
parst das aktuelle Item und gibt das Ergebnis als Array der Attribute zurück; für die Ausgaben in HTML5 müssen die Render-Einstellungen als $objSettings übergeben werden z.B. $metaModel->getView(3)

parseAll($outputFormat = 'text', $settings = null)
parst alle Items und gibt das Ergebnis als Array der Items mit dessen Attributen zurück; für die Ausgaben in HTML5 müssen die Render-Einstellungen als $objSettings übergeben werden z.B. $metaModel->getView(3)

Item Interface:

Mit dem Item-Interface können Eigenschaften eines Item abgefragt werden.

Zunächst muss eine MetaModels-Instanz über die ID oder dem Namen eines MetaModel erzeugt und anschließend z.B. über einen Filter (ggf. auch leerer Filter)eine Liste von Items ermittelt werden.

$items = $model->findByFilter($filter);

Anschließend kann eine Eigenschaft abgefragt werden - z.B. die Abfrage des Wertes eines Attributs:

$attribute = $items->getItem()->get($attributeName);

Ein neues Item wird wie folgt erzeugt:

$item = new \MetaModels\Item($model, []);

In dem übergebenen Array können „Key-Value-Paare“ übergeben werden - dies ist aber nur bei einfachen Item-Typen wie Text sinnvoll.

Aktuelle Informationen unter: IItem

Interfaces:

get($attributeName)
gibt den Wert eines Attributes bei gegebenem Attributnamen zurück

set($attributeName, $value)
setzt den Wert eines Attributes bei gegebenem Attributnamen

getMetaModel()
gibt die Instanz des Items zurück

getAttribute($attributeName)
gibt die Instanz eines Attributes bei gegebenem Attributnamen zurück

isVariant()
ermittelt, ob das Item eine Variante eines anderen Items ist

isVariantBase()
ermittelt, ob das Item eine Variantenbasis ist

getVariants($filter)
gibt ein Array mit den Varianten des Items zurück oder null, wenn das Item keine Varianten beherrscht

getVariantBase()
gibt das Item der Variantenbasis zurück; für ein Item ohne Varianten ist die Variantenbasis das Item selbst

parseValue($outputFormat = 'text', $settings = null)
rendert das Item im vorgegebenen Format; als Rohdaten [raw] werden die Daten immer mit ausgegeben inkl. Attribute referenzierter MetaModel

parseAttribute($attributeName, $outputFormat = 'text', $settings = null)
rendert ein einzelnes Attribut des Item im vorgegebenen Format; als Rohdaten [raw] werden die Daten immer mit ausgegeben inkl. Attribute referenzierter MetaModel

copy()
erstellt ein neues Item als Kopie eines vorhandenen Items

varCopy()
erstellt ein neues Item als Kopie eines vorhandenen Items als Variante

save()
speichert den aktuellen Wert bzw. Werte für das Item

Beispiel:

Das folgende Beispiel soll einen kleinen Einstieg in die Arbeit mit den Interfaces demonstrieren. Das Beispiel kann z.B. in eine Template-Datei eingefügt und per Inserttag {{file::mm_interfaces.html5}} in einem Artikel-Inhaltselement ausgegeben werden.

Beispiele für den Einsatz von Filtern sind hier zu finden Filter Interfaces

Das Beispiel bezieht sich auf den Ausbau von „Das erste MetaModel“.

 1<?php
 2/* Parameter (Beispiel) */
 3
 4// Name der MetaModel Tabelle (siehe "Das erstes Metamodel")
 5$modelName = 'mm_mitarbeiterliste';
 6// ID der Render-Einstellungen "FE-Liste"
 7$renderId = 2;
 8// ID des Filters
 9$filterId = 1;
10
11/* Interface */
12
13// Den 'service container' kann man erhalten, wenn man ihn aus dem globalen Scope holt,
14// oder aber indem man auf das Event \MetaModelsEvents::SUBSYSTEM_BOOT (oder eines der
15// konkretisierten Events für Backend/Frontend) lauscht.
16// (Container nur notwendig, wenn außerhalb des MM-Zugriffs)
17
18/* --- MM 2.0 --- */
19/** @var \MetaModels\IMetaModelsServiceContainer $container */
20//$container = $GLOBALS['container']['metamodels-service-container'];
21// MM Factory
22//$factory = $container->getFactory();
23
24/* --- MM 2.1 --- */
25/** @var $container */
26$factory = $this->getContainer()->get('metamodels.factory');
27// alternativ
28//$factory = \Contao\System::getContainer()->get('metamodels.factory');
29
30/* --- MM 2.x --- */
31// MetaModel erzeugen, wenn Tabellen/MetaModel-Name bekannt.
32$model = $factory->getMetaModel($modelName);
33// MetaModel erzeugen, wenn nur id bekannt ($metaModelId == tl_metamodel.id des MetaModel).
34//$model = $factory->getMetaModel($factory->translateIdToMetaModelName($metaModelId));
35// leerer Filter
36$filter = $model->getEmptyFilter();
37// vordefinierter Filter über die Filter-Id
38//$filter = $model->prepareFilter($filterId, []);
39// alle Items
40$items = $model->findByFilter($filter);
41// alle Items geparst zu Array mit HTML5 Knoten
42$arrItems = $items->parseAll('html5', $model->getView($renderId));
43// alternativ nur Knoten raw und text
44//$arrItems = $items->parseAll('text');
45//dump($arrItems);
46
47/* Ausgabe */
48
49// Anzahl der Items
50echo 'Anzahl: '.$items->getCount()."<br>\n";
51
52// Variante 1 - Items-Objekt
53/*
54foreach ($items as $item)
55{
56    echo $item->get('name')."<br>\n";
57}
58*/
59
60// Variante 2 - Items-Array
61foreach ($arrItems as $arrItem)
62{
63    echo $arrItem['html5']['name']."<br>\n";
64}