Contao Community Documentation - Benutzerbeiträge [de]

Ext404

2012-02-28T11:38:14Z

B2m: Kompatibilität

Dieses Modul erweitert Contao um die Möglichkeit, auf der 404-Seite dem User über eine Referrer-Auswertung spezifische Hinweise auf die Ursache des 404-Fehlers zu geben.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.9.2
| Version=2.9 - 2.11
| TLVersion=2.7.0 - 2.8.4
| ERLink=http://www.contao.org/erweiterungsliste/view/ext404.de.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/ext404/issues
}}

=Verwendung=

==Modul anlegen==

Das Modul ext404 wird entweder über einen Artikel, oder über ein spezifisches Seitenlayout in die spezielle 404-Seite von Contao eingebunden. Hierfür muss ein neues Modul vom Typ '''Verschiedenes/Extended 404''' angelegt werden.

===Maileinstellungen===

* Empfänger Mailadresse: an diese Mailadresse werden Informationen über fehlerhafte Verlinkungen versendet. Ist das Feld leer, so werden keine Fehlerbenachrichtigungen versendet.
* Absender Mailadresse: diese Mailadresse wird als Absender der Fehlerbenachrichtigungen per E-Mail verwendet. Ist dieses Feld leer, so werden keine Fehlerbenachrichtigungen versendet.

{{Hinweis|Es genügt also schon ein leeres Feld (Empfänger "oder" Absender) um den Mailversand zu deaktivieren!}}

===Behandlung von Dateierweiterungen===

