Égayez votre site Astro avec KwesForms et Rive —

Dans cet article, je vais vous montrer comment ajouter KwesForms à ton Astro site, puis donnez vie au formulaire à l’aide d’événements personnalisés et Rive.

Des événements personnalisés peuvent être utilisés pour contrôler les différents états d’une animation Rive chaque fois qu’un « événement » dans le formulaire se produit. Cela peut se produire lorsqu’un champ devient invalide ou lorsque le formulaire a été soumis avec succès.

Si vous souhaitez aller de l’avant, j’ai créé un exemple de dépôt contenant tout le code et un aperçu en direct :

Premiers pas avec Astro

Pour démarrer avec Astro, vous disposez de plusieurs options. Vous pouvez soit suivre le directives pour l’installation d’Astro avec le CLI automatiqueou (mon approche préférée) installer Astro manuellement.

Créer une page

Si vous avez installé Astro manuellement, créez un nouveau fichier appelé index.astro dans le répertoire suivant : src/pages.

Créer un composant

Créez un nouveau fichier appelé rive-form.astro dans le src/components annuaire.

Ajouter le composant à la page

Ajoutez ce qui suit pour afficher le composant RiveForm dans la page d’index :

---
import RiveForm from '../components/rive-form.astro';
---

<RiveForm />

Pour le reste de cet article, j’ajouterai du code au rive-form.astro déposer.

Le src peut être vu dans le dépôt ici : rive-kwes-forms/src/pages/index.astro.

Premiers pas avec KwesForms

j’ai utilisé KwesForms pour un projet client récemment et j’ai adoré l’expérience. Il existe, bien sûr, de nombreuses façons de gérer les données d’un formulaire, mais j’ai trouvé que l’utilisation de KwesForms a vraiment contribué à simplifier l’exigence d’une validation côté client et côté serveur !

Pour commencer, allez-y et s’inscrire (c’est gratuit). Il existe deux manières d’inclure le code KwesFroms dans votre site : vous pouvez soit l’installer via npm, soit utiliser un élément de script. Dans cet exemple, j’utiliserai l’élément script.

Les cinq étapes restantes de la section de configuration vous guideront dans la manière d’ajouter un élément de formulaire HTML à votre site.

Ajout du script KwesFroms à Astro

Lorsque vous utilisez des scripts côté client avec Astro, vous souhaiterez peut-être se retirer du traitement en utilisant le is:inline directif. Cela indique à Astro de laisser le script tranquille et de le restituer dans le HTML en tant qu’élément de script.

Dans ton rive-form.astro fichier, ajoutez ce qui suit :

// src/components/rive-form.astro

- <script src="https://kwesforms.com/v2/kwes-script.js" defer></script>
+ <script is:inline src="https://kwesforms.com/v2/kwes-script.js" defer></script>

Ajout de KwesForms HTML

Voici le code que j’ai utilisé dans l’exemple (en utilisant Vent arrière) :

// src/components/rive-form.astro

<script is:inline src="https://kwesforms.com/v2/kwes-script.js" defer></script>

<form
  id="riveForm"
  class="kwes-form flex flex-col gap-6"
  action="https://kwesforms.com/api/foreign/forms/abc123"
  data-kw-no-reload
>
  <div class="flex gap-4">
    <div class="grow">
      <label for="name">Name</label>
      <input id="riveFormName" type="text" name="name" data-kw-rules="required" />
    </div>
    <div class="grow">
      <label for="email">Email</label>
      <input id="riveFormEmail" type="email" name="email" data-kw-rules="required|email" required />
    </div>
  </div>
  <div>
    <label for="name">Message</label>
    <textarea id="riveFormMessage" name="message" rows="4" data-kw-rules="required"></textarea>
  </div>
  <button type="submit">Send Message</button>
</form>

Le src peut être vu dans le dépôt ici : rive-kwes-forms/src/components.rive-form.astro.

J’ai utilisé quelques attributs pour configurer mon formulaire. Vous remarquerez sur toutes les entrées que j’ai ajouté les éléments suivants : data-kw-rules="required". Cela indique à KwesFroms que ces champs doivent contenir une valeur avant que le formulaire puisse être considéré comme valide. J’ai utilisé un attribut supplémentaire dans le champ e-mail pour garantir que seules des adresses e-mail valides sont utilisées. Par exemple : data-kw-rules="required|email".

Vous pouvez voir toutes les règles de validation dans les KwesForms documentation du formulaire.

Une fois le formulaire configuré, il est maintenant temps d’ajouter une animation Rive.

Qu’est-ce que Rive ?

Rive est super cool, car il permet aux concepteurs et aux animateurs de créer une animation à l’aide d’une interface basée sur un navigateur, et une fois terminée, les développeurs peuvent simplement télécharger un fichier.

Modification de la configuration Vite d’Astro

Pour utiliser un .riv fichier avec Astro, une petite quantité de configuration est requise pour que le compilateur Astro sache quoi faire avec les fichiers qui se terminent par .riv.

Pour utiliser Rive avec Astro, ajoutez ce qui suit à votre astro.config.mjs déposer:

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    assetsInclude: ['**/*.riv'],
  },
});

Télécharger l’animation Rive

L’étape suivante consiste à trouver une animation Rive à utiliser ou, si vous vous sentez créatif, vous pouvez créer la vôtre. Il y a des tas de communauté exemples qui peuvent être téléchargés et utilisés gratuitement.

