Aller au contenu
BDU Cauri, accueilv0.1.0
Démarrer

JavaScript

Les composants interactifs de Cauri (modale, menu déroulant, onglets, infobulles…) fonctionnent avec des attributs HTML, sans écrire de script. Pour aller plus loin, une API JavaScript permet de les piloter depuis votre code.

Fichiers

Deux fichiers indépendants. Le premier suffit pour tous les composants de Cauri ; le second n’est utile que pour le simulateur de prêt.

Fichiers
FichierContenuObjet global
cauri.bundle.min.jsLe JavaScript des composants interactifs, avec la bibliothèque de positionnement (infobulles, popovers, menus). Fichier compressé, accompagné de sa carte cauri.bundle.min.js.map.bootstrap
cauri.jsLes comportements propres à BDU : calcul du simulateur de prêt. Sans dépendance.Cauri

Composants disponibles

Composants disponibles
ClassePageRôle
bootstrap.AlertAlertesFermer une alerte
bootstrap.ButtonBoutonsBouton à bascule (état actif)
bootstrap.CarouselCarrouselFaire défiler des diapositives
bootstrap.CollapseRepliAfficher ou masquer un bloc (utilisé par l’accordéon et le menu mobile)
bootstrap.DropdownMenus déroulantsOuvrir un menu
bootstrap.ModalModaleBoîte de dialogue
bootstrap.OffcanvasOffcanvasPanneau latéral
bootstrap.PopoverPopoversBulle riche en contenu
bootstrap.ScrollSpyScrollspySuivre la section visible
bootstrap.TabNavigation et ongletsOnglets et pilules
bootstrap.ToastToastsNotification temporaire
bootstrap.TooltipInfobullesBulle d’aide

Inclure les scripts

Ajoutez le script juste avant la fermeture de </body>, après le contenu. Sans lui, la modale, le menu déroulant, l’accordéon et le menu mobile ne réagissent pas. Le détail des balises CDN et des empreintes d’intégrité est sur la page Installation.

Comportement par attributs#

Un bouton avec data-bs-toggle et data-bs-target suffit : aucun script à écrire. Le bouton de fermeture utilise data-bs-dismiss.

<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#js-modale-virement">Confirmer le virement</button>

<div class="modal fade" id="js-modale-virement" tabindex="-1" aria-labelledby="js-modale-virement-titre" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h2 class="modal-title fs-5" id="js-modale-virement-titre">Virement de 150 000 FCFA</h2>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Fermer"></button>
      </div>
      <div class="modal-body">Du compte courant vers le compte épargne.</div>
      <div class="modal-footer">
        <button type="button" class="btn btn-outline-primary" data-bs-dismiss="modal">Annuler</button>
        <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Confirmer</button>
      </div>
    </div>
  </div>
</div>

Attributs de commande

Ces attributs se posent sur le déclencheur. Ils ne demandent aucune initialisation, sauf pour les infobulles et les popovers.

Attributs de commande
AttributRôle
data-bs-toggle="modal"Ouvre la modale désignée par data-bs-target (sélecteur CSS) ou par href.
data-bs-toggle="offcanvas"Ouvre le panneau latéral désigné.
data-bs-toggle="collapse"Replie ou déplie le bloc désigné. Avec data-bs-parent, un seul bloc reste ouvert.
data-bs-toggle="dropdown"Ouvre le menu qui suit le bouton.
data-bs-toggle="tab" ou "pill"Active l’onglet et affiche son panneau.
data-bs-toggle="button"Fait basculer l’état actif du bouton.
data-bs-toggle="tooltip" ou "popover"Marque l’élément ; demande une initialisation en JavaScript.
data-bs-dismiss="modal", "offcanvas", "alert", "toast"Ferme le composant qui contient ce bouton.
data-bs-ride="carousel"Démarre le défilement automatique du carrousel au chargement.
data-bs-slide="prev" ou "next", data-bs-slide-to="2"Commandes du carrousel (précédent, suivant, aller à la diapositive).
data-bs-spy="scroll"Active le suivi de la section visible ; avec data-bs-target vers la navigation.

API avec l'objet global bootstrap (CDN)#

Quand le script est chargé par une balise, l’objet bootstrap est global. Un composant se crée avec un sélecteur CSS ou un élément.

const modale = new bootstrap.Modal('#js-modale-virement');
modale.show();   // ouvre
modale.hide();   // ferme
modale.toggle(); // bascule

// Récupérer l'instance d'un élément, ou la créer si elle n'existe pas
const menu = bootstrap.Dropdown.getOrCreateInstance(document.querySelector('#menu-compte'));

