Websource Listes de liens pour WordPress — référence développeur

Vue d'ensemble

• Espace de noms PHP : Websource\LinkLists (classes dans src/, PSR-4, chargeur dans websource-linklists.php, pas de Composer).
• Préfixe des options, filtres et handles : wsx_linklists_. Classes CSS : wsll.
• Stockage : options WordPress, aucune table. wsx_linklists_lists (listes publiées, chargée automatiquement), wsx_linklists_drafts (brouillons), wsx_linklists_seq (dernier numéro), wsx_linklists_rev (révision du cache), wsx_linklists_version.
• Cache : un transient par liste et par langue, wsx_linklists_v_<révision>_<numéro>-<langue>, durée 1 heure. Vidé à chaque enregistrement et quand une page, un produit, un terme, les permaliens, le thème ou les pages WooCommerce changent.
• Côté public : une feuille de style (assets/css/front.css, handle wsx-linklists), aucun JavaScript. La feuille n'est chargée que si une liste s'affiche sur la page.
• Droit requis pour l'administration : edit_theme_options (filtre wsx_linklists_capability).
• Aucune route REST propre. L'administration passe par une action admin-ajax.php protégée (voir « Action AJAX d'administration »).

Bloc

websource/link-list — rendu serveur, sans étape de build (blocks/link-list/block.json, blocks/link-list/editor.js).

Supports : align (wide, full), spacing.margin, spacing.padding, customClassName, plusieurs blocs par page.

<!-- wp:websource/link-list {"list":"informations","layout":"menu"} /-->

Le bloc ne rend rien sur le site si la liste est inconnue, masquée ou sans lien affichable. Dans l'éditeur, il affiche alors un message d'aide.

Code court

[websource_linklist list="informations"]
[websource_linklist id="1"]

Widget

Widget classique wsx_linklists (classe Websource\LinkLists\Widget\LinkListWidget, classe CSS widget_wsx_linklists). Réglages d'instance : title (facultatif) et list (identifiant). Disponible aussi comme widget hérité dans l'éditeur de widgets à blocs.

Fonction PHP

<?php
// Dans un fichier du thème : HTML d'une liste affichée sur le site, ou chaîne vide.
echo websource_linklist('informations'); // identifiant
echo websource_linklist(1);              // numéro

Accès aux services :

<?php
$plugin   = \Websource\LinkLists\Plugin::instance();
$html     = $plugin->renderer()->renderByRef('informations'); // comme websource_linklist()
$html     = $plugin->renderer()->renderList(1, 2);            // numéro, colonne du pied de page (0 à 4)
$all      = $plugin->lists()->all();                          // listes publiées, par numéro
$active   = $plugin->lists()->findActive();
$plugin->afterChange();                                       // vide le cache après une écriture directe

Emplacements

Un emplacement est une paire page + endroit. Son champ hook prend l'une de ces trois formes :

Zones et points d'accroche :

Les zones de widgets dont l'identifiant contient footer, header, colophon ou bottom ne reçoivent pas les positions left_column et right_column (filtre wsx_linklists_sidebar_zone).

Clés de page (page) : all, home, shop, category, product, brand, cms (avec cms_id, 0 = toutes les pages), blog, search, login, password, account, cart, checkout, contact, notfound.

Les points d'accroche ne sont branchés que sur les pages où une liste affichée les utilise (Websource\LinkLists\Front\Placements::prepare(), action wp, priorité 20). Rien n'est branché en administration, en AJAX, en REST, dans les flux ni dans les contenus embarqués.

Action AJAX d'administration

L'extension ne déclare aucune route REST. L'écran Apparence > Listes de liens appelle une seule action.

• Méthode et chemin : POST /wp-admin/admin-ajax.php
• Paramètres communs : action=wsx_linklists, _ajax_nonce (nonce wsx_linklists_admin), do (opération).
• Accès : utilisateur connecté disposant du droit edit_theme_options. Un visiteur anonyme reçoit la réponse 0 de WordPress (HTTP 400), un utilisateur sans le droit ou sans nonce valide reçoit HTTP 403.

