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.
| Fichier | Contenu | Objet global |
|---|---|---|
cauri.bundle.min.js | Le 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.js | Les comportements propres à BDU : calcul du simulateur de prêt. Sans dépendance. | Cauri |
Composants disponibles
| Classe | Page | Rôle |
|---|---|---|
bootstrap.Alert | Alertes | Fermer une alerte |
bootstrap.Button | Boutons | Bouton à bascule (état actif) |
bootstrap.Carousel | Carrousel | Faire défiler des diapositives |
bootstrap.Collapse | Repli | Afficher ou masquer un bloc (utilisé par l’accordéon et le menu mobile) |
bootstrap.Dropdown | Menus déroulants | Ouvrir un menu |
bootstrap.Modal | Modale | Boîte de dialogue |
bootstrap.Offcanvas | Offcanvas | Panneau latéral |
bootstrap.Popover | Popovers | Bulle riche en contenu |
bootstrap.ScrollSpy | Scrollspy | Suivre la section visible |
bootstrap.Tab | Navigation et onglets | Onglets et pilules |
bootstrap.Toast | Toasts | Notification temporaire |
bootstrap.Tooltip | Infobulles | Bulle 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.
| Attribut | Rô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.
| Composant | Option (valeur par défaut) | Effet |
|---|---|---|
| Modale | backdrop (true) | false : pas de fond. "static" : le clic sur le fond ne ferme pas. |
| Modale | keyboard (true) | Fermeture avec Échap. |
| Modale | focus (true) | Place le focus dans la modale à l’ouverture. |
| Offcanvas | backdrop (true), keyboard (true), scroll (false) | Fond, fermeture à Échap, défilement de la page autorisé derrière le panneau. |
| Repli | toggle (true), parent (null) | Bascule à la création ; sélecteur du conteneur dont un seul repli reste ouvert. |
| Carrousel | interval (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. |
| Infobulle | placement ("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. |
| Popover | Celles de l’infobulle, plus content ; placement vaut "right" | Contenu du corps de la bulle. |
| Toast | animation (true), autohide (true), delay (5000) | Fondu, fermeture automatique, durée d’affichage en millisecondes. |
| Scrollspy | target, rootMargin ("0px 0px -25%"), smoothScroll (false), threshold | Navigation 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().
| Composant | Événements |
|---|---|
| Modale, offcanvas | show, shown, hide, hidden, hidePrevented (fermeture empêchée par une option) |
| Menu déroulant, repli, onglet, toast | show, shown, hide, hidden |
| Infobulle, popover | show, shown, hide, hidden, inserted (bulle ajoutée à la page) |
| Alerte | close, closed |
| Carrousel | slide (avant le changement), slid (après), avec direction, from et to |
| Scrollspy | activate (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: falseretire toutes les transitions CSS de Cauri (voir Options Sass). - Par composant. L’option
animation: falsesupprime le fondu des infobulles, des popovers et des toasts. Pour une modale ou un panneau, retirez la classefadede 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
getOrCreateInstanceplutôt quenewsi 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
iduniques :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.
| Élément | Rôle |
|---|---|
data-cauri-simulator sur le form | Active 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>