Es ist natürlich möglich die Standard 404-Meldungen per [http://aktuell.de.selfhtml.org/artikel/server/apacheconf/apconf16.htm#a3 Servereinstellungen] oder [http://de.selfhtml.org/servercgi/server/htaccess.htm#fehlermeldungen .htaccess] auf die 404-Seite von Contao weiterzuleiten. Dann werden auch nicht von Contao abgefangene Requests behandelt. Also nicht nur fehlerhafte Verlinkungen auf Contao-Seiten, sondern z.B. auch fehlerhaft eingebundene Bilder, CSS oder JavaScriptdateien berücksichtigt. Da dies jedoch auch zu Problemen führen kann gibt es die Möglichkeit nur Dateien mit speziellen Erweiterungen zu behandeln bzw. auszuschließen.

'''Zu behandelnde Dateierweiterungen:''' dies stellt eine durch Kommata separierte Liste von Dateierweiterungen dar (Beispiel: html,htm,php). Es werden dann nur Dateien mit dieser Erweiterung vom Modul behandelt. Für alle anderen Dateitypen gilt die Einstellung ''Behandlung anderer Anfragen''.

'''Behandlung anderer Anfragen''': Dies zeigt die Optionen, die für die Behandlung von Dateien außerhalb der Whitelist verwendet werden.
* die: Der Aufbau der Seite wird abgebrochen und eine 404-Meldung per [http://php.net/manual/de/function.die.php die] herausgegeben.
* nomail: Die Fehlermeldung wird wie gewohnt angezeigt und geloggt, jedoch wird keine Informationsmail versandt.
* nolog: Die Fehlermeldung wird wie gewohnt angezeigt und per Mail darüber informiert, sie wird jedoch nicht geloggt. Dies erhöht die Anzahl der Mails beträchtlich!
* nolognomail: Die Fehlermeldung wird wie gewohnt angezeigt, jedoch weder geloggt noch darüber per Mail informiert.

'''Erweiterungen, die für IE 8 behandelt werden sollen:''' dies stellt wie auch in der oberen Option eine durch Kommata separierte Liste von Dateierweiterungen dar, die vom Modul behandelt werden sollen. Diese Liste wird jedoch nur angewandt, wenn der Browser des Besuchers sich als Internet Explorer 8 identifiziert.

'''Behandlung anderer Anfragen mit dem IE 8:''' Wie ''Behandlung anderer Anfragen'', nur auf die Liste für den IE 8 angewandt.

'''Verwendung der Whitelist als Blacklist:''' Mit einem kleinen Trick ist es auch möglich die Liste der Dateierweiterungen als Blacklist zu verwenden. Hierfür einfach als erstes Stichwort in der Liste 'blacklist' verwenden. Beispiel: ''blacklist,js,css''

==Modul einbinden==

Das Modul wird entweder über ein Content Element in einen Artikel auf der Contao 404-Seite eingebunden, oder in das spezielle Layout für diese Seite geladen. Dort zeigt es dann je nach Einstellungen eine Fehlermeldung an und informiert über den Fehler per Datenbanklog oder Mail.

=Die Fehlermeldungen=

==Typen von Fehlermeldungen==

Es gibt vier Typen von Fehlermeldungen:
# Der Referrer konnte nicht ausgewertet werden => Vermutlich veraltetes Bookmark oder Adresse direkt eingegeben.
# Der Referrer entspricht der eigenen Webseite => ein falscher Link auf der eigenen Seite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für diese 404-Meldung gab.
# Der Referrer ist in der Liste der Suchmaschinen zu finden => abwarten und Tee trinken
# Der Referrer ist nicht in der Liste => Falscher Link von einer anderen Webseite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für die 404-Meldung gab.

==Anpassen der Fehlermeldungen==

{{Anmerkung|Die Fehlermeldungen befinden sich in der Sprachdatei ''~/system/modules/ext404/sprachcode/default.php''. Da sich die Sprachelemente in den globalen [http://www.contao.org/data-container-arrays.html DCA] von Contao befinden können sie da auch selbst updatesicher überschrieben werden.}}

==Testen der Fehlermeldungen==

Wenn man die Reaktion von Fehlermeldungen testen möchte, sollte man berücksichtigen, dass die Information per Mail pro falsch verlinkter Seite (Referrer+verlinkte Seite stimmen überein) nur einmal in 31 Tagen versendet wird. Deshalb sollte man beim Testen die Tabelle tl_ext404_log unter dem Punkt ''Systemwartung'' im Backend ab und zu leeren.

# Um den ersten Typ zu testen ruft man einfach eine nicht existierende Seite auf. Beispiel http://www.example.com/blubb.html bzw. http://www.example.com/index.php/blubb.html
# Um den zweiten Typ zu testen gibt man einfach einen falschen Link in einem Artikel auf der eigenen Seite ein und klickt ihn an
# Um den dritten Typ zu testen editiert man die Datei ''~/system/modules/ext404/files/searchengines.txt'' und fügt da eine eigene Domain zur Liste hinzu, von wo aus man auf eine nicht existierende Seite im zu testenden Contao-Projekt verlinkt.
# Um den vierten Typ zu testen verlinkt man von einer Seite auf einer anderen Domain auf eine nicht existierende Seite im zu testenden Contao-Projekt.

=Weitere Mechanismen z.B. speziell für Suchmaschinen=

Um nicht ständig über fehlerhafte Verlinkungen von bestimmten Webseiten aus benachrichtigt zu werden, was vor allem bei Suchmaschinen mit nicht aktuellem Index nervig ist, werden diese speziell behandelt.

==Reverser IP-Lookup==

Gerade bei Suchmaschinen bekommt man als Referrer häufiger eine IP anstatt eine Adresse. Diese wird wenn möglich aufgelöst und in die für Menschen lesbare Adresse umgewandelt.

==Liste der Suchmaschinen==

Eine Liste der Suchmaschinen ist in der Datei ''~/system/modules/ext404/files/searchengines.txt'' zu finden. Hierbei ist zu beachten, dass auch Subdomains oder andere Topleveldomains berücksichtigt werden können!

Der Eintrag ''google'' berücksichtigt also '''alle''' Topleveldomains wie google.de, google.com... sowie Subdomains wie maps.google.de

Die Einträge werden mit [http://php.net/manual/de/function.preg-quote.php preg_quote()] in einen regulären Eindruck eingefügt.

Ext404

2011-08-18T07:07:13Z

B2m: Version aktualisiert

Dieses Modul erweitert Contao um die Möglichkeit, auf der 404-Seite dem User über eine Referrer-Auswertung spezifische Hinweise auf die Ursache des 404-Fehlers zu geben.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.9.2
| Version=2.9 - 2.10
| TLVersion=2.7.0 - 2.8.4
| ERLink=http://www.contao.org/erweiterungsliste/view/ext404.de.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/ext404/issues
}}

=Verwendung=

==Modul anlegen==

Das Modul ext404 wird entweder über einen Artikel, oder über ein spezifisches Seitenlayout in die spezielle 404-Seite von Contao eingebunden. Hierfür muss ein neues Modul vom Typ '''Verschiedenes/Extended 404''' angelegt werden.

===Maileinstellungen===

* Empfänger Mailadresse: an diese Mailadresse werden Informationen über fehlerhafte Verlinkungen versendet. Ist das Feld leer, so werden keine Fehlerbenachrichtigungen versendet.
* Absender Mailadresse: diese Mailadresse wird als Absender der Fehlerbenachrichtigungen per E-Mail verwendet. Ist dieses Feld leer, so werden keine Fehlerbenachrichtigungen versendet.

{{Hinweis|Es genügt also schon ein leeres Feld (Empfänger "oder" Absender) um den Mailversand zu deaktivieren!}}

===Behandlung von Dateierweiterungen===

Es ist natürlich möglich die Standard 404-Meldungen per [http://aktuell.de.selfhtml.org/artikel/server/apacheconf/apconf16.htm#a3 Servereinstellungen] oder [http://de.selfhtml.org/servercgi/server/htaccess.htm#fehlermeldungen .htaccess] auf die 404-Seite von Contao weiterzuleiten. Dann werden auch nicht von Contao abgefangene Requests behandelt. Also nicht nur fehlerhafte Verlinkungen auf Contao-Seiten, sondern z.B. auch fehlerhaft eingebundene Bilder, CSS oder JavaScriptdateien berücksichtigt. Da dies jedoch auch zu Problemen führen kann gibt es die Möglichkeit nur Dateien mit speziellen Erweiterungen zu behandeln bzw. auszuschließen.

'''Zu behandelnde Dateierweiterungen:''' dies stellt eine durch Kommata separierte Liste von Dateierweiterungen dar (Beispiel: html,htm,php). Es werden dann nur Dateien mit dieser Erweiterung vom Modul behandelt. Für alle anderen Dateitypen gilt die Einstellung ''Behandlung anderer Anfragen''.

'''Behandlung anderer Anfragen''': Dies zeigt die Optionen, die für die Behandlung von Dateien außerhalb der Whitelist verwendet werden.
* die: Der Aufbau der Seite wird abgebrochen und eine 404-Meldung per [http://php.net/manual/de/function.die.php die] herausgegeben.
* nomail: Die Fehlermeldung wird wie gewohnt angezeigt und geloggt, jedoch wird keine Informationsmail versandt.
* nolog: Die Fehlermeldung wird wie gewohnt angezeigt und per Mail darüber informiert, sie wird jedoch nicht geloggt. Dies erhöht die Anzahl der Mails beträchtlich!
* nolognomail: Die Fehlermeldung wird wie gewohnt angezeigt, jedoch weder geloggt noch darüber per Mail informiert.

'''Erweiterungen, die für IE 8 behandelt werden sollen:''' dies stellt wie auch in der oberen Option eine durch Kommata separierte Liste von Dateierweiterungen dar, die vom Modul behandelt werden sollen. Diese Liste wird jedoch nur angewandt, wenn der Browser des Besuchers sich als Internet Explorer 8 identifiziert.

'''Behandlung anderer Anfragen mit dem IE 8:''' Wie ''Behandlung anderer Anfragen'', nur auf die Liste für den IE 8 angewandt.

'''Verwendung der Whitelist als Blacklist:''' Mit einem kleinen Trick ist es auch möglich die Liste der Dateierweiterungen als Blacklist zu verwenden. Hierfür einfach als erstes Stichwort in der Liste 'blacklist' verwenden. Beispiel: ''blacklist,js,css''

==Modul einbinden==

Das Modul wird entweder über ein Content Element in einen Artikel auf der Contao 404-Seite eingebunden, oder in das spezielle Layout für diese Seite geladen. Dort zeigt es dann je nach Einstellungen eine Fehlermeldung an und informiert über den Fehler per Datenbanklog oder Mail.

=Die Fehlermeldungen=

==Typen von Fehlermeldungen==

Es gibt vier Typen von Fehlermeldungen:
# Der Referrer konnte nicht ausgewertet werden => Vermutlich veraltetes Bookmark oder Adresse direkt eingegeben.
# Der Referrer entspricht der eigenen Webseite => ein falscher Link auf der eigenen Seite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für diese 404-Meldung gab.
# Der Referrer ist in der Liste der Suchmaschinen zu finden => abwarten und Tee trinken
# Der Referrer ist nicht in der Liste => Falscher Link von einer anderen Webseite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für die 404-Meldung gab.

==Anpassen der Fehlermeldungen==

{{Anmerkung|Die Fehlermeldungen befinden sich in der Sprachdatei ''~/system/modules/ext404/sprachcode/default.php''. Da sich die Sprachelemente in den globalen [http://www.contao.org/data-container-arrays.html DCA] von Contao befinden können sie da auch selbst updatesicher überschrieben werden.}}

==Testen der Fehlermeldungen==

Wenn man die Reaktion von Fehlermeldungen testen möchte, sollte man berücksichtigen, dass die Information per Mail pro falsch verlinkter Seite (Referrer+verlinkte Seite stimmen überein) nur einmal in 31 Tagen versendet wird. Deshalb sollte man beim Testen die Tabelle tl_ext404_log unter dem Punkt ''Systemwartung'' im Backend ab und zu leeren.

# Um den ersten Typ zu testen ruft man einfach eine nicht existierende Seite auf. Beispiel http://www.example.com/blubb.html bzw. http://www.example.com/index.php/blubb.html
# Um den zweiten Typ zu testen gibt man einfach einen falschen Link in einem Artikel auf der eigenen Seite ein und klickt ihn an
# Um den dritten Typ zu testen editiert man die Datei ''~/system/modules/ext404/files/searchengines.txt'' und fügt da eine eigene Domain zur Liste hinzu, von wo aus man auf eine nicht existierende Seite im zu testenden Contao-Projekt verlinkt.
# Um den vierten Typ zu testen verlinkt man von einer Seite auf einer anderen Domain auf eine nicht existierende Seite im zu testenden Contao-Projekt.

=Weitere Mechanismen z.B. speziell für Suchmaschinen=

Um nicht ständig über fehlerhafte Verlinkungen von bestimmten Webseiten aus benachrichtigt zu werden, was vor allem bei Suchmaschinen mit nicht aktuellem Index nervig ist, werden diese speziell behandelt.

==Reverser IP-Lookup==

Gerade bei Suchmaschinen bekommt man als Referrer häufiger eine IP anstatt eine Adresse. Diese wird wenn möglich aufgelöst und in die für Menschen lesbare Adresse umgewandelt.

==Liste der Suchmaschinen==

Eine Liste der Suchmaschinen ist in der Datei ''~/system/modules/ext404/files/searchengines.txt'' zu finden. Hierbei ist zu beachten, dass auch Subdomains oder andere Topleveldomains berücksichtigt werden können!

Der Eintrag ''google'' berücksichtigt also '''alle''' Topleveldomains wie google.de, google.com... sowie Subdomains wie maps.google.de

Die Einträge werden mit [http://php.net/manual/de/function.preg-quote.php preg_quote()] in einen regulären Eindruck eingefügt.

G3 REST

2011-07-08T09:50:39Z

B2m: /* Unteralben aus Album (alle) */

Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.1.0
| Version=2.9
| ERLink=http://www.contao.org/erweiterungsliste/view/g3_rest.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:en:Representational_State_Transfer_REST_API|Representational State Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Installation aus dem Erweiterungsverzeichnis heraus, oder von Hand
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:en:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, lade Daten zu Bildern, lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist von zwei Servern/Installationen abhängig und es werden Daten zwischen diesen Servern/Installationen übertragen}}
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.

Möchte man eine Contao-Installation z.B. für Google Page Speed optimieren, so kann sich bei der Verwendung des Seitencaches das Problem ergeben, dass das erneute Zwischenspeichern der Seite von dem GoogleBot ausgelöst wird, der entsprechend lange auf das Ergebnis warten muss.

== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Fehlermeldungen==
Entdeckt ''g3_rest'' einen Verarbeitungsfehler, so wird der InsertTag durch einen leeren String ersetzt und die Fehlermeldung in das [[System-Log]] von [[Einsteiger|Contao]] geschrieben. Sollte also der InsertTag scheinbar keine Wirkung zeigen, dann sollte das [[System-Log]] auf Meldungen der Kategorie '''ERROR''' geprüft werden.

==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-07-08T09:48:32Z

B2m: /* Fehlermeldungen */ Links

Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.1.0
| Version=2.9
| ERLink=http://www.contao.org/erweiterungsliste/view/g3_rest.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:en:Representational_State_Transfer_REST_API|Representational State Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Installation aus dem Erweiterungsverzeichnis heraus, oder von Hand
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:en:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, lade Daten zu Bildern, lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist von zwei Servern/Installationen abhängig und es werden Daten zwischen diesen Servern/Installationen übertragen}}
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.

Möchte man eine Contao-Installation z.B. für Google Page Speed optimieren, so kann sich bei der Verwendung des Seitencaches das Problem ergeben, dass das erneute Zwischenspeichern der Seite von dem GoogleBot ausgelöst wird, der entsprechend lange auf das Ergebnis warten muss.

== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Fehlermeldungen==
Entdeckt ''g3_rest'' einen Verarbeitungsfehler, so wird der InsertTag durch einen leeren String ersetzt und die Fehlermeldung in das [[System-Log]] von [[Einsteiger|Contao]] geschrieben. Sollte also der InsertTag scheinbar keine Wirkung zeigen, dann sollte das [[System-Log]] auf Meldungen der Kategorie '''ERROR''' geprüft werden.

==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-06-14T08:47:28Z

B2m: /* Einfaches Beispiel für Bilder oder Album */ fehlende Klammer

Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.1.0
| Version=2.9
| ERLink=http://www.contao.org/erweiterungsliste/view/g3_rest.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:en:Representational_State_Transfer_REST_API|Representational State Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Installation aus dem Erweiterungsverzeichnis heraus, oder von Hand
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:en:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, lade Daten zu Bildern, lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist von zwei Servern/Installationen abhängig und es werden Daten zwischen diesen Servern/Installationen übertragen}}
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.

Möchte man eine Contao-Installation z.B. für Google Page Speed optimieren, so kann sich bei der Verwendung des Seitencaches das Problem ergeben, dass das erneute Zwischenspeichern der Seite von dem GoogleBot ausgelöst wird, der entsprechend lange auf das Ergebnis warten muss.

== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Fehlermeldungen==
Entdeckt ''g3_rest'' einen Verarbeitungsfehler, so wird der InsertTag durch einen leeren String ersetzt und die Fehlermeldung in das Systemlog von Contao geschrieben. Sollte also der InsertTag scheinbar keine Wirkung zeigen, dann sollte das Systemlog auf Meldungen der Kategorie '''ERROR''' geprüft werden.

==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-06-08T10:06:52Z

B2m:

Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.1.0
| Version=2.9
| ERLink=http://www.contao.org/erweiterungsliste/view/g3_rest.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:en:Representational_State_Transfer_REST_API|Representational State Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Installation aus dem Erweiterungsverzeichnis heraus, oder von Hand
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:en:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, lade Daten zu Bildern, lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist von zwei Servern/Installationen abhängig und es werden Daten zwischen diesen Servern/Installationen übertragen}}
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.

Möchte man eine Contao-Installation z.B. für Google Page Speed optimieren, so kann sich bei der Verwendung des Seitencaches das Problem ergeben, dass das erneute Zwischenspeichern der Seite von dem GoogleBot ausgelöst wird, der entsprechend lange auf das Ergebnis warten muss.

== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Fehlermeldungen==
Entdeckt ''g3_rest'' einen Verarbeitungsfehler, so wird der InsertTag durch einen leeren String ersetzt und die Fehlermeldung in das Systemlog von Contao geschrieben. Sollte also der InsertTag scheinbar keine Wirkung zeigen, dann sollte das Systemlog auf Meldungen der Kategorie '''ERROR''' geprüft werden.

==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-06-08T10:02:19Z

B2m: /* Lösungsansätze */

Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.1.0
| Version=2.9
| ERLink=http://www.contao.org/erweiterungsliste/view/g3_rest.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:en:Representational_State_Transfer_REST_API|Representational State Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Installation aus dem Erweiterungsverzeichnis heraus, oder von Hand
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:en:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, lade Daten zu Bildern, lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.
{{Anmerkung|Dieser ganze Ablauf ist von zwei Servern/Installationen abhängig und es werden Daten zwischen diesen Servern/Installationen übertragen}}

== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Fehlermeldungen==
Entdeckt ''g3_rest'' einen Verarbeitungsfehler, so wird der InsertTag durch einen leeren String ersetzt und die Fehlermeldung in das Systemlog von Contao geschrieben. Sollte also der InsertTag scheinbar keine Wirkung zeigen, dann sollte das Systemlog auf Meldungen der Kategorie '''ERROR''' geprüft werden.

==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

Ext404

2011-06-08T09:51:20Z

B2m:

Dieses Modul erweitert Contao um die Möglichkeit, auf der 404-Seite dem User über eine Referrer-Auswertung spezifische Hinweise auf die Ursache des 404-Fehlers zu geben.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.9.2
| Version=2.9
| TLVersion=2.7.0 - 2.8.4
| ERLink=http://www.contao.org/erweiterungsliste/view/ext404.de.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/ext404/issues
}}