Exemple de requête :

curl -b cookies.txt https://exemple.fr/wp-admin/admin-ajax.php \
  -d action=wsx_linklists -d do=toggle -d id=1 -d active=0 -d _ajax_nonce=20c18e7621

Réponses d'erreur (JSON { "error": "…" }) : 400 action inconnue, 403 droit ou nonce refusé, 404 liste introuvable.

Le contenu reçu (payload) est toujours nettoyé par Websource\LinkLists\Admin\ListPayloadSanitizer : 60 liens et 20 emplacements au plus, sources et pages connues seulement, adresses passées par UrlSanitizer. dropped donne le nombre de liens refusés.

Format des données

Liste publiée (option wsx_linklists_lists)

{
  "id": 1,
  "identifier": "informations",
  "name": "Informations",
  "layout": "columns",
  "show_title": true,
  "active": true,
  "titles": { "fr": "Informations" },
  "links": [
    { "source": "page", "target_id": 0, "page_key": "contact", "url": "", "urls": [], "new_tab": false, "nofollow": false, "labels": [] },
    { "source": "custom", "target_id": 0, "page_key": "", "url": "https://www.websource.fr/", "urls": [], "new_tab": true, "nofollow": true, "labels": { "fr": "Websource" } }
  ],
  "placements": [
    { "page": "all", "position": "footer_col1", "cms_id": 0, "hook": "zone:footer" }
  ],
  "date_add": "2026-10-09 18:52:10",
  "date_upd": "2026-10-09 18:52:10"
}

Adresses acceptées pour un lien libre (Websource\LinkLists\Link\UrlSanitizer) : http://, https://, chemin commençant par /, ancre #…, mailto:, tel:. Une adresse du type www.exemple.fr ou exemple.fr/page est complétée par https://. Tout le reste est refusé (javascript:, ftp:, espaces, guillemets, chevrons). 500 caractères au plus.

Un lien dont la cible n'existe plus ou n'est pas publiée reste enregistré mais n'est pas affiché.

Pages du site sans équivalent natif : contact, sitemap, terms, stores, prices-drop et manufacturers sont cherchées parmi les pages publiées, par slug (contact, plan-du-site, conditions-generales-de-vente, nos-magasins, promotions, marques et leurs variantes ; liste dans Websource\LinkLists\Link\SpecialPages::SLUGS). terms utilise d'abord la page des conditions générales de WooCommerce, privacy la page de politique de confidentialité de WordPress. best-sales et new-products mènent à la boutique triée (?orderby=popularity, ?orderby=date).

Vue d'une liste (filtre wsx_linklists_view, gabarit)

<?php
[
    'id' => 1,
    'identifier' => 'informations',
    'title' => 'Informations',
    'layout' => 'columns',        // columns, inline, menu
    'show_title' => true,
    'links' => [
        ['url' => 'https://exemple.fr/contact/', 'label' => 'Contact', 'target' => '', 'rel' => ''],
    ],
];

Paquet de thème

Section linklists, version 1, des filtres websource_theme_export et websource_theme_import de Websource Theme Config (classe Websource\LinkLists\ThemePackage\ThemePackage).

{
  "lists": [
    {
      "identifier": "informations",
      "name": "Informations",
      "layout": "columns",
      "show_title": true,
      "active": true,
      "titles": { "fr": "Informations" },
      "links": [
        { "source": "cms", "target": "cms:a-propos", "page_key": "", "url": "", "urls": [], "new_tab": false, "nofollow": false, "labels": [] },
        { "source": "product", "target": "product:WS-001", "page_key": "", "url": "", "urls": [], "new_tab": false, "nofollow": false, "labels": [] }
      ],
      "placements": [
        { "page": "cms", "position": "before_footer", "hook": "zone:before_footer", "cms": "cms:a-propos" }
      ]
    }
  ]
}

