Documentation / Getting started

Embedding a module

A module installs with two lines of HTML: an element that marks the spot, and the script that fills it. The script creates a frame (an iframe) at that spot, adjusts its height to its content, and touches nothing else on your page.

The code to paste

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

You do not have to write it yourself: your site's "Modules" screen, then each module's editor, show the exact code with your key already in place. Copy it as is.

Paste it where the module should appear on the page. The <script> line can also go lower in the page, or in your template's footer: it looks for every marked element, wherever it is.

The attributes

Where to find your key

The key appears in the code of each object's "Embed" tab, and on its own in the site's "Settings" screen, under "Public key". It identifies the site and gives access to nothing else: it can stay visible in your page's source code.

Where to find a reference

Every form, quiz or palette gets a reference when it is created, derived from its name (for example contact). You do not have to look for it: the code in the object's "Embed" tab already contains it. A reference holds only unaccented lowercase letters, digits and hyphens, 40 characters at most.

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

If the reference matches no live object, the frame shows "No form is ready on this site yet." (or the equivalent for a quiz or a palette).

Several modules on one page

Repeat the <div data-bl> element as many times as needed, one per module. A single <script> line is enough for the whole page.

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

Sites with in-page navigation

Some sites change page without reloading the browser (single-page applications, many recent themes). The script watches the page: a <div data-bl> element added after load is mounted too. The script only needs to have been loaded once, for example in the template shared by every page.

For reactions, the path kept is the page's path at the moment the frame is mounted.

Where the module shows, and where it refuses

Your page's code is visible to everyone, and the key is easy to copy. So that nobody can show your modules on their own site, every frame is served with a security header (frame-ancestors) that lists the only domains allowed to display it. The visitor's browser enforces that rule.

• The domain registered for the site always counts, with all its subdomains, over https as well as http. If you registered example.com, the module also shows on www.example.com or blog.example.com.
• The reverse is not true: if you registered www.example.com, the module does not show on a bare example.com.
• For other addresses (a second domain name, a test address), add them in the site's "Settings" screen, under "Allowed addresses", separated by commas.

On a domain that is not on the list, the browser refuses to display the frame: you see an empty frame or a browser error message, never the module.

What it takes for a module to show

• The site is active (a closed account switches off its sites).
• The site is verified. Otherwise the frame shows "This module is waiting for the site owner to verify the site." See the daily re-check of the proof.
• The module is added to this site. Removed, the frame shows "This module is no longer connected to this site."
• The requested object (form, quiz or palette) exists and is live ("More" menu of the object).
• The page showing it is on an allowed domain.