// Récupérer l'instance existante (null s'il n'y en a pas)
const existante = bootstrap.Modal.getInstance('#js-modale-virement');

// Libérer un composant que vous n'utilisez plus
modale.dispose();

API avec un bundler (npm)#

Le paquet expose @bdu/cauri/js : c’est le fichier dist/cauri.bundle.min.js, au format UMD (module CommonJS et objet global). Un import par défaut donne l’objet bootstrap. Aucun objet global n’est créé : importez ce dont vous avez besoin.

import bootstrap from '@bdu/cauri/js';

const modale = new bootstrap.Modal('#js-modale-virement');
modale.show();

// Pour les seuls attributs data-bs-*, un import sans valeur suffit
// import '@bdu/cauri/js';

Initialiser les infobulles et les popovers#

Pour des raisons de performance, ces deux composants ne démarrent pas seuls. Initialisez-les une fois la page chargée. Le contenu se place dans data-bs-title (infobulle) ou data-bs-title et data-bs-content (popover).

// Infobulles
document.querySelectorAll('[data-bs-toggle="tooltip"]')
  .forEach((el) => new bootstrap.Tooltip(el));

// Popovers
document.querySelectorAll('[data-bs-toggle="popover"]')
  .forEach((el) => new bootstrap.Popover(el));

// Contenu ajouté plus tard : déléguer à un conteneur
new bootstrap.Tooltip(document.body, { selector: '[data-bs-toggle="tooltip"]' });

Infobulle sur un bouton#

Le site de documentation initialise déjà les infobulles de ses aperçus. Dans votre page, ajoutez le code d’initialisation ci-dessus.

<button type="button" class="btn btn-outline-primary" data-bs-toggle="tooltip" data-bs-title="Le plafond est de 500 000 FCFA par jour">Plafond de virement</button>

Options : par attribut ou par objet

Chaque option se règle par un attribut data-bs-* ou par l’objet passé au constructeur. Le nom de l’option en camelCase devient un attribut en minuscules séparées par des tirets : customClass donne data-bs-custom-class. L’objet l’emporte sur les attributs.

Options : par attribut ou par objet
ComposantOption (valeur par défaut)Effet
Modalebackdrop (true)false : pas de fond. "static" : le clic sur le fond ne ferme pas.
Modalekeyboard (true)Fermeture avec Échap.
Modalefocus (true)Place le focus dans la modale à l’ouverture.
Offcanvasbackdrop (true), keyboard (true), scroll (false)Fond, fermeture à Échap, défilement de la page autorisé derrière le panneau.
Replitoggle (true), parent (null)Bascule à la création ; sélecteur du conteneur dont un seul repli reste ouvert.
Carrouselinterval (5000), ride (false), pause ("hover"), wrap (true), keyboard (true), touch (true)Délai en millisecondes, démarrage automatique, pause au survol, retour au début, flèches du clavier, balayage tactile.
Infobulleplacement ("top"), trigger ("hover focus"), delay (0), animation (true), html (false), container (false), customClass (""), title, offset ([0, 6])Position, déclenchement (click, hover, focus), délai, fondu, HTML autorisé, élément parent, classe ajoutée.
PopoverCelles de l’infobulle, plus content ; placement vaut "right"Contenu du corps de la bulle.
Toastanimation (true), autohide (true), delay (5000)Fondu, fermeture automatique, durée d’affichage en millisecondes.
Scrollspytarget, rootMargin ("0px 0px -25%"), smoothScroll (false), thresholdNavigation suivie, marge de détection, défilement doux au clic.

Régler une option#

<!-- Par attribut -->
<button type="button" class="btn btn-primary" data-bs-toggle="modal"
        data-bs-target="#js-modale-virement" data-bs-backdrop="static" data-bs-keyboard="false">
  Confirmer le virement
</button>

<script>
  // Par objet
  new bootstrap.Modal('#js-modale-virement', { backdrop: 'static', keyboard: false });
  new bootstrap.Tooltip('#plafond', { placement: 'bottom', trigger: 'focus' });
  new bootstrap.Toast('#toast-recu', { delay: 8000 });
</script>

Événements

Les événements sont déclenchés sur l’élément du composant. Le nom se termine par le nom du composant : show.bs.modal, shown.bs.dropdown… Les événements show et hide se lancent avant l’action et peuvent être annulés avec preventDefault().

