tibi-starter/docs/md/projektkonfig/collections/hooks.md

hooks

Hooks in Tibi sind spezielle Funktionen, die bestimmte Teile der HTTP-Anfragen und -Antworten manipulieren können. Sie erlauben Ihnen, den Datenfluss und die Abläufe zu bestimmten Zeitpunkten im Lebenszyklus einer HTTP-Anfrage zu beeinflussen.

Jeder Hook ist einer bestimmten HTTP-Methode (z.B. GET, POST, PUT, DELETE) und einem bestimmten Schritt in diesem Prozess zugeordnet. Die verfügbaren Schritte variieren je nach Methode und können beinhalten:

• read (GET)
• return (GET, POST, PUT, DELETE)
• bind (POST, PUT)
• validate (POST, PUT)
• create (POST)
• update (PUT)
• delete (DELETE)

Jeder dieser Schritte wird an einem spezifischen Punkt während der Verarbeitung einer HTTP-Anfrage oder -Antwort ausgeführt. Die genaue Reihenfolge und das Verhalten der Hooks ist in dem betrag zur Collection definiert.

Hook Implementierung

Jeder Hook ist in einer separaten JavaScript-Datei implementiert, die im hooks-Ordner Ihres Projekts gespeichert ist. Der Pfad zu dieser Datei wird in der jeweiligen collection yml Datei angegeben.

Ein Hook ist eine Funktion, die eine context-Variable zur Verfügung hat, welche Informationen und Methoden für die aktuelle Anfrage bereitstellt. Der Rückgabewert dieser Funktion wird verwendet, um die Verarbeitung der Anfrage oder Antwort zu beeinflussen.

Zwei spezielle Typen, HookResponse und HookException, werden in Hooks verwendet, um Daten zu manipulieren und Fehler zu signalisieren.

HookResponse

Die HookResponse ist das Objekt, das von einem Hook zurückgegeben wird. Es kann verwendet werden, um Daten zu manipulieren, die in die Datenbank geschrieben oder an den Benutzer zurückgegeben werden.

Es beinhaltet:

• data: Daten, die in die Datenbank geschrieben werden. Sie können diese Daten im Hook ändern, bevor sie in die Datenbank geschrieben werden.
• results: Daten, die an den Benutzer zurückgegeben werden. Sie können diese Daten im Hook ändern, bevor sie an den Benutzer zurückgegeben werden. (return hook)

HookException

Eine HookException ist ein Fehler, der in einem Hook geworfen werden kann. Sie können eine HookException verwenden, um einen Fehler zu signalisieren und die Verarbeitung der Anfrage oder Antwort zu stoppen. Er kann aber auch verwendet werden, um einen 200er zu werfen und zu verhindern, dass irgendetwas in die Datenbank geschrieben wird. Dies ist bei einer "actions" collection vom vorteil.

Eine HookException kann folgende Eigenschaften haben:

• status: HTTP-Statuscode des Fehlers.
• html: HTML-Nachricht des Fehlers.
• message: Textnachricht des Fehlers.
• bytes: Binäre Daten des Fehlers.
• json: JSON-Daten des Fehlers.
• file: Dateipfad der Fehlermeldung.
• log: Wenn true, wird der Fehler im Serverprotokoll aufgezeichnet.

Hook Beispiel

Hier ist ein Beispiel für einen Hook, der die GET-Methode bearbeitet:

;(function () {
    /** @type {HookResponse}*/ // @ts-ignore
    let hookResponse
    let request = context.request()
    if (request.query("rateIt")) {
        let orderNumber
        orderNumber = Number(request.query("orderNumber"))

        if (isNaN(orderNumber))
            throw {
                status: 400,
                message: "Invalid order number.",
            }

        /** @type {Order} */ // @ts-ignore
        let order = context.db.find("order", {
            filter: {
                sequence: orderNumber,
            },
        })[0]

        if (!order)
            throw {
                status: 400,
                message: "No entry with this order number.",
            }

        if (order.deliveryAddress.postcode != request.query("postalcode"))
            throw {
                status: 403,
                message: "Error",
            }

        hookResponse = {
            filter: {
                orderId: order.id,
            },
        }

        return hookResponse
    }
})()

In diesem Beispiel wird zuerst die Anfrage analysiert und eine Bedingung überprüft. Wenn die Bedingung erfüllt ist, wird ein bestimmtes Element in der Datenbank gesucht. Wenn das Element gefunden wird und bestimmte Kriterien erfüllt, wird ein HookResponse-Objekt erstellt und zurückgegeben. Wenn während des Prozesses Fehler auftreten, werden entsprechende HookException-Objekte geworfen.

Hier ist ein beispiel für einen Posthook, welcher ein dynamisches formular validiert (Post create):

!!!include(../api/hooks/forms/post_create.js)!!!

Hier ist ein beispiel für einen Posthook, welcher ein dynamisches formular abschickt (Post return):

!!!include(../api/hooks/forms/post_return.js)!!!