Le fichier que j’utilise, Personnage de connexion animéa été créé par Juan Carlos Cruz de l’équipe Rive. Pour commencer, téléchargez le fichier et enregistrez-le dans votre répertoire public.

J’ai gardé le mien dans public/rive/2244-7248-animated-login-character.riv.

Le src peut être vu dans le dépôt ici : rive-kwes-forms/public/rive.

Initialisation de Rive

Pour initialiser le canevas Rive, ajoutez ce qui suit à votre rive-form.astro déposer:

// src/components/rive-form.astro

<script>
  const r = new rive.Rive({
    src: '/rive/2244-7248-animated-login-character.riv',
    canvas: document.getElementById('canvas'),
    autoplay: true,
    stateMachines: 'Login Machine',
  });
</script>
<script is:inline src="https://unpkg.com/@rive-app/canvas@2.7.0"></script>
<canvas id="canvas" width="800" height="600"></canvas>

La partie suivante consiste à ajouter des écouteurs d’événements à chacun des éléments du formulaire afin qu’ils puissent lancer l’animation Rive dans ses différents états d’animation.

Machines à états rive

Vous verrez sur la page de téléchargement que cette animation a un certain nombre « d’états » définis. Ce sont les différents états de l’animation qui peuvent être déclenchés lorsque certains événements du formulaire se produisent.

Rive machines à états peut être l’un des types suivants :

• un déclencheur qui a un fire() fonction
• un nombre qui a une propriété de nombre de valeur
• un booléen qui a une propriété booléenne de valeur

Le type de machines à états définies dans une animation déterminera la manière dont vous les invoquerez à partir des écouteurs d’événements de votre formulaire. (J’y reviendrai dans un instant.)

Ajout d’écouteurs d’événements

J’ai donné à chaque champ du formulaire un id attribut, et à partir de là, je peux attacher les écouteurs d’événement requis pour chaque événement que je souhaite exploiter.

Ces événements sont spécifiques à KwesForms. Vous pouvez voir tous les événements personnalisés dans le Documentation KwesForms. Voici le code du formulaire :

const form = document.getElementById('riveForm');

form.addEventListener('kwSubmitted', function () {
  console.log('form: kwSubmitted');
});

form.addEventListener('kwHasErrors', () => {
  console.log('form: kwHasErrors');
});

Et voici le code du champ email. Ce sont les événements JavaScript standard pour se concentrer et se brouiller. J’ai ajouté la même chose pour les champs nom et message :

const name = document.getElementById('riveFormName');

name.addEventListener('focus', () => {
  console.log('name: focus');
});

name.addEventListener('blur', () => {
  console.log('name: blur');
});

Déclenchement des machines à états Rive à partir d’événements de formulaire

C’est là que tout s’assemble. Chaque fois qu’un événement de formulaire se produit, je peux invoquer l’un des états de l’animation.

Création d’une fonction getTrigger

Juste en dessous du code d’initialisation, ajoutez l’extrait de code suivant :

<script>
  const r = new rive.Rive({
  ...

+  const getTrigger = (name) => {
+    return r.stateMachineInputs('Login Machine').find((input) => input.name === name);
+  };

</script>

Cette fonction accepte un name paramètre. Il s’agit du nom de l’État tel que vu précédemment sur la page de téléchargement. La fonction renvoie une instance de Rive stateMachineInputsqui permet de définir des valeurs, ce qui à son tour propulse l’animation dans ses différents états.

Appel d’un déclencheur à partir d’un écouteur d’événement

Chaque fois que le formulaire contient des erreurs, je me connecte aux KwesForms kwHasErrors événement et appelez le trigFail déclencher à l’aide du fire fonction:

form.addEventListener('kwHasErrors', () => {
  console.log('form: kwHasErrors');
+  const trigger = getTrigger('trigFail');
+  trigger.fire();
});

Chaque fois que le champ de nom reçoit le focus, je définis isChecking à trueet partout où le champ de nom est flou, je définis isChecking à false:

name.addEventListener('focus', () => {
  console.log('name: focus');
+  const trigger = getTrigger('isChecking');
+  trigger.value = true;
});

name.addEventListener('blur', () => {
  console.log('name: blur');
+  const trigger = getTrigger('isChecking');
+  trigger.value = false;
});

Chaque fois que le champ e-mail reçoit le focus, je définis isHandsUp à trueet chaque fois que le champ email est flou, je définis isHandsUp à false:

email.addEventListener('focus', () => {
  console.log('email: focus');
+  const trigger = getTrigger('isHandsUp');
+  trigger.value = true;
});

email.addEventListener('blur', () => {
  console.log('email: blur');
+  const trigger = getTrigger('isHandsUp');
+  trigger.value = false;
})

Conclusion

En utilisant une combinaison d’événements KwesForms et d’événements JavaScript standard avec des animations Rive, les erreurs de formulaire peuvent apparaître de toutes les manières imaginables.

Si vous avez des questions concernant tout ce que j’ai abordé dans cet article, n’hésitez pas à venir me trouver sur Twitter/X : PaulieScanlon.

Vous voulez plus d’informations sur Astro ? Découvrez notre tout nouveau livre sur SitePoint Premium : Libérer la puissance d’Astrode Tamas Piros, qui vous montrera comment tirer le meilleur parti de ce cadre moderne tout-en-un pour créer des sites Web plus rapides et axés sur le contenu.