=Verwendung=

==Modul anlegen==

Das Modul ext404 wird entweder über einen Artikel, oder über ein spezifisches Seitenlayout in die spezielle 404-Seite von Contao eingebunden. Hierfür muss ein neues Modul vom Typ '''Verschiedenes/Extended 404''' angelegt werden.

===Maileinstellungen===

* Empfänger Mailadresse: an diese Mailadresse werden Informationen über fehlerhafte Verlinkungen versendet. Ist das Feld leer, so werden keine Fehlerbenachrichtigungen versendet.
* Absender Mailadresse: diese Mailadresse wird als Absender der Fehlerbenachrichtigungen per E-Mail verwendet. Ist dieses Feld leer, so werden keine Fehlerbenachrichtigungen versendet.

{{Hinweis|Es genügt also schon ein leeres Feld (Empfänger "oder" Absender) um den Mailversand zu deaktivieren!}}

===Behandlung von Dateierweiterungen===

Es ist natürlich möglich die Standard 404-Meldungen per [http://aktuell.de.selfhtml.org/artikel/server/apacheconf/apconf16.htm#a3 Servereinstellungen] oder [http://de.selfhtml.org/servercgi/server/htaccess.htm#fehlermeldungen .htaccess] auf die 404-Seite von Contao weiterzuleiten. Dann werden auch nicht von Contao abgefangene Requests behandelt. Also nicht nur fehlerhafte Verlinkungen auf Contao-Seiten, sondern z.B. auch fehlerhaft eingebundene Bilder, CSS oder JavaScriptdateien berücksichtigt. Da dies jedoch auch zu Problemen führen kann gibt es die Möglichkeit nur Dateien mit speziellen Erweiterungen zu behandeln bzw. auszuschließen.

'''Zu behandelnde Dateierweiterungen:''' dies stellt eine durch Kommata separierte Liste von Dateierweiterungen dar (Beispiel: html,htm,php). Es werden dann nur Dateien mit dieser Erweiterung vom Modul behandelt. Für alle anderen Dateitypen gilt die Einstellung ''Behandlung anderer Anfragen''.

'''Behandlung anderer Anfragen''': Dies zeigt die Optionen, die für die Behandlung von Dateien außerhalb der Whitelist verwendet werden.
* die: Der Aufbau der Seite wird abgebrochen und eine 404-Meldung per [http://php.net/manual/de/function.die.php die] herausgegeben.
* nomail: Die Fehlermeldung wird wie gewohnt angezeigt und geloggt, jedoch wird keine Informationsmail versandt.
* nolog: Die Fehlermeldung wird wie gewohnt angezeigt und per Mail darüber informiert, sie wird jedoch nicht geloggt. Dies erhöht die Anzahl der Mails beträchtlich!
* nolognomail: Die Fehlermeldung wird wie gewohnt angezeigt, jedoch weder geloggt noch darüber per Mail informiert.

'''Erweiterungen, die für IE 8 behandelt werden sollen:''' dies stellt wie auch in der oberen Option eine durch Kommata separierte Liste von Dateierweiterungen dar, die vom Modul behandelt werden sollen. Diese Liste wird jedoch nur angewandt, wenn der Browser des Besuchers sich als Internet Explorer 8 identifiziert.

'''Behandlung anderer Anfragen mit dem IE 8:''' Wie ''Behandlung anderer Anfragen'', nur auf die Liste für den IE 8 angewandt.

'''Verwendung der Whitelist als Blacklist:''' Mit einem kleinen Trick ist es auch möglich die Liste der Dateierweiterungen als Blacklist zu verwenden. Hierfür einfach als erstes Stichwort in der Liste 'blacklist' verwenden. Beispiel: ''blacklist,js,css''

==Modul einbinden==

Das Modul wird entweder über ein Content Element in einen Artikel auf der Contao 404-Seite eingebunden, oder in das spezielle Layout für diese Seite geladen. Dort zeigt es dann je nach Einstellungen eine Fehlermeldung an und informiert über den Fehler per Datenbanklog oder Mail.

=Die Fehlermeldungen=

==Typen von Fehlermeldungen==

Es gibt vier Typen von Fehlermeldungen:
# Der Referrer konnte nicht ausgewertet werden => Vermutlich veraltetes Bookmark oder Adresse direkt eingegeben.
# Der Referrer entspricht der eigenen Webseite => ein falscher Link auf der eigenen Seite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für diese 404-Meldung gab.
# Der Referrer ist in der Liste der Suchmaschinen zu finden => abwarten und Tee trinken
# Der Referrer ist nicht in der Liste => Falscher Link von einer anderen Webseite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für die 404-Meldung gab.

==Anpassen der Fehlermeldungen==

{{Anmerkung|Die Fehlermeldungen befinden sich in der Sprachdatei ''~/system/modules/ext404/sprachcode/default.php''. Da sich die Sprachelemente in den globalen [http://www.contao.org/data-container-arrays.html DCA] von Contao befinden können sie da auch selbst updatesicher überschrieben werden.}}

==Testen der Fehlermeldungen==

Wenn man die Reaktion von Fehlermeldungen testen möchte, sollte man berücksichtigen, dass die Information per Mail pro falsch verlinkter Seite (Referrer+verlinkte Seite stimmen überein) nur einmal in 31 Tagen versendet wird. Deshalb sollte man beim Testen die Tabelle tl_ext404_log unter dem Punkt ''Systemwartung'' im Backend ab und zu leeren.

# Um den ersten Typ zu testen ruft man einfach eine nicht existierende Seite auf. Beispiel http://www.example.com/blubb.html bzw. http://www.example.com/index.php/blubb.html
# Um den zweiten Typ zu testen gibt man einfach einen falschen Link in einem Artikel auf der eigenen Seite ein und klickt ihn an
# Um den dritten Typ zu testen editiert man die Datei ''~/system/modules/ext404/files/searchengines.txt'' und fügt da eine eigene Domain zur Liste hinzu, von wo aus man auf eine nicht existierende Seite im zu testenden Contao-Projekt verlinkt.
# Um den vierten Typ zu testen verlinkt man von einer Seite auf einer anderen Domain auf eine nicht existierende Seite im zu testenden Contao-Projekt.

=Weitere Mechanismen z.B. speziell für Suchmaschinen=

Um nicht ständig über fehlerhafte Verlinkungen von bestimmten Webseiten aus benachrichtigt zu werden, was vor allem bei Suchmaschinen mit nicht aktuellem Index nervig ist, werden diese speziell behandelt.

==Reverser IP-Lookup==

Gerade bei Suchmaschinen bekommt man als Referrer häufiger eine IP anstatt eine Adresse. Diese wird wenn möglich aufgelöst und in die allgemein üblichere Adresse umgewandelt.

==Liste der Suchmaschinen==

Eine Liste der Suchmaschinen ist in der Datei ''~/system/modules/ext404/files/searchengines.txt'' zu finden. Hierbei ist zu beachten, dass auch Subdomains oder andere Topleveldomains berücksichtigt werden können!

Der Eintrag ''google'' berücksichtigt also '''alle''' Topleveldomains wie google.de, google.com... sowie Subdomains wie maps.google.de

Die Einträge werden mit [http://php.net/manual/de/function.preg-quote.php preg_quote()] in einen regulären Eindruck eingefügt.

G3 REST

2011-06-08T09:50:13Z

B2m: Erweiterung nun auch im ER

Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.1.0
| Version=2.9
| ERLink=http://www.contao.org/erweiterungsliste/view/g3_rest.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:en:Representational_State_Transfer_REST_API|Representational State Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Installation aus dem Erweiterungsverzeichnis heraus, oder von Hand
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:en:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, lade Daten zu Bildern, lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.
== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Fehlermeldungen==
Entdeckt ''g3_rest'' einen Verarbeitungsfehler, so wird der InsertTag durch einen leeren String ersetzt und die Fehlermeldung in das Systemlog von Contao geschrieben. Sollte also der InsertTag scheinbar keine Wirkung zeigen, dann sollte das Systemlog auf Meldungen der Kategorie '''ERROR''' geprüft werden.

==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-04-23T05:26:20Z

B2m: Fehlermeldungen hinzugefügt

{{stub}}
Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.0.1
| Version=2.9
| ERLink=https://github.com/b2m/g3_rest/
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
{{Achtung|Dieses Modul ist noch in einer aktiven Entwicklungsphase und deshalb '''nicht''' im ER-Repository zu finden und '''nicht''' für den produktiven Gebrauch zu empfehlen!}}
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:Representational_State_Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Herunterladen der Dateien aus dem GitHub Repository
# Gegebenenfalls entpacken und in den Ordner ''~/system/modules/g3_rest/'' verschieben
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, Lade Daten zu Bildern, Lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.
== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Fehlermeldungen==
Entdeckt ''g3_rest'' einen Verarbeitungsfehler, so wird der InsertTag durch einen leeren String ersetzt und die Fehlermeldung in das Systemlog von Contao geschrieben. Sollte also der InsertTag scheinbar keine Wirkung zeigen, dann sollte das Systemlog auf Meldungen der Kategorie '''ERROR''' geprüft werden.

==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-04-22T18:21:18Z

B2m:

{{stub}}
Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.0.1
| Version=2.9
| ERLink=https://github.com/b2m/g3_rest/
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}
==Allgemeine Informationen==
{{Achtung|Dieses Modul ist noch in einer aktiven Entwicklungsphase und deshalb '''nicht''' im ER-Repository zu finden und '''nicht''' für den produktiven Gebrauch zu empfehlen!}}
Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:Representational_State_Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.
{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}
== Installation ==
# Herunterladen der Dateien aus dem GitHub Repository
# Gegebenenfalls entpacken und in den Ordner ''~/system/modules/g3_rest/'' verschieben
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/
{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}
== Problematik des g3_rest Moduls ==
Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.
===Normaler Ablauf in Contao===
[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss oder ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Users von dem Server der Contao Installation nachgeladen und angezeigt.
{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}
===Ablauf mit ''g3_rest'' Modul===
[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext.]]
# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, Lade Daten zu Bildern, Lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Browser des Besuchers von dem Server der Gallery Installation nachgeladen und angezeigt.
===Lösungsansätze===
Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein, einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit, solange bis die gecachte Seite verfällt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.
== Verarbeitung von Bildern mit ''g3_rest'' ==
{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}
Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet.
=== Einfaches Beispiel für Bilder oder Album ===
<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten.

=== Ausführliches Beispiel für Bild===
<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===
<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===
<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5.

=== Unteralben aus Album (direkt) ===
<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5.

=== Unteralben aus Album (alle) ===
<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5.

=== Mehrere Bilder und Alben ===
<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11.

=== Bilder und Alben über Tag ===
<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===
<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.
{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}
==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>
Die variabel gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.
==Parameter für die InsertTags==
{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}
===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}
===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===
Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):
{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}
{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-04-22T16:05:41Z

B2m: Installationshinweise hinzugefügt

{{stub}}
Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.

[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.0.1
| Version=2.9
| ERLink=https://github.com/b2m/g3_rest/
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}

{{Achtung|Dieses Modul ist noch in einer aktiven Entwicklungsphase und deshalb '''nicht''' im ER-Repository zu finden und '''nicht''' für den produktiven Gebrauch zu empfehlen!}}

Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:Representational_State_Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.

{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}

== Installation ==

# Herunterladen der Dateien aus dem GitHub Repository
# Gegebenenfalls entpacken und in den Ordner ''~/system/modules/g3_rest/'' verschieben
# In den Einstellungen von Contao die Adresse zum REST Service der Gallery Installation angeben
# In den Einstellungen den Zugriffstoken für den REST Service der Gallery Installation angeben

Die Adresse zum REST Service mit '''/''' am Ende (!) kann wie folgt lauten:
* In Unterordner ohne mod_rewrite: http://www.example.com/gallery/index.php?rest/
* In Unterordner ohne www aber mit mod_rewrite: http://example.com/gallery/rest/
* Ohne Unterordner ohne mod_rewrite: http://www.example.com/index.php?rest/
* Ohne Unterordner mit mod_rewrite: http://www.example.com/rest/

{{Hinweis|Es empfiehlt sich für den REST Zugriff einen eigenen User anzulegen und dessen Token zu verwenden!}}

== Problematik des g3_rest Moduls ==

Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.

===Normaler Ablauf in Contao===

[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext]]

# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss, ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Server der Contao Installation nachgeladen und angezeigt.

{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}

===Ablauf mit ''g3_rest'' Modul===

[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext]]

# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, Lade Daten zu Bildern, Lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Server der Gallery Installation nachgeladen und angezeigt.

===Lösungen===

Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit solange die gecachte Seite gültig bleibt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.

== Verarbeitung von Bildern mit ''g3_rest'' ==

{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}

Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet:

=== Einfaches Beispiel für Bilder oder Album ===

<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten

=== Ausführliches Beispiel für Bild===

<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===

<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===

<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5

=== Unteralben aus Album (direkt) ===

<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5

=== Unteralben aus Album (alle) ===

<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5

=== Mehrere Bilder und Alben ===

<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11

=== Bilder und Alben über Tag ===

<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===

<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.

{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}

==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>

Die variable gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.

==Parameter für die InsertTags==

{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}

===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}

===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===

Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):

