Comment réaliser des requêtes AJAX avec OctoberCMS

OctoberCMS permet de réaliser sans aucune connaissance en JavaScript des requêtes AJAX de facon simple et intuitive tout en permettant des fonctionnalités avancées tel que l'envoi de fichiers ou la gestion d'erreurs de validation de formulaires.

Les requêtes AJAX

Les requêtes AJAX sont aujourd'hui très largement utilisées dans bon nombre de sites internet, elles permettent d'exécuter des actions et/ou de retourner des données à afficher au visiteur en la modifiant sans rafraîchir la page. Elles reposent sur l'utilisation de JavaScript, avec des methodes plus ou moins complexes selon l'environement et la tâche à accomplir.

Comment les réaliser avec OctoberCMS

Grâce à OctoberCMS, qui les implémente à l'aide d'un framework spécialement conçu, il devient possible de réaliser des requêtes AJAX sans même une seule ligne de JavaScript grâce l'API des attributs de données. Vous n'avez qu'à donner les indications à l'aide d'attributs data- dans votre HTML sur le formulaire, le bouton, le lien, ou autre élément déclencheur de l'appel asynchrone au serveur, et le système se charge du reste. Vous pouvez toutefois utiliser l'API JavaScript, qui permet des actions plus avancées et qui reste cependant elle aussi très simple à mettre en place.

Les gestionnaires d'évènements, ces fonctions PHP répondant à la requête AJAX peuvent êtres globales ou locales selon si elles sont définies dans le layout, une page ou un composant de plugin.

Il vous est même possible de réaliser très simplement un formulaire comportant un chargement de fichier grâce aux fonctionnalités supplémentaires.

Entre autres fonctionnalités très simples et intuitives à mettre en place, retrouvez dans la documentation traduite du site officiel comment:

• retourner des messages d'erreurs ou de succès à afficher au visiteur
• afficher les erreurs de validation de formulaire (de plusieurs façons differentes: seulement la première erreur, toutes en liste, ou toutes à côté de leur champs respectifs)
• mettre à jour la page sans rafraichissement ou afficher un état de chargement durant la requête.

Exemples

Retrouvez dans la documentation des exemples d'utilisation tel que les suivants:

Afficher un message de succès

<form
    data-request="onSuccess"
    data-request-flash>
    <!-- ... -->
</form>

Combiné à l'utilisation de ce gestionnaire AJAX

function onSuccess()
{
    // Exécution de la logique

    if($success) {
        Flash::success('Vous avez réussi!');
    } else {
        Flash::error("Une erreur s'est produite!");
    }
}

Et à ce markup dans votre layout afin de définir un aspect similaire sur toutes vos pages

{% flash %}
    <p
        data-control="flash-message"
        class="flash-message fade {{ type }}"
        data-interval="5">
        {{ message }}
    </p>
{% endflash %}

Validation de formulaire

<form
    data-request="onDoSomething"
    data-request-validate
    data-request-flash>

    <div>
        <input name="name" />
        <span data-validate-for="name"></span>
    </div>

    <div>
        <input name="email" />
        <span data-validate-for="email"></span>
    </div>

    <button data-attach-loading>
        Submit
    </button>

    <div class="alert alert-danger" data-validate-error>
        <p data-message></p>
    </div>

</form>

Associé à ce gestionnaire AJAX

function onDoSomething()
{
    $data = post();

    $rules = [
        'name' => 'required',
        'email' => 'required|email',
    ];

    $validation = Validator::make($data, $rules);

    if ($validation->fails()) {
        throw new ValidationException($validation);
    }

    Flash::success('Action effectuée avec succès!');
}