Endpoint /web

La classe EwtWebServlet est habituellement mappée sur l'url-pattern /web et prend en charge les requêtes GET et POST envoyées depuis un navigateur.

Dans le cas des requêtes GET, le servlet analyse l'URL et retourne généralement la page d'accueil de l'application concernée.

Dans le cas des requêtes POST, le servlet traite le formulaire reçu. La servlet supporte les formulaires de type url-encoded et multipart. Les deux types de formulaires sont traitées de manière transparente et unifiée, si bien que les requêtes de formulaire peuvent utiliser l'un ou l'autre de ces types d'encodage, voire les deux en alternance. L'idée est d'utiliser url-encoded en standard, et de basculer sur multipart si une donnée binaire doit être envoyée à l'application.

Charset des formulaires multipart

Par défaut Ewt traite tous les formulaires HTML en partant du principe qu'ils utilisent le charset UTF-8. Il se peut toutefois que l'on doive envoyer des données multipart dans un autre charset.

Les navigateurs actuels ne véhiculent pas le charset. Pour permettre à la page web d'indiquer à Ewt quel charset il doit utiliser pour le parsing du formulaire multipart, il est possible d'ajouter un paramètre _charset dans l'URL. Lorsque ce paramètre est spécifié, les données textuelles présentes dans le multipart sont interprétées selon le charset indiqué.

Exemple de formulaire HTML forçant le charset iso-8859-1:

<form id="form" method="post"
      action="{/output/session/formAction}?_charset=iso-8859-1"
      accept-charset="ISO-8859-1"
      enctype="multipart/form-data"
      autocomplete="off">

Commandes et actions

Les commandes sont les ordres envoyés à Ewt au moyen un formulaire HTML posté sur le servlet /web. Elles entraînent une action à faire par le moteur. Commande et action sont liées : la commande est le moyen de communiquer une action au moteur.

La commande est décrite au moyen d'un arbre json structuré ainsi:

{
  "action": "some_action",
  "params": {
    "name": "sample",
    "parameters": {
        "var1": "foo",
        "var2": "bar",
        ...
    }
  }, 
  "supplement": {
    ...
  }
}

Le prototype de chaque action spécifie le schéma json de l'arbre attendu.

Une commande est généralement constituée de deux éléments:

1. [requis] Le nom de l'action qui est véhiculé au moyen de la propriété action
2. [optionnel] Les paramètres d'appel, véhiculés au moyen de la propriété params.
   Chaque action attend des paramètres spécifiques, voire aucun paramètre dans certains cas. Les paramètres sont des paires clé/valeur où la clé est une chaîne de caractères et la valeur une valeur litérale, un tableau ou n'importe quel type d'objet. Se reporter au prototype de chaque action pour en connaître la liste et la forme

La commande est doit être transmise à Ewt via un champ de formulaire portant le nom EWT:COMMAND. La valeur elle-même doit être une chaîne de caractères respectant la convention de notation json. Le plus simple pour ce faire est de définir la commande en objet javascript puis d'utiliser JSON.stringify sur l'objet pour le convertir. Le moteur accepte également la commande ainsi sérialisée au format base64.

Le moteur implémente les actions suivantes.

• addTuple
• admin
• arrange
• clone
• close
• create
• delete
• delTuple
• dummy
• open
• reset
• save
• script
• setLocale
• setState
• setStyle
• setView

Contexte

La commande peut être accompagnée d'un contexte. Le contexte est utile car il permet de préciser sur quel dossier porte la commande. Sans contexte, le moteur ne saurait pas sur quel dossier appliquer la commande, ce qui est problématique lorsque l'on a plusieurs dossiers ouverts à la fois.

Le contexte est à transmettre via le champ de formulaire portant le nom EWT:CONTEXT. La valeur de contexte doit être un hash à reprendre de l'arbre de sortie généré par Ewt.

Options

Il est possible de passer des options via le champ EWT:OPTIONS du formulaire. Comme pour le cas des commandes, la valeur attendue est la représentation sérialisée d'un objet javascript. En encodage en base64 est accepté.

Les options reconnues par la version actuelle du moteur sont les suivantes:

newSession boolean

Demande au moteur de créer une nouvelle session.

Habituellement les requêtes POST ne créent pas de session. Or il peut arriver que l'on souhaite afficher le résultat de la requête dans une nouvelle fenêtre ou un nouvel onglet du navigateur.

Il est dans ce cas nécessaire d'activer l'option, sans quoi les deux onglets vont partager la même session, ce qui est une source de conflits et d'effets de bord à éviter.

Lorsqu'une requête POST envoie le champ formulaire EWT:OPTIONS avec la valeur { "newSession": true }, le moteur commence par vérifier que la requête est valide (vérification du token CSRF) puis crée une nouvelle session pour la réponse.

delSession boolean

Demande au moteur de supprimer la session courante.

Cette option permet de libérer des ressources du serveur en supprimant les sessions qui n'ont plus lieu d'être. Elle peut être envoyée depuis un worker à la fermeture d'un navigateur ou d'un onglet. Le moteur se charge de supprimer la session au niveau de la table ewt_sessions de l'application.

Lorsque cette option est activée, le moteur n'exécute aucune action et retourne un statut HTTP 204 avec un payload vide.

L'action peut être déclenchée depuis une page web à l'aide des commandes suivantes:

document.getElementsByName('EWT:OPTIONS')[0].value =
   JSON.stringify({ delSession: true });
document.querySelector('form').submit();

À noter que le moteur intègre un mécanisme automatique de suppression des sessions expirées.