Documentation / Premiers pas

Intégrer un module

Un module s'installe avec deux lignes de HTML : un élément qui marque l'emplacement, et le script qui le remplit. Le script crée un cadre (une iframe) à cet endroit, ajuste sa hauteur à son contenu, et ne touche à rien d'autre dans votre page.

Le code à coller

<div data-bl="formulaire" data-cle="pk_votrecle"></div>
<script src="https://bonjourlatoile.com/bl.js" defer></script>

Vous n'avez pas à l'écrire vous-même : l'écran « Modules » de votre site, puis l'éditeur de chaque module, affichent le code exact, avec votre clé déjà en place. Copiez-le tel quel.

Collez-le à l'endroit de la page où le module doit apparaître. La ligne <script> peut aussi aller plus bas dans la page, ou dans le pied de page de votre gabarit : elle cherche tous les éléments marqués, où qu'ils soient.

Les attributs

Attribut	Obligatoire	Rôle
`data-bl`	Oui	Le module à afficher : `formulaire`, `quiz` ou `reactions`.
`data-cle`	Oui	La clé publique du site, de la forme `pk_` suivi de 24 caractères.
`data-ref`	Non	Quel formulaire, quel quiz ou quelle palette afficher. Le code de l'onglet « Intégration » le porte déjà. Sans lui, c'est le plus ancien des objets en ligne de ce module qui s'affiche.
`data-page`	Non	Pour les réactions seulement : l'adresse sous laquelle les votes sont comptés. Par défaut, le chemin de la page en cours.

Où trouver sa clé

La clé figure dans le code de l'onglet « Intégration » de chaque objet, et seule dans l'écran « Réglages » du site, sous « Clé publique ». Elle identifie le site et ne donne accès à rien d'autre : elle peut rester visible dans le code source de votre page.

Où trouver une référence

Chaque formulaire, quiz ou palette reçoit une référence à sa création, tirée de son nom (par exemple contact). Vous n'avez pas à la chercher : le code de l'onglet « Intégration » de l'objet la contient déjà. Une référence ne contient que des minuscules sans accent, des chiffres et des tirets, 40 caractères au plus.

<div data-bl="formulaire" data-cle="pk_votrecle" data-ref="contact"></div>

Si la référence ne correspond à aucun objet en ligne, le cadre affiche « Aucun formulaire n'est prêt sur ce site. » (ou l'équivalent pour un quiz ou une palette).

Plusieurs modules sur une page

Répétez l'élément <div data-bl> autant de fois qu'il faut, un par module. Une seule ligne <script> suffit pour toute la page.

<div data-bl="formulaire" data-cle="pk_votrecle" data-ref="contact"></div>
<div data-bl="quiz" data-cle="pk_votrecle"></div>
<div data-bl="reactions" data-cle="pk_votrecle"></div>
<script src="https://bonjourlatoile.com/bl.js" defer></script>

Certains sites changent de page sans recharger le navigateur (les applications monopage, beaucoup de thèmes récents). Le script surveille la page : un élément <div data-bl> ajouté après le chargement est monté lui aussi. Il suffit que le script ait été chargé une fois, par exemple dans le gabarit commun à toutes les pages.

Pour les réactions, le chemin retenu est celui de la page au moment où le cadre est monté.

Où le module s'affiche, et où il refuse

Le code de votre page est visible de tous, et la clé se recopie facilement. Pour que personne ne puisse afficher vos modules chez lui, chaque cadre est servi avec un en-tête de sécurité (frame-ancestors) qui liste les seuls domaines autorisés à l'afficher. C'est le navigateur du visiteur qui applique cette règle.

Le domaine déclaré pour le site compte toujours, avec tous ses sous-domaines, en https comme en http. Si vous avez déclaré exemple.fr, le module s'affiche aussi sur www.exemple.fr ou blog.exemple.fr.
L'inverse n'est pas vrai : si vous avez déclaré www.exemple.fr, le module ne s'affiche pas sur exemple.fr sans rien devant.
Pour d'autres adresses (un second nom de domaine, une adresse de test), ajoutez-les dans l'écran « Réglages » du site, sous « Adresses autorisées », séparées par des virgules.

Sur un domaine qui n'est pas dans la liste, le navigateur refuse d'afficher le cadre : vous voyez un cadre vide ou un message d'erreur du navigateur, jamais le module.

Une copie de votre site sur votre ordinateur (localhost, une adresse IP, un nom en .local ou .test) ne peut pas être autorisée : ces adresses sont refusées. Pour voir le module avant de le mettre en ligne, utilisez le bouton « Aperçu » de son éditeur.

Les conditions pour qu'un module s'affiche

Le site est actif (un compte fermé éteint ses sites).
Le site est vérifié. Sinon, le cadre affiche « Ce module attend que le propriétaire du site prouve qu'il lui appartient. » Voir la relecture quotidienne de la preuve.
Le module est greffé sur ce site. Retiré, le cadre affiche « Ce module n'est plus branché sur ce site. »
L'objet demandé (formulaire, quiz ou palette) existe et il est en ligne (menu « Plus » de l'objet).
La page qui l'affiche est sur un domaine autorisé.