Événements
ComposantÉvénements
Modale, offcanvasshow, shown, hide, hidden, hidePrevented (fermeture empêchée par une option)
Menu déroulant, repli, onglet, toastshow, shown, hide, hidden
Infobulle, popovershow, shown, hide, hidden, inserted (bulle ajoutée à la page)
Alerteclose, closed
Carrouselslide (avant le changement), slid (après), avec direction, from et to
Scrollspyactivate (un lien devient actif)

Écouter un événement#

const modale = document.querySelector('#js-modale-virement');

modale.addEventListener('shown.bs.modal', () => {
  document.querySelector('#montant').focus();
});

// Empêcher la fermeture tant que le formulaire est incomplet
modale.addEventListener('hide.bs.modal', (e) => {
  if (!document.querySelector('#formulaire-virement').checkValidity()) {
    e.preventDefault();
  }
});

// Carrousel : savoir quelle diapositive s'affiche
document.querySelector('#offres').addEventListener('slid.bs.carousel', (e) => {
  console.log('Diapositive', e.to);
});

Désactiver les transitions

Selon le besoin, trois niveaux :

  • À la compilation. L’option Sass $enable-transitions: false retire toutes les transitions CSS de Cauri (voir Options Sass).
  • Par composant. L’option animation: false supprime le fondu des infobulles, des popovers et des toasts. Pour une modale ou un panneau, retirez la classe fade de l’élément.
  • Selon l’utilisateur. Rien à faire : les transitions sont déjà coupées quand le système demande de réduire les animations (voir Accessibilité).

Sans animation#

new bootstrap.Tooltip('#plafond', { animation: false });
new bootstrap.Toast('#toast-recu', { animation: false });

// Modale sans fondu : pas de classe "fade"
// <div class="modal" id="js-modale-virement" tabindex="-1">…</div>

Sélecteurs et bonnes pratiques

  • Le constructeur accepte un sélecteur CSS ('#js-modale-virement') ou un élément du DOM.
  • Un élément n’a qu’une instance par composant : utilisez getOrCreateInstance plutôt que new si le code peut s’exécuter plusieurs fois.
  • Dans une application à composants (React, Vue, Angular), créez l’instance après le rendu et appelez dispose() quand le composant est détruit.
  • Les attributs data-bs-* fonctionnent sur le HTML présent au chargement et sur celui qu’on ajoute ensuite, car les commandes écoutent le document entier. Seules les infobulles et les popovers demandent une initialisation.
  • Gardez des id uniques : data-bs-target="#ma-modale" désigne le premier élément trouvé.

Simulateur de prêt : Cauri

Le fichier cauri.js lit les formulaires marqués data-cauri-simulator au chargement de la page et calcule la mensualité d’un prêt à annuités constantes. Voir le composant Simulateur de prêt dans la section Composants.

Simulateur de prêt : Cauri
ÉlémentRôle
data-cauri-simulator sur le formActive le simulateur.
data-rate="7.5"Taux annuel en pourcentage (0 si absent).
Champ name="amount"Montant emprunté, en FCFA.
Champ name="months"Durée en mois.
Élément [data-cauri-result]Reçoit le résultat, par exemple « 45 000 FCFA / mois » (nombres au format français, arrondis à l’unité), ou « — » si les valeurs sont invalides.
Cauri.init(conteneur)Initialise les simulateurs d’un conteneur. Un simulateur déjà initialisé est ignoré.
Cauri.monthlyPayment(montant, tauxAnnuel, mois)Calcule la mensualité sans interface. Renvoie 0 si le montant ou la durée ne sont pas positifs.

Utiliser le simulateur#

Avec la balise de script, tout est automatique. Avec un framework, appelez Cauri.init après le rendu du composant (import Cauri from '@bdu/cauri/components').

<form data-cauri-simulator data-rate="7.5">
  <label class="form-label" for="sim-montant">Montant (FCFA)</label>
  <input class="form-control" id="sim-montant" name="amount" type="number" value="1000000" min="0">
  <label class="form-label mt-3" for="sim-duree">Durée (mois)</label>
  <input class="form-control" id="sim-duree" name="months" type="number" value="24" min="1">
  <p class="mt-3 mb-0" aria-live="polite">Mensualité : <strong data-cauri-result></strong></p>
</form>

<script src="https://cdn-cauri.wanetech.com/v0.1.0/cauri.js"></script>
<script>
  // Mensualité de 1 000 000 FCFA à 7,5 % sur 24 mois
  console.log(Cauri.monthlyPayment(1000000, 7.5, 24)); // environ 44 999,6
</script>
Charte provisoire, déduite du site public de la BDU CI. Elle sera remplacée par la charte officielle.