{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}

{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-04-22T15:56:36Z

B2m: Beispiel für Zufallsbild hinzugefügt

{{stub}}
Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.

[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.0.1
| Version=2.9
| ERLink=https://github.com/b2m/g3_rest/
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}

{{Achtung|Dieses Modul ist noch in einer aktiven Entwicklungsphase und deshalb nicht im ER-Repository zu finden und nicht für den produktiven Gebrauch zu empfehlen!}}

Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:Representational_State_Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.

{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}

== Problematik des g3_rest Moduls ==

Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.

===Normaler Ablauf in Contao===

[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext]]

# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss, ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Server der Contao Installation nachgeladen und angezeigt.

{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}

===Ablauf mit ''g3_rest'' Modul===

[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext]]

# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, Lade Daten zu Bildern, Lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Server der Gallery Installation nachgeladen und angezeigt.

===Lösungen===

Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit solange die gecachte Seite gültig bleibt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.

== Verarbeitung von Bildern mit ''g3_rest'' ==

{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}

Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet:

=== Einfaches Beispiel für Bilder oder Album ===

<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten

=== Ausführliches Beispiel für Bild===

<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Zufallsbild mit Cacheschutz ===

<nowiki>{{cache_g3_rest::item?scope=all&type=photo&random=true}}</nowiki>

Einbindung eines Zufallsbildes aus der Gallery mit aktiviertem Cacheschutz für den InsertTag durch vorangestelltes '''cache_'''.

=== Bilder aus Album ===

<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5

=== Unteralben aus Album (direkt) ===

<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5

=== Unteralben aus Album (alle) ===

<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5

=== Mehrere Bilder und Alben ===

<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11

=== Bilder und Alben über Tag ===

<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===

<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.

{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}

==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>

Die variable gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.

==Parameter für die InsertTags==

{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}

===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}

===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===

Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):

{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}

{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

G3 REST

2011-04-22T15:53:58Z

B2m: Problematik erklärt

{{stub}}
Dieses Modul erweitert Contao um die Möglichkeit über InsertTags Bilder aus einer Menalto Gallery 3 Installation einzufügen.

[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.0.1
| Version=2.9
| ERLink=https://github.com/b2m/g3_rest/
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/g3_rest/issues
}}

{{Achtung|Dieses Modul ist noch in einer aktiven Entwicklungsphase und deshalb nicht im ER-Repository zu finden und nicht für den produktiven Gebrauch zu empfehlen!}}

Die [http://codex.gallery2.org/Gallery3:About Gallery 3] ist die aktuelle Version des [http://gallery.menalto.com/ Gallery Project] und bietet ein umfangreiches [[w:Representational_State_Transfer REST API]] an. Mit ''g3_rest'' ist es möglich verschiedene GET Requests auszuführen und somit die Daten aus der Gallery innerhalb von Contao zu verwenden.

{{msgInfo|Das [http://codex.gallery2.org/Gallery3:API:REST REST API der Gallery] kennt GET, PULL, DELETE und CREATE Requests. Somit lässt sich eine vollständige Anwendung schreiben, die Daten auslesen, löschen, hochladen… kann. Das Modul ''g3_rest'' beschränkt sich in der aktuellen Version jedoch auf GET Requests und kann somit nur Daten darstellen.}}

== Problematik des g3_rest Moduls ==

Die Installationen von Contao und Gallery werden in der aktuellen Version von ''g3_rest'' als '''getrennt''' betrachtet. Dies führt zu Problemen auf die an dieser Stelle aufmerksam gemacht werden soll. Hierfür ist jedoch ein grobes Verständnis des Verarbeitungsprozesses notwendig.

===Normaler Ablauf in Contao===

[[Datei:Bildverarbeitung-in-contao.png‎|200px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung in Contao. Erklärung der einzelnen Schritte im Fließtext]]

# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt ein Bild (InsertTag, Galerie,…). Es überprüft ob das Bild am angegebenen Ort existiert und lädt die Bilddaten.
# Contao überprüft ob das Bild verkleinert werden muss, ob schon eine aktuelle verkleinerte Version existiert und erstellt gegebenenfalls eine verkleinerte Version des Bildes.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Server der Contao Installation nachgeladen und angezeigt.

{{Anmerkung|Dieser ganze Ablauf ist nur von einem Server abhängig und es werden nur Daten auf dem Server selbst verarbeitet}}

===Ablauf mit ''g3_rest'' Modul===

[[Datei:Bildverarbeitung-mit-g3 rest.png‎|335px|thumb|Grobe Skizze des Ablaufes der Bildverarbeitung mit ''g3_rest'' Modul. Erklärung der einzelnen Schritte im Fließtext]]

# Mr. Blue ruft eine Webseite auf. Diese Anfrage wird von dem Webserver an Contao weitergegeben.
# Contao entdeckt einen InsertTag von ''g3_rest'' und started die registrierten Prozeduren.
# Das Modul ''g3_rest'' verarbeitet die Parameter des InsertTags und stellt einen REST Request an die Gallery Installation. Dies erfolgt über normale [[w:Hypertext Transfer Protocol|HTTP-Anfragen]] und somit kann die Gallery Installation auch auf einem anderen Server liegen. Die von Gallery übermittelten Daten werden von ''g3_rest'' verarbeitet und eventuell daraus eine neue Anfrage erstellt, deren Ergebnis verarbeitet und daraus weitere Anfragen erstellt… Beispiel: Ermittle Bilder im Album x, Lade Daten zu Bildern, Lade Tags der Bilder. Dies kann je nach Erreichbarkeit des Servers mit der Gallery Installation durchaus Zeit in Anspruch nehmen!
# Das Verkleinern des Bildes auf die angegebene Größe entfällt, da Gallery schon eine verkleinerte Version gespeichert hat und es zu viel Zeit kosten würde das Bild nachzuladen. Es wird lediglich der HTML-Code mit den Bildlinks und entsprechenden Größenangaben im img-Tag an Contao zurückgegeben.
# Contao liefert den HTML-Code der angeforderten Seite aus.
# Der von Contao ausgelieferte HTML-Code enthält einen img-Tag mit einem Link auf das verkleinerte Bild. Dieses wird vom Server der Gallery Installation nachgeladen und angezeigt.

===Lösungen===

Über die Parameter der InsertTags des ''g3_rest'' Moduls lässt sich nicht nur die Größe des Bildes bestimmen, sondern auch welches der drei zur Verfügung stehenden Bilder (Thumbnail, Resize, Original) eingebunden werden soll. Wenn man also nicht gerade das Originalbild auf Thumbnailgröße verkleinert anzeigen lässt, sind die paar Kilobyte mehr durchaus für den Besucher zu verschmerzen.

Eventuell wird es zukünftig möglich sein einen Pfad zur Gallery Installation auf dem gleichen Server anzugeben um so direkt auf die Bilder zugreifen und diese verarbeiten zu können.

Um das Problem des mehrfachen Nachladens von Daten via REST zu begegenen, bietet sich die Cache-Funktionen von Contao an. Sind diese aktiviert, so wird der von ''g3_rest'' generierte HTML-Code anstelle des InsertTags in die gecachte Seite eingebettet. Eine erneute Bearbeitung des InsertTags mit den damit verbundenen REST Requests entfällt damit solange die gecachte Seite gültig bleibt.

Möchte man trotz aktivierter Cachefunktionen zum Beispiel Zufallsbilder anzeigen lassen, so kann ab TYPOLight 2.8 das Cachen eines InsertTags verhindert werden, indem ein '''cache_''' vorangestellt wird (siehe auch Beispielsektion). Das Modul ''g3_rest'' unterstützt diesen Mechanismus.

== Verarbeitung von Bildern mit ''g3_rest'' ==

{{msgInfo|Die Gallery kann neben Bildern auch Videos verarbeiten und darstellen. Dies wird von ''g3_rest'' in der aktuellen Version jedoch nicht unterstützt.}}

Die Bilder werden in Contao über einen InsertTag eingebunden. Hier sind einige Beispiele gelistet:

=== Einfaches Beispiel für Bilder oder Album ===

<nowiki>{{g3_rest::item?id=125}</nowiki>

Einbindung des Bildes/Albums mit der id 125 mit den Standardwerten

=== Ausführliches Beispiel für Bild===

<nowiki>{{g3_rest::item?id=125&include=resize&height=400&alt=Alt Text für Bild&class=meine bildklassen&&link=orig&rel=lightbox[bilder]&caption=Meine Bildunterschrift&title=Die Beschreibung in der Lightbox&showlink=0&showtags=0&divclass=meine klassen}}</nowiki>

Einbindung des Bildes mit der id 125. Es wird die verkleinerte Version eingebunden und das Original in der Lightbox angezeigt. Die Anzeige eines Linkes zur Gallery und die Anzeige von Tags wird unterdrückt:

<source lang="html4strict">
<div class="image_container meine klassen">
<a href="orig.jpg" title="Die Beschreibung in der Lightbox" rel="lightbox[bilder]">
<img src="resize.jpg" alt="Alt Text für Bild" width="600" height="400" class="meine bildklassen" />
</a>
<div class="caption_container caption">
Meine Bildunterschrift
</div>
</div>
</source>

=== Bilder aus Album ===

<nowiki>{{g3_rest::item?id=5&count=7&type=photo}}</nowiki>

Einbindung von sieben Bildern des Albums mit der id 5

=== Unteralben aus Album (direkt) ===

<nowiki>{{g3_rest::item?id=5&type=album}}</nowiki>

Einbindung der direkten Unteralben des Albums mit der id 5

=== Unteralben aus Album (alle) ===

<nowiki>{{g3_rest::item?id=5&type=album&scope=all}}</nowiki>

Einbindung der aller Unteralben des Albums mit der id 5

=== Mehrere Bilder und Alben ===

<nowiki>{{g3_rest::item</nowiki>'''s'''<nowiki>?id=2,5,8,11}}</nowiki>

Einbindung der Bilder/Alben mit den ids 2, 5, 7 und 11

=== Bilder und Alben über Tag ===

<nowiki>{{g3_rest::tag?id=5}}</nowiki>

Einbindung der Bilder/Alben, die mit dem Tag der id 5 versehen sind.

=== Bilder über Tag ===

<nowiki>{{g3_rest::tag?id=5&type=photo}}</nowiki>

Einbindung nur von Bildern, die mit dem Tag der id 5 versehen sind.

{{msgInfo|Es gibt in der Gallery noch weitere REST Quellen, wie Kommentare oder selbst erstellte Erweiterungen zur Schnittstelle. Diese werden in der aktuellen Version von g3_rest jedoch nicht unterstützt.}}

==Generierter HTML-Code==
<source lang="html4strict">
<div class="image_container $divclass">
<a href="$link" title="$title" rel="$rel">
<img src="$include" alt="$alt" width="$width" height="$height" class="$class" />
</a>
<div class="caption_container caption">
$caption
</div>
<div class="tags_container">
Tags:
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname1" onclick="window.open(this.href); return false;">$_tagname1</a>
<a href="$_taglink1" title="Bilder mit dem Tag $_tagname2" onclick="window.open(this.href); return false;">$_tagname2</a>

</div>
<a href="$_gallery_link" title="$_item_title" class="gallery_link" onclick="this.blur(); window.open(this.href); return false;">Galerie</a>
</div>
</source>

Die variable gesetzten Werte sind mit '''$''' gekennzeichnet. Variablen mit '''$_''' werden anhand der von Gallery übermittelten Daten bestimmt. Die anderen sind über Parameter in den InsertTags beeinflussbar. Der Text ist in Contao Sprachdateien hinterlegt und kann somit auch updatesicher angepasst werden.

==Parameter für die InsertTags==

{{msgWarning|Der WYSIWYG-Editor von Contao fügt (je nach Einstellung) automatisch p-Tags um alleine stehende InsertTags. Da ''g3_rest'' aber je nach Parameter einen div-Container zurückgibt sorgt dies für invalides HTML. Daher ist es eventuell notwendig den InsertTag in einen div-Tag zu schreiben um das automatische einbetten in einen p-Tag durch den WYSIWYG-Editor zu verhindern.}}

===Von ''g3_rest'' verarbeitete Parameter für InsertTag===
{|
|+ align="bottom" style="text-align:center;" | '''Von ''g3_rest'' verarbeitete Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| id
| Zahl oder Komma separierte Liste von Zahlen
| 1
| Die id des zu verarbeitenden Album oder Bildes.
| Wird eine Liste übergeben werden diese Elemente angezeigt.
|-
!scope="row"| width
| Zahlenwert
| leer
| Breite des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| height
| Zahlenwert
| leer
| Höhe des eingebundenen Bildes
| Das Bild an sich wird nicht verkleinert, sondern lediglich ein HTML-Attribut gesetzt. Ist kein oder ein zu großer Wert gegeben wird der von Gallery übermittelte Wert übernommen.
|-
!scope="row"| alt
| g3Title, g3Desc, eigener Text
| g3Title
| Text für alt-Attribut des Bildes
|
|-
!scope="row"| class
| eigener Text
| leer
| Text für das class-Attribut des Bildes
| Mehrere Klassen werden einfach durch Leerzeichen getrennt
|-
!scope="row"| caption
| none, g3Title, g3Desc, eigener Text
| g3Title
| Text für die Bildunterschrift
| Werden mehrere Bilder eingebunden, so wird der Titel (g3Title) bzw. die Beschreibung (d3Desc) des übergeordneten Albums angezeigt.
|-
!scope="row"| include
| thumb, resize, orig
| thumb
| Welches Bild soll eingebunden werden?
| Bei Alben wird nur das Vorschaubild (thumb) eingebunden.
|-
!scope="row"| link
| none, resize, orig, site
| resize
| Ziel des Bildlinks
| Dieser Link kann über den rel-Parameter auch in der Lightbox geöffnet werden. Bei Alben wird nur ein Link auf die Seite eingebunden.
|-
!scope="row"| title
| g3Title, g3Desc, eigener Text
| g3Desc
| Text für das title-Attribut des Bildlinks.
| Dieser Text wird als Bildbeschreibung in der Lightbox angezeigt.
|-
!scope="row"| rel
| eigener Text
| leer
| Text für das rel-Attribut des Bildlinks
| Erlaubt zum Beispiel das Öffnen einer größeren Bildversion per Lightbox
|-
!scope="row"| divclass
| eigener Text
| leer
| Text für das class-Attribut des umgebenden div-Containers
| Der div-Container wird nur erstellt, wenn diese Klasse übergeben wird, oder mehrere Bilder angezeigt werden, oder die Tags mit angezeigt werden, oder ein Link zur Gallery angezeigt werden soll.
|-
!scope="row"| showlink
| 0, 1
| 1
| Soll ein Link zur Gallery unter dem Bild angezeigt werden?
| Werden mehrere Bilder eingebunden, so ist diese Option nicht verfügbar.
|-
!scope="row"| showtags
| 0, 1
| 1
| Sollen die zum Album oder Bild zugehörigen Tags angezeigt werden?
| Werden mehrere Bilder eingebunden, so so werden die Tags aller Bilder zusammen angezeigt.
|-
!scope="row"| count
| Zahl
| leer
| Anzahl der anzuzeigenden Elemente
|
|}

===Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag===

Es stehen außerdem einige Parameter des REST API zur Verfügung (siehe auch [http://codex.gallery2.org/Gallery3:API:REST Gallery Dokumentation]):

{|
|+ align="bottom" style="text-align:center;"| '''Von ''g3_rest'' an Gallery weiter gegebene Parameter für InsertTag'''
|-
!scope="col"| Name
!scope="col"| Erlaubte Werte
!scope="col"| Default
!scope="col"| Beschreibung
!scope="col"| Kommentar
|-
!scope="row"| num
| Zahlen
| 100
| Anzahl der Inhaltselemente
|
|-
!scope="row"| start
| Zahlen
| 0
| Anzahl der zu überspringenden Elemente
| Zusammen mit dem num-Parameter lassen sich somit zum Beispiel die Elemente 150-200 eines Albums anzeigen.
|-
!scope="row"| scope
| direct, all
| direct
| Sollen nur die direkten Elemente eines Albums verarbeitet werden, oder '''alle''' Elemente '''und''' Unterelemente eines Albums
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies ''kann'' bei größeren Installtionen zu Problemen führen.
|-
!scope="row"| random
| true
| leer
| Suche ein zufälliges Element
| Ist dieser Parameter gesetzt wird automatisch ein Elemente des per ID übergebenen Albums per Zufall ausgewählt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| name
| eigener Text
| leer
| Beschränke auf Elemente die den Text im Namen haben.
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt. Dies funktioniert nicht bei der Auswahl über einen Tag, oder wenn mehrere ids übergeben werden.
|-
!scope="row"| type
| album, photo
| leer
| Beschränke auf Elemente des Typs Album oder Photo
| Ist dieser Parameter gesetzt werden automatisch die Elemente des per ID übergebenen Albums angezeigt.
|}

{{msgImportant|Nicht alle Parameter sind miteinander kombinierbar und auch unterstützen nicht alle REST Quellen sämtliche Parameter. Bei der Menge an angebotenen Optionen ist es durchaus möglich, dass es zu einem unvorhergesehenem Verhalten kommt!}}

Datei:Bildverarbeitung-mit-g3 rest.png

2011-04-22T15:19:30Z

B2m: Skiziert grob die Bildverarbeitung in Contao mit dem Modul g3_rest. Quelle: selbst erstellt unter Zuhilfename von LibreOffice Draw und der OpenClipart Bibliothek.

Skiziert grob die Bildverarbeitung in Contao mit dem Modul g3_rest.
Quelle: selbst erstellt unter Zuhilfename von LibreOffice Draw und der OpenClipart Bibliothek.

Datei:Bildverarbeitung-in-contao.png

2011-04-22T15:18:33Z

B2m: Skiziert grob die Bildverarbeitung in Contao. Quelle: selbst erstellt unter Zuhilfename von LibreOffice Draw und der OpenClipart Bibliothek.

Skiziert grob die Bildverarbeitung in Contao.
Quelle: selbst erstellt unter Zuhilfename von LibreOffice Draw und der OpenClipart Bibliothek.

G3 REST

2011-04-22T15:11:54Z

B2m: HTML-Code hinzugefügt

G3 REST

2011-04-22T14:59:02Z

B2m: /* Mehrere Bilder und Alben */

G3 REST

2011-04-22T14:58:19Z

B2m: /* Von g3_rest verarbeitete Parameter für InsertTag */

G3 REST

2011-04-22T14:57:58Z

B2m: /* Von g3_rest verarbeitete Parameter für InsertTag */

G3 REST

2011-04-22T14:57:44Z

B2m: /* Von g3_rest an Gallery weiter gegebene Parameter für InsertTag */

G3 REST

2011-04-22T14:47:16Z

B2m: /* Parameter für die InsertTags */

G3 REST

2011-04-22T14:23:37Z

B2m: Erste Inhalte eingefügt

G3 REST

2011-04-22T09:08:03Z

B2m: Erstellt + Grundlegende Informationen

Benutzer:B2m

2011-04-22T09:00:19Z

B2m: /* Profil */

== Profil ==

Entwickler von Contao Erweiterungen

'''Name:''' Benjamin Meier

'''Blog:''' [http://www.meier-benjamin.de www.meier-benjamin.de]

'''Status:''' Student

Benutzer:B2m

2011-04-22T08:59:25Z

B2m: Profil erstellt

== Profil ==

Entwickler von Contao Erweiterungen

'''Name:''' Benjamin Meier

'''Blog:''' [[http://www.meier-benjamin.de|www.meier-benjamin.de]]

'''Status:''' Student

Ext404

2011-03-16T14:57:03Z

B2m:

{{stub}}
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.9.2
| Version=2.9
| TLVersion=2.7.0
| ERLink=http://www.contao.org/erweiterungsliste/view/ext404.de.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/ext404/issues
}}

=Verwendung=

==Modul anlegen==

Das Modul ext404 wird entweder über einen Artikel, oder über ein spezifisches Seitenlayout in die spezielle 404-Seite von Contao eingebunden. Hierfür muss ein neues Modul angelegt vom Typ '''Verschiedenes/Extended 404''' werden.

===Maileinstellungen===

* Empfänger Mailadresse: an diese Mailadresse werden Informationen über fehlerhafte Verlinkungen versendet. Ist das Feld leer, so werden keine Fehlerbenachrichtigungen versendet.
* Absender Mailadresse: diese Mailadresse wird als Absender der Fehlerbenachrichtigungen per E-Mail verwendet. Ist dieses Feld leer, so werden keine Fehlerbenachrichtigungen versendet.

{{Hinweis|Es genügt also schon ein leeres Feld (Empfänger "oder" Absender) um den Mailversand zu deaktivieren!}}

===Behandlung von Dateierweiterungen===

Es ist natürlich möglich die Standard 404-Meldungen per [http://aktuell.de.selfhtml.org/artikel/server/apacheconf/apconf16.htm#a3 Servereinstellungen] oder [http://de.selfhtml.org/servercgi/server/htaccess.htm#fehlermeldungen .htaccess] auf die 404-Seite von Contao weiterzuleiten. Dann werden auch nicht von Contao abgefangene Requests behandelt. Also nicht nur fehlerhafte Verlinkungen auf Contao-Seiten, sondern z.B. auch fehlerhaft eingebundene Bilder, CSS oder JavaScriptdateien berücksichtigt. Da dies jedoch auch zu Problemen führen kann gibt es die Möglichkeit nur Dateien mit speziellen Erweiterungen zu behandeln bzw. auszuschließen.

'''Zu behandelnde Dateierweiterungen:''' dies stellt eine durch Kommata separierte Liste von Dateierweiterungen dar (Beispiel: html,htm,php). Es werden dann nur Dateien mit dieser Erweiterung vom Modul behandelt. Für alle anderen Dateitypen gilt die Einstellung ''Behandlung anderer Anfragen''.

'''Behandlung anderer Anfragen''': Dies zeigt die Optionen, die für die Behandlung von Dateien außerhalb der Whitelist verwendet werden.
* die: Der Aufbau der Seite wird abgebrochen und eine 404-Meldung per [http://php.net/manual/de/function.die.php die] herausgegeben.
* nomail: Die Fehlermeldung wird wie gewohnt angezeigt und geloggt, jedoch wird keine Informationsmail versandt.
* nolog: Die Fehlermeldung wird wie gewohnt angezeigt und per Mail darüber informiert, sie wird jedoch nicht geloggt. Dies erhöht die Anzahl der Mails beträchtlich!
* nolognomail: Die Fehlermeldung wird wie gewohnt angezeigt, jedoch weder geloggt noch darüber per Mail informiert.

'''Erweiterungen, die für IE 8 behandelt werden sollen:''' dies stellt wie auch in der oberen Option eine durch Kommata separierte Liste von Dateierweiterungen dar, die vom Modul behandelt werden sollen. Diese Liste wird jedoch nur angewandt, wenn der Browser des Besuchers sich als Internet Explorer 8 identifiziert.

'''Behandlung anderer Anfragen mit dem IE 8:''' Wie ''Behandlung anderer Anfragen'', nur auf die Liste für den IE 8 angewandt.

'''Verwendung der Whitelist als Blacklist:''' Mit einem kleinen Trick ist es auch möglich die Liste der Dateierweiterungen als Blacklist zu verwenden. Hierfür einfach als erstes Stichwort in der Liste 'blacklist' verwenden. Beispiel: ''blacklist,js,css''

==Modul einbinden==

Das Modul wird entweder über ein Content Element in einen Artikel auf der Contao 404-Seite eingebunden, oder in das spezielle Layout für diese Seite geladen. Dort zeigt es dann je nach Einstellungen eine Fehlermeldung an und informiert über den Fehler per Datenbanklog oder Mail.

=Die Fehlermeldungen=

==Typen von Fehlermeldungen==

Es gibt vier Typen von Fehlermeldungen:
# Der Referrer konnte nicht ausgewertet werden => Vermutlich veraltetes Bookmark oder Adresse direkt eingegeben.
# Der Referrer entspricht der eigenen Webseite => ein falscher Link auf der eigenen Seite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für diese 404-Meldung gab.
# Der Referrer ist in der Liste der Suchmaschinen zu finden => abwarten und Tee trinken
# Der Referrer ist nicht in der Liste => Falscher Link von einer anderen Webseite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für die 404-Meldung gab.

==Anpassen der Fehlermeldungen==

{{Anmerkung|Die Fehlermeldungen befinden sich in der Sprachdatei ''~/system/modules/ext404/sprachcode/default.php''. Da sich die Sprachelemente in den globalen [http://www.contao.org/data-container-arrays.html DCA] von Contao befinden können sie da auch selbst updatesicher überschrieben werden.}}

==Testen der Fehlermeldungen==

Wenn man die Reaktion von Fehlermeldungen testen möchte, sollte man berücksichtigen, dass die Information per Mail pro falsch verlinkter Seite (Referrer+verlinkte Seite stimmen überein) nur einmal in 31 Tagen versendet wird. Deshalb sollte man beim Testen die Tabelle tl_ext404_log unter dem Punkt ''Systemwartung'' im Backend ab und zu leeren.

# Um den ersten Typ zu testen gibt ruft man einfach eine nicht existierende Seite auf. Beispiel http://de.contaowiki.org/blubb.html bzw. http://de.contaowiki.org/index.php/blubb.html
# Um den zweiten Typ zu testen gibt man einfach einen falschen Link in einem Artikel auf der eigenen Seite ein und klickt ihn an
# Um den dritten Typ zu testen editiert man die Datei ''~/system/modules/ext404/files/searchengines.txt'' und fügt da eine eigene Domain zur Liste hinzu, von wo aus man auf eine nicht existierende Seite im zu testenden Contao-Projekt verlinkt.
# Um den vierten Typ zu testen verlinkt man von einer Seite auf einer anderen Domain auf eine nicht existierende Seite im zu testenden Contao-Projekt.

=Weitere Mechanismen z.B. speziell für Suchmaschinen=

Um nicht ständig über fehlerhafte Verlinkungen von bestimmten Webseiten aus benachrichtigt zu werden, was vor allem bei Suchmaschinen mit nicht aktuellem Index nervig ist, werden diese speziell behandelt.

==Reverser IP-Lookup==

Gerade bei Suchmaschinen bekommt man als Referrer häufiger eine IP anstatt eine Adresse. Diese wird wenn möglich aufgelöst und in die allgemein üblichere Adresse umgewandelt.

==Liste der Suchmaschinen==

Eine Liste der Suchmaschinen ist in der Datei ''~/system/modules/ext404/files/searchengines.txt'' zu finden. Hierbei ist zu beachten, dass auch Subdomains oder andere Topleveldomains berücksichtigt werden können!

Der Eintrag ''google'' berücksichtigt also '''alle''' Topleveldomains wie google.de, google.com... sowie Subdomains wie maps.google.de

Die Einträge werden mit [http://php.net/manual/de/function.preg-quote.php preg_quote()] in einen regulären Eindruck eingefügt.

Ext404

2011-03-16T14:54:17Z

B2m: Von contao-forge.org portiert

{{stub}}
[[Category:Extensions]]
{{ExtInfo
| Dev=Benjamin Meier
| DevSite=http://www.meier-benjamin.de
| ExtVersion=0.9.2
| Version=2.9
| TLVersion=2.8
| ERLink=http://www.contao.org/erweiterungsliste/view/ext404.de.html
| DonateLink=http://www.amazon.de/registry/wishlist/2VDXQUM2K10V5/?sort=priority
| TrackerLink=https://github.com/b2m/ext404/issues
}}

=Verwendung=

==Modul anlegen==

Das Modul ext404 wird entweder über einen Artikel, oder über ein spezifisches Seitenlayout in die spezielle 404-Seite von Contao eingebunden. Hierfür muss ein neues Modul angelegt vom Typ '''Verschiedenes/Extended 404''' werden.

===Maileinstellungen===

* Empfänger Mailadresse: an diese Mailadresse werden Informationen über fehlerhafte Verlinkungen versendet. Ist das Feld leer, so werden keine Fehlerbenachrichtigungen versendet.
* Absender Mailadresse: diese Mailadresse wird als Absender der Fehlerbenachrichtigungen per E-Mail verwendet. Ist dieses Feld leer, so werden keine Fehlerbenachrichtigungen versendet.

{{Hinweis|Es genügt also schon ein leeres Feld (Empfänger "oder" Absender) um den Mailversand zu deaktivieren!}}

===Behandlung von Dateierweiterungen===

Es ist natürlich möglich die Standard 404-Meldungen per [http://aktuell.de.selfhtml.org/artikel/server/apacheconf/apconf16.htm#a3 Servereinstellungen] oder [http://de.selfhtml.org/servercgi/server/htaccess.htm#fehlermeldungen .htaccess] auf die 404-Seite von Contao weiterzuleiten. Dann werden auch nicht von Contao abgefangene Requests behandelt. Also nicht nur fehlerhafte Verlinkungen auf Contao-Seiten, sondern z.B. auch fehlerhaft eingebundene Bilder, CSS oder JavaScriptdateien berücksichtigt. Da dies jedoch auch zu Problemen führen kann gibt es die Möglichkeit nur Dateien mit speziellen Erweiterungen zu behandeln bzw. auszuschließen.

'''Zu behandelnde Dateierweiterungen:''' dies stellt eine durch Kommata separierte Liste von Dateierweiterungen dar (Beispiel: html,htm,php). Es werden dann nur Dateien mit dieser Erweiterung vom Modul behandelt. Für alle anderen Dateitypen gilt die Einstellung ''Behandlung anderer Anfragen''.

'''Behandlung anderer Anfragen''': Dies zeigt die Optionen, die für die Behandlung von Dateien außerhalb der Whitelist verwendet werden.
* die: Der Aufbau der Seite wird abgebrochen und eine 404-Meldung per [http://php.net/manual/de/function.die.php die] herausgegeben.
* nomail: Die Fehlermeldung wird wie gewohnt angezeigt und geloggt, jedoch wird keine Informationsmail versandt.
* nolog: Die Fehlermeldung wird wie gewohnt angezeigt und per Mail darüber informiert, sie wird jedoch nicht geloggt. Dies erhöht die Anzahl der Mails beträchtlich!
* nolognomail: Die Fehlermeldung wird wie gewohnt angezeigt, jedoch weder geloggt noch darüber per Mail informiert.

'''Erweiterungen, die für IE 8 behandelt werden sollen:''' dies stellt wie auch in der oberen Option eine durch Kommata separierte Liste von Dateierweiterungen dar, die vom Modul behandelt werden sollen. Diese Liste wird jedoch nur angewandt, wenn der Browser des Besuchers sich als Internet Explorer 8 identifiziert.

'''Behandlung anderer Anfragen mit dem IE 8:''' Wie ''Behandlung anderer Anfragen'', nur auf die Liste für den IE 8 angewandt.

'''Verwendung der Whitelist als Blacklist:''' Mit einem kleinen Trick ist es auch möglich die Liste der Dateierweiterungen als Blacklist zu verwenden. Hierfür einfach als erstes Stichwort in der Liste 'blacklist' verwenden. Beispiel: ''blacklist,js,css''

==Modul einbinden==

Das Modul wird entweder über ein Content Element in einen Artikel auf der Contao 404-Seite eingebunden, oder in das spezielle Layout für diese Seite geladen. Dort zeigt es dann je nach Einstellungen eine Fehlermeldung an und informiert über den Fehler per Datenbanklog oder Mail.

=Die Fehlermeldungen=

==Typen von Fehlermeldungen==

Es gibt vier Typen von Fehlermeldungen:
# Der Referrer konnte nicht ausgewertet werden => Vermutlich veraltetes Bookmark oder Adresse direkt eingegeben.
# Der Referrer entspricht der eigenen Webseite => ein falscher Link auf der eigenen Seite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für diese 404-Meldung gab.
# Der Referrer ist in der Liste der Suchmaschinen zu finden => abwarten und Tee trinken
# Der Referrer ist nicht in der Liste => Falscher Link von einer anderen Webseite, Information per Mail wenn es innerhalb der letzten 31 Tage keinen Logeintrag für die 404-Meldung gab.

==Anpassen der Fehlermeldungen==

{{Anmerkung|Die Fehlermeldungen befinden sich in der Sprachdatei ''~/system/modules/ext404/sprachcode/default.php''. Da sich die Sprachelemente in den globalen [http://www.contao.org/data-container-arrays.html DCA] von Contao befinden können sie da auch selbst updatesicher überschrieben werden.}}

==Testen der Fehlermeldungen==

Wenn man die Reaktion von Fehlermeldungen testen möchte, sollte man berücksichtigen, dass die Information per Mail pro falsch verlinkter Seite (Referrer+verlinkte Seite stimmen überein) nur einmal in 31 Tagen versendet wird. Deshalb sollte man beim Testen die Tabelle tl_ext404_log unter dem Punkt ''Systemwartung'' im Backend ab und zu leeren.

# Um den ersten Typ zu testen gibt ruft man einfach eine nicht existierende Seite auf. Beispiel http://de.contaowiki.org/blubb.html bzw. http://de.contaowiki.org/index.php/blubb.html
# Um den zweiten Typ zu testen gibt man einfach einen falschen Link in einem Artikel auf der eigenen Seite ein und klickt ihn an
# Um den dritten Typ zu testen editiert man die Datei ''~/system/modules/ext404/files/searchengines.txt'' und fügt da eine eigene Domain zur Liste hinzu, von wo aus man auf eine nicht existierende Seite im zu testenden Contao-Projekt verlinkt.
# Um den vierten Typ zu testen verlinkt man von einer Seite auf einer anderen Domain auf eine nicht existierende Seite im zu testenden Contao-Projekt.

=Weitere Mechanismen z.B. speziell für Suchmaschinen=

Um nicht ständig über fehlerhafte Verlinkungen von bestimmten Webseiten aus benachrichtigt zu werden, was vor allem bei Suchmaschinen mit nicht aktuellem Index nervig ist, werden diese speziell behandelt.

==Reverser IP-Lookup==

Gerade bei Suchmaschinen bekommt man als Referrer häufiger eine IP anstatt eine Adresse. Diese wird wenn möglich aufgelöst und in die allgemein üblichere Adresse umgewandelt.

==Liste der Suchmaschinen==

Eine Liste der Suchmaschinen ist in der Datei ''~/system/modules/ext404/files/searchengines.txt'' zu finden. Hierbei ist zu beachten, dass auch Subdomains oder andere Topleveldomains berücksichtigt werden können!

Der Eintrag ''google'' berücksichtigt also '''alle''' Topleveldomains wie google.de, google.com... sowie Subdomains wie maps.google.de

Die Einträge werden mit [http://php.net/manual/de/function.preg-quote.php preg_quote()] in einen regulären Eindruck eingefügt.