JSON Request in TYPO3 einrichten

Was ist JSON Request?

JSON Request ist ein Protokoll, das es Entwicklern ermöglicht, einfache Anfragen an TYPO3 zu senden. Diese Anfragen können entweder über einen Webbrowser oder über eine API gestellt werden. JSON Request bietet viele Vorteile gegenüber anderen Protokollen, da es sehr einfach zu verstehen und zu implementieren ist.

Es ist im Wesentlichen eine reine Textdatei, bestehend aus einfachen Strings in einem bestimmten Format. Es gibt sowohl im JavaScript als auch in PHP native Funktionen um JSON Strings zu kodieren und zu dekodieren.

Diese Funktionen stehen auch jedem modernen Browser zur Verfügung, was den Einsatz in der heutigen Zeit als sicher gestaltet.

Wie richte ich einen JSON Request in TYPO3 ein?

Um ein JSON Request einzurichten, benötigen wir eine PAGE Konfiguration und eine Extension, die den Request verarbeitet.

Kickstart einer Extension

Die beste Praxis ist es, dass wir alle notwendigen Konfiguration in einer Extension kapseln. Denn in der Regel wollen wir eine bestimmte Funktion ausführen und dazu brauchen wir ohnehin eine Extension.

Eine Extension lässt sich am einfachsten mit dem Extension-Builder erstellen. Diesen habe ich dir im kostenfreien TYPO3 Crashkurs für Entwickler bereits vorgestellt.

PAGE Konfiguration für JSON Requests

Nachdem die eigene Extension erstellt wurde, binden wir das StaticTS in TYPO3 ein und können beginnen die PAGE Konfiguration innerhalb der setup.typoscript vorzunehmen.

Das TypoScript Objekt PAGE konfiguriert die Rahmenbedingungen einer Seite. Darunter wird konfiguriert, was zurückgeliefert werden soll, wenn ein Request auf TYPO3 gestartet wird.

Wir erstellen ein neues PAGE Objekt im TypoScript wie folgt:

pageJSON = PAGE

Hierbei müssen wir sicherstellen, dass es noch keine Variable mit dem Namen: pageJSON im TypoScript gibt.

Da wir spätestens jetzt mehrere PAGE - Objekte im System haben, müssen wir eine Ziffer in der Eigenschaft: typeNum setzen. Diese Ziffer werden wir dann für die Request benötigen und diese Ziffer muss frei sein. Es darf also kein weiteres PAGE Objekt mit dem gleichen typeNum - Wert geben.

In meinem Fall setze ich typeNum auf 1:

pageJSON {
  typeNum = 1
}

Die Startwerte des PAGE - Objektes nach Erstellung sind so gewählt, dass ein HTML Dokument zurückgeliefert wird. Das müssen wir nun ändern.

Das geht sehr einfach mit folgender Konfiguration:

pageJSON {
   config {
      disableAllHeaderCode = 1
      additionalHeaders.10.header = Content-type:application/json
      admPanel = 0
   }
}

In Zeile 3 deaktivieren wir die automatische Erstellung diverser HTML relevanten Teile. Kurz gesagt ist damit die Auslieferung eines HTML Dokumentes deaktiviert.

Jetzt müssen wir einer eigenen Content-Type angeben, was in unserem Fall in Zeile 4 gemacht und auf JSON gesetzt wird.

Abschließend in Zeile 5 deaktivieren wir die Adminkonsole, was ein HTML Widget ist.

Damit haben wir unser PAGE Objekt so weit konfiguriert, dass nun ein Dokument vom Content-Type: application/json zurückgeliefert wird. 

Dieses Dokument ist noch leer, weil wir noch keine Ausgabenummer definiert haben. Und hier kommt unsere Extension ins Spiel.

Wir rufen hier unterhalb einer Ausgabenummer ein Frontend Plugin auf, was dann die JSON Antwort zurückliefert.

Dazu müssen wir jetzt in unserer Extension ein solches Frontend Plugin erstellen.

Frontend Plugin erstellen

Ein Frontend Plugin registrieren wir in der ext_localconf.php Datei wie folgt:

\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin(
   'JsonExample',
   'Example',
   [\Slavlee\JsonExample\Controller\JsonController\JsonController::class => 'show'],
   [\Slavlee\JsonExample\Controller\JsonController\JsonController::class => 'show']
);

