Websource Builder pour WordPress — référence développeur

Vue d'ensemble

• Espace de noms Websource\Builder, classes dans src/ (chargeur PSR-4 maison, pas de Composer). Fichier principal websource-builder.php : constantes WEBSOURCE_BUILDER_VERSION, WEBSOURCE_BUILDER_DIR, WEBSOURCE_BUILDER_URL, fonctions websource_builder() et websource_builder_render_composition().
• Un seul catalogue de blocs (Block\BlockRegistry) alimente trois façades : blocs Gutenberg websource/<type> (rendu serveur, block.json dans blocks/<type>/), shortcodes [wsb_<type>], et le modèle JSON {type, data, style} utilisé par l'API PHP, l'export et le connecteur Websource MCP. C'est le même modèle que le module PrestaShop Websource Builder 1.13.
• Type de contenu wsb_composition (« Compositions Websource », non public, show_in_rest), métadonnées _wsb_placements (liste d'emplacements), _wsb_lang, _wsb_pending_content (brouillon en attente d'une composition publiée).
• Options : wsb_product_layout (disposition de la fiche produit), wsb_contact_page, wsb_placement_index (index des emplacements, reconstruit à chaque enregistrement).
• Aucune table, aucun JavaScript public. CSS : assets/css/base.css + une feuille par bloc, chargées seulement si le bloc est présent (Assets::typesIn() analyse le contenu et les compositions retenues avant l'en-tête).

Blocs

Nom Gutenberg websource/<type>, shortcode [wsb_<type>]. Tous ont l'attribut appearance (objet : apparence + style avancé) et className. Les attributs portent le nom du champ ; les noms réservés par Gutenberg (style, align, layout…) sont préfixés wsb_ (wsb_style pour le bouton, wsb_align pour l'appel à l'action).

Apparence (style, commune à tous les blocs) :

Icônes (icon) : icon:<nom> parmi truck, bag, chat, home, hand, rocket, sparkles, bolt, heart, shield, phone, tag, list, alert, return, star, bell, megaphone, mountain, quote, leaf, pin, cart, fire, thumb, link, check, lock… (Render\Icons::PATHS), ou un emoji, un court texte, une adresse d'image.

Jetons dans les textes et liens (Render\TokenResolver) : {price:N}, {link:home}, {link:contact}, {link:shop}, {link:cart}, {link:account}, {link:page:ID} (alias {link:cms:ID}), {link:post:ID}, {link:product:ID}, {link:category:ID}. Les identifiants sont traduits par Polylang / WPML.

Balisage produit : <section class="wsb-block wsb-b-<type> wsb-bg-<bg> wsb-pad-<pad> wsb-w-<width> wsb-al-<align> [wsb-l-<layout>]">, contenu dans .wsb-inner. Une composition est enveloppée dans <div class="wsb-composition wsb-at-<position>" data-wsb-composition="ID">.

Shortcodes

[wsb_hero title="Bienvenue" subtitle="…" button_label="Voir" button_url="{link:shop}" image="https://…/photo.jpg" height="l" style_bg="dark" style_pad="l"]
[wsb_features columns="3" style_bg="soft"]
  [wsb_item icon="icon:truck" title="Livraison rapide" text="Sous 48 h."]
  [wsb_item icon="icon:shield" title="Paiement sécurisé" text="3D Secure."]
[/wsb_features]
[wsb_text]<p>Texte riche : <strong>le contenu du shortcode</strong>.</p>[/wsb_text]
[wsb_columns gap="l" valign="center"][wsb_column w="2"]…[/wsb_column][wsb_column w="1"]…[/wsb_column][/wsb_columns]
[wsb_composition id="12"]

• Un attribut par champ ; style_<clé> pour l'apparence et le style avancé ; class ajoute une classe CSS.
• Listes (features, cards, faq, testimonials, stats) : un [wsb_item …] par élément, attributs = sous-champs.
• Texte riche (text, split, pagecontent) : le contenu du shortcode remplace le champ riche.
• [wsb_composition id="N"] affiche une composition publiée (vide sinon).

Modèle JSON

[
  {"type": "hero", "data": {"title": "Bienvenue", "button_url": "{link:shop}"}, "style": {"bg": "dark", "pad": "l"}},
  {"type": "columns", "data": {"cols": [
    {"w": 2, "blocks": [{"type": "heading", "data": {"title": "Colonne A"}}]},
    {"w": 1, "blocks": [{"type": "button", "data": {"label": "Voir", "style": "outline"}}]}
  ]}},
  {"type": "gutenberg", "data": {"ref": "a3f9…"}}
]

• Un champ absent prend sa valeur par défaut ; une valeur hors liste revient à la valeur par défaut ; les types inconnus sont retirés ; 80 blocs au plus ; un seul niveau de colonnes.
• gutenberg : un bloc natif de l'éditeur présent dans la composition, référencé par une empreinte ref. Serializer le conserve tel quel ; l'API refuse une référence inconnue (aucun bloc natif ne peut être créé par ce modèle).
• Gutenberg\Serializer::toContent() / fromContent() convertissent dans les deux sens avec le contenu Gutenberg sérialisé.

API PHP

websource_builder() renvoie Websource\Builder\Api :

websource_builder_render_composition(int $id): string : HTML d'une composition publiée.

Déclarer un bloc externe (il devient bloc Gutenberg, shortcode et type du connecteur MCP) :

add_action('websource_builder_register_blocks', function (Websource\Builder\Block\BlockRegistry $registry) {
    $registry->add(new Mon_Bloc()); // implémente Websource\Builder\Block\BlockInterface
});
add_filter('websource_builder_block_styles', fn(array $styles) => $styles + ['mon_bloc' => plugins_url('mon-bloc.css', __FILE__)]);

BlockInterface : getType(), getLabel(), getDescription(), getCategory(), getIcon(), getFields() (tableau de Block\Field::text(), textarea(), richText(), url(), image(), icon(), color(), select(), number(), toggle(), category(), repeater()), getDefaults(), render(array $data, RenderContext $context). Étendre Block\AbstractBlock fournit l'essentiel ; InnerContentBlock (innerField()) déclare un champ riche édité par blocs imbriqués.

Routes REST

Espace websource-builder/v1. Authentification WordPress (cookie + nonce X-WP-Nonce, ou mot de passe d'application).

Les compositions elles-mêmes passent par la route native wp/v2/websource-compositions (métas _wsb_placements, _wsb_lang exposées en REST).

curl -u admin:xxxx-xxxx-xxxx-xxxx https://exemple.fr/wp-json/websource-builder/v1/placements

{
  "pages": {"all": "Toutes les pages du site", "home": "Page d'accueil", "product": "Fiches produit", "cms": "Pages de contenu (CMS)"},
  "positions": [{"key": "top", "label": "Tout en haut, sous l'en-tête (pleine largeur)", "pages": null},
                {"key": "product_info", "label": "Dans la fiche produit, sous le bouton d'achat", "pages": ["product"]}],
  "targetable": ["cms", "post", "product", "category"],
  "languages": ["fr"]
}

Emplacements

Un emplacement : { "page": "product", "position": "product_info", "object_id": 0, "hook": "", "priority": 10, "native": "" } (12 au plus par composition).

Pages : all, home, shop, category, product, cms, post, blog, login, registration, password, account, orders, cart, checkout, contact, search, notfound. object_id est accepté pour cms (page), post, product, category (product_cat).

Les thèmes à blocs sont pris en charge via render_block_core/template-part, render_block_core/query et render_block_woocommerce/product-collection.

Hooks

Le thème Websource expose aussi websource_theme_product_layout : la disposition enregistrée ici y est injectée (Product\ProductLayouts::forTheme()).

Export / import

GET /export, bouton Exporter les compositions, ou ThemePackage\Package::export() :

{
  "format": "websource-builder",
  "version": 1,
  "generator": "websource-builder/1.0.0 (wordpress)",
  "sections": {
    "builder": [
      {"key": "wsb-bandeau", "title": "Bandeau de promotion", "status": "publish", "lang": "",
       "placements": [{"page": "all", "position": "top", "hook": "", "priority": 10, "native": ""}],
       "content": "<!-- wp:websource/announcement {\"link\":\"{link:shop}\",\"appearance\":{\"bg\":\"brand\",\"pad\":\"s\",\"width\":\"wide\",\"align\":\"center\"}} /-->",
       "pending": ""}
    ],
    "builder_library": [{"key": "…", "title": "…", "content": "…"}],
    "product_layout": null
  }
}

• key : clé stable de la composition (slug), utilisée pour la fusion. Un emplacement ciblant un contenu porte object_ref (slug) à la place de object_id ; les adresses du site dans les contenus sont réécrites à l'import. Les références introuvables sont listées dans missing et remplacées par l'accueil.
• builder_library : sections réutilisables (wp_block) contenant des blocs Websource ; product_layout : disposition de la fiche produit (null si jamais enregistrée).
• Package::import(array $package, string $mode = 'merge', bool $dryRun = false) renvoie dry_run, mode, created, updated, trashed, library, product_layout, missing, errors. Un paquet d'un format différent ou d'une version supérieure est refusé.
• Le paquet complet du thème (Websource Theme Config) inclut les sections builder, builder_library et product_layout via websource_theme_export / websource_theme_import.

Variables CSS

Les feuilles de style lisent les variables du thème Websource avec repli :

Variables posées par l'extension sur .wsb-block quand une valeur est fixée (apparence, layout ou style avancé) : --wsb-brand, --wsb-brand-soft, --wsb-ink, --wsb-line, --wsb-surface, --wsb-text, --wsb-overlay, --wsb-btn-bg, --wsb-btn-fg, --wsb-btn-hover, --wsb-card-bg, --wsb-r, --wsb-r2 (arrondis), --wsb-shadow, --wsb-font, --wsb-weight, --wsb-k (facteur de taille).

Données structurées

Seo\JsonLd imprime dans wp_footer : FAQPage (toutes les questions des blocs FAQ de la page, fusionnées en un seul nœud), VideoObject (bloc Vidéo avec titre, description, date, miniature), ItemList + Product / Offer (bloc Produits). Rien n'est imprimé dans l'éditeur ni sur une page sans ces blocs.

Multilingue

• Composition : méta _wsb_lang (vide = toutes les langues) comparée à pll_current_language / wpml_current_language, sinon à la locale.
• wpml-config.xml : type wsb_composition traduisible, métas copiées ou ignorées, champs texte des blocs déclarés pour l'éditeur de traduction avancé.
• Jetons {link:…} : identifiants traduits par pll_get_post / wpml_object_id.

Désinstallation

uninstall.php supprime les compositions (wsb_composition, corbeille comprise, avec leurs métas) et les options wsb_placement_index, wsb_product_layout, wsb_contact_page. Les blocs présents dans les pages restent du contenu Gutenberg ordinaire (affichés comme des blocs inconnus, texte conservé).