• Clés stables des cibles : cms:<slug>, category:<slug>, brand:<slug>, product:<UGS> (ou product:<slug> sans UGS).
• Contexte d'import : mode (replace par défaut, ou merge) et dry_run. replace supprime les listes du site puis crée celles du paquet (les numéros changent, les identifiants sont conservés). merge met à jour la liste de même identifiant et ajoute les autres.
• Rapport renvoyé : { "action": "merge", "counts": { "create": 1, "update": 1, "delete": 0, "skip": 0 }, "messages": ["linklists : cible « cms:nexiste-pas » introuvable : lien ignoré."] }.
• Une section de version supérieure à 1 lève une RuntimeException (rapportée en erreur par Websource Theme Config).
• Les brouillons ne sont pas exportés. 60 listes au plus par import.
• Paquets du module PrestaShop : les pages index, manufacturer, pagenotfound, my-account, authentication, order et product-list sont traduites en home, brand, notfound, account, login, checkout et category. Un hook libre displayXxx devient l'action wsx_linklists_displayxxx, à déclencher dans le thème avec do_action(). Sur un site à une seule langue, le premier texte du paquet est repris.

Filtres

Exemple : déclarer les zones d'un thème classique.

<?php
add_filter('wsx_linklists_zone_hooks', function (array $hooks, string $template): array {
    if ($template === 'mon-theme') {
        $hooks['under_header'] = ['mon_theme_after_header', 10];
        $hooks['footer'] = ['mon_theme_footer_top', 10];
    }

    return $hooks;
}, 10, 2);

Exemple : forcer la présentation d'une liste.

<?php
add_filter('wsx_linklists_view', function (array $view): array {
    if ($view['identifier'] === 'informations') {
        $view['layout'] = 'inline';
    }

    return $view;
});

Gabarit et balisage

Gabarit : templates/list.php, surchargeable dans le thème (<thème>/websource-linklists/list.php). Variables : $wsll_list (la vue) et $wsll_order (colonne du pied de page, 0 à 4).

<nav class="wsll wsll--columns wsll--o1" data-wsll-list="informations" aria-label="Informations">
    <p class="wsll__title">Informations</p>
    <ul class="wsll__list">
        <li class="wsll__item"><a class="wsll__link" href="https://exemple.fr/contact/">Contact</a></li>
    </ul>
</nav>

Données structurées : après chaque liste affichée, une balise <script type="application/ld+json"> de type SiteNavigationElement (@graph, nom et adresse absolue de chaque lien http(s)). Une même liste affichée deux fois sur une page n'est décrite qu'une fois. Rien dans l'aperçu de l'administration ni dans l'éditeur de blocs.

Variables CSS

La feuille de style lit les variables du thème Websource et prévoit une valeur de repli pour tout autre thème.

Multilingue

• Les titres, les textes des liens et les adresses des liens libres sont enregistrés par code de langue (fr, en…). La langue courante est lue auprès de Polylang (pll_current_language) ou de WPML (wpml_current_language) ; à défaut, la langue du site.
• Texte absent dans une langue : celui de la langue par défaut est repris.
• Les pages, produits et termes sont remplacés par leur traduction (pll_get_post, pll_get_term, wpml_object_id).
• Les titres et textes des listes publiées sont déclarés à Polylang (pll_register_string, groupe « Websource Link Lists ») et à WPML (wpml-config.xml, option wsx_linklists_lists).
• Classe utilitaire : Websource\LinkLists\Languages (all(), codes(), defaultCode(), current(), isMultilingual(), translatePost(), translateTerm(), pick()).

Classes PHP utiles

Désinstallation

uninstall.php supprime les options wsx_linklists_lists, wsx_linklists_drafts, wsx_linklists_seq, wsx_linklists_rev, wsx_linklists_version, widget_wsx_linklists et les transients wsx_linklists_*, sur chaque site d'un réseau multisite.