In Zeile 2 kommt der Name der Extension, in Zeile 3 ein eindeutige Identifier, innerhalb deiner Liste an Frontend Plugins, für das Plugin. 

In Zeile 4 ist ein Array von Controller -> Action - Methoden Paaren. Der erste Controller und die erste Action-Methode werden aufgerufen, wenn nichts anderes angegeben wird. In unserem Fall ist also die Methode: showAction innerhalb von JsonController die Funktion, die beim JSON Request ausgeführt wird.
In Zeile 5 werden alle Controller -> Action - Methoden Paaren aufgelistet, deren Cache mal deaktivieren möchte.

Als Nächstes erstellen wir die Controller Klasse mit der jeweiligen Action - Methode. Die Controller Klasse wird unterhalb von json_example/Classes/Controller/JsonController.php erstellt:

namespace Slavlee\JsonExample\Controller;

use Psr\Http\Message\ResponseInterface

class JsonController extends \TYPO3\CMS\Extbase\Mvc\Controller\AbstractController
{
    public function showAction(): ResponseInterface
    {
        $data = [];
        $jsonOutput = json_encode($data);
        return $this->jsonResponse($jsonOutput);
    }
}

Der ActionController für ein JSON Request ist mittlerweile identisch zu einem normalen ActionController. Der Unterschied liegt im Aufruf in Zeile 11. Dort wird die Klassenmethode: jsonResponse genutzt, welche alles Weitere erledigt.

Du kannst also jetzt ausgehend der showAction - Funktion alle Daten zusammenstellen, die du als JSON String zurückgeben möchtest. Dabei empfehle ich dir, diese in einem assoziativen Array zu speichern. 

Dieses Array wird dann per json_encode enkodiert und abschließend der View als JSON Response übergeben.

Der Rest erledigt TYPO3 mithilfe deiner PAGE Konfiguration.

Wie kann ich ein JSON Request auslösen?

Um letzten Endes ein JSON Request auszuführen, muss man entweder einen Link erzeugen, auf den der Benutzer klicken muss oder man erzeugt eine URI die man dann per JavaScript aufruft.

Link generieren

Ein Link kann man in Fluid sehr leicht mit dem LinkViewHelper generieren. Eine Lösung ist die folgende:

<f:link.page pageUid="1" additionalParams="{foo: 'bar'}" pageType="1">page link</f:link.page>

Der LinkViewHelper gibt es uns mehrere Attribute, mit denen wir Einfluss auf den Link nehmen können. Wir können die Seiten-ID angeben, Parameter übergeben und den Page Type definieren.

Die Seiten-ID ist optional, wenn wir diese weglassen, dann wird die aktuelle Seite genommen. Über additionalParams können wir unserer Action-Methode Parameter mitgeben und dort verarbeiten.

Das wichtigste Attribut für uns ist pageType. Der Wert von pageType muss einem gültigen typeNum - Wert entsprechend eines vorhandenen PAGE - Objektes.

Um das PAGE Objekt von pageJSON zu nutzen, müssen wir also den Wert: 1 angeben.

Damit sucht TYPO3 ein PAGE Objekt mit dem typeNum - Wert 1 und nutzt dieses Objekt zur Beantwortung dieses Requests. Sprich: Es wird das Frontend Plugin JsonExample ausgeführt und damit unsere dort erstellte JSON String zurückgeliefert.

Uri generieren

Eine weitere Möglichkeit ist es im Template eine URI zu generieren und den Wert beispielsweise eine JavaScript Variable zuzuordnen. 

Der UriViewHelper nutzt sich genauso, wie der LinkViewHelper:

var jsonUri = '<f:uri.page pageUid="1" additionalParams="{foo: 'bar'}" typeNum="1" absolute="1" />';

Die generierte URL können wir dann im JavaScript nutzen um an gezielter Stelle ein AJAX Request zu starten. In jQuery würde das so aussehen:

$.get(jsonUri, function(data){

});

Fazit

Die Konfiguration einer JSON Response in TYPO3 ist sehr einfach geworden. Man muss lediglich die jsonResponse - Methode des AbstractControllers aufrufen und mit einem PAGE - Objekt sicherstellen, dass ein Content-Type: application/json zurückgeliefert wird.

Das ist auch die grundsätzliche Vorgehensweise, wie man andere Formate in TYPO3 zurückgeben kann, abweichend von HTML.

Es ist in der Regel eine Kombination aus PAGE - Objekt mit einem definierten typeNum - Wert und einem Frontend Plugin.