Widgets HandAmateur.

Qu'est-ce qu'un widget HandAmateur ?

Un widget est un petit encart que tu insères dans une page de ton site et qui affiche, en temps réel, des données de ton club issues de CoachBox. Les informations restent toujours à jour : tu saisis tes matchs et tes résultats dans CoachBox comme d'habitude, le site se met à jour tout seul.

• Aucune ressaisie — la donnée vit dans CoachBox, le widget l'affiche.
• Fonctionne partout — WordPress, Wix, un site fait main… tout site capable d'insérer un bloc HTML.
• Score en direct — pendant un match capté en live, le score se rafraîchit automatiquement sur ton site.
• Tu gardes la main — rien n'est publié tant que tu ne l'as pas explicitement décidé (voir la section RGPD).

Bon à savoir. Les widgets remplacent l'ancien module « HandAmateur » que certains clubs utilisaient. Si c'est ton cas, vois la section migration.

Les widgets disponibles

Six widgets couvrent les besoins d'un site de club :

Avant de commencer : activer la publication

Par défaut, rien n'est public. Un administrateur du club doit d'abord activer et choisir ce qui est exposé. Tout se passe dans CoachBox :

1. Connecte-toi à CoachBox avec un compte administrateur du club.
2. Depuis l'accueil, ouvre Administration → Site vitrine (tuile 🌐).
3. Active l'interrupteur Activer la publication en haut de page.
4. Onglet Équipes : coche les équipes à rendre visibles sur le site.
5. Onglet Joueurs : coche les joueurs dont tu veux publier le nom et les statistiques (facultatif).
6. Onglet Réglages : choisis d'exposer ou non les statistiques des joueurs, les anniversaires, les feuilles de match, la carte des déplacements, etc. Pour la carte, tu règles les informations affichées (lignes, distances, résultats, prochain déplacement) et la couleur principale (la teinte de la terre ; la mer et les libellés en sont déduits).

Important. Tant que la publication est désactivée, ou qu'une équipe/un joueur n'est pas coché, le widget correspondant affiche « indisponible ». C'est volontaire : tu maîtrises exactement ce qui sort.

L'onglet Intégration de cette même page fournit, pour chaque widget, le code prêt à copier (iframe et shortcode WordPress) — c'est la source la plus fiable pour récupérer les identifiants de tes équipes.

Méthode 1 — WordPress (plugin)

La méthode la plus simple si ton site tourne sous WordPress. Un petit plugin ajoute des « shortcodes » que tu colles dans tes pages.

1. Télécharge le plugin : handamateur-widgets.zip (v1.4.0).
2. Dans WordPress : Extensions → Ajouter → Téléverser une extension, envoie le fichier .zip téléchargé, puis Active-le.
3. Va dans Réglages → HandAmateur Widgets et renseigne :
   • URL de base : l'adresse de ton instance (ex. https://coachbox.handamateur.fr).
   • Slug du club : l'identifiant de ton club, affiché dans Administration → Site vitrine → onglet Intégration (à côté des extraits à copier).
   • (facultatif) couleur d'accent et thème clair/sombre.
4. Modifie la page voulue et insère un bloc « Code court » (shortcode) avec l'un des codes ci-dessous.
5. Publie la page. C'est tout !

Les shortcodes disponibles :

Pour le joueur, le plus simple est d'utiliser son numéro de licence FFHB (donnée officielle que tu connais) : [handamateur_player licence_id="123456"]. Tu peux aussi utiliser l'id interne : [handamateur_player player_id="…"].

Les identifiants team_id (et l'id interne d'un joueur, si besoin) sont fournis tout faits : chaque équipe publiée propose son extrait dans l'onglet Site vitrine → Intégration.

Astuce. Tous les shortcodes acceptent des options : accent="#FF6600", theme="dark", height="700". Exemple : [handamateur_team team_id="…" height="800"].

Affichage « scoreboard ». L'agenda et les fiches équipe proposent un second affichage des matchs (logos + score façon feuille de match) via agenda_ui="scoreboard" :
[handamateur_agenda agenda_ui="scoreboard"] — avec un filtre par catégorie.
[handamateur_team team_id="…" agenda_ui="scoreboard"] — résultats & à venir en scoreboard.
Sur l'agenda, tu peux aussi limiter l'affichage à certaines équipes : teams="ID1,ID2". Et sur la liste des équipes, agenda_ui="scoreboard" se propage aux fiches équipe ouvertes depuis elle.
Le plus simple : l'onglet Site vitrine → Intégration génère le shortcode (et un aperçu) avec ces options préremplies.

Mises à jour : une fois installé, le plugin se met à jour tout seul — WordPress te proposera la nouvelle version en un clic dans Extensions, comme n'importe quelle extension. Et l'affichage des widgets est de toute façon toujours à jour : il est servi en direct depuis CoachBox.

Méthode 2 — N'importe quel site (iframe)

Si ton site n'est pas sous WordPress (Wix, Jimdo, site fait main…), tu peux coller directement un « iframe ». C'est exactement ce que génère l'onglet Intégration de CoachBox : copie, colle, terminé.

1. Dans CoachBox : Administration → Site vitrine → onglet Intégration.
2. Choisis le widget souhaité et clique sur « Copier l'iframe ».
3. Dans l'éditeur de ton site, ajoute un bloc HTML / Code embarqué et colle le code.
4. Enregistre la page.

À quoi ressemble le code (les valeurs entre accolades sont propres à ton club) :

<iframe
  src="https://coachbox.handamateur.fr/widgets.html#/{slug-du-club}/agenda"
  style="width:100%;max-width:820px;height:600px;border:0;display:block;margin:0 auto"
  loading="lazy" title="Agenda HandAmateur"></iframe>

Le widget ajuste sa hauteur tout seul une fois chargé, si tu ajoutes ce petit script une fois dans ta page (le plugin WordPress le fait automatiquement) :

<script>
addEventListener('message', function (e) {
  if (e.data && e.data.type === 'handamateur:height') {
    document.querySelectorAll('iframe').forEach(function (f) {
      if (f.contentWindow === e.source) f.style.height = e.data.height + 'px';
    });
  }
});
</script>

Sans ce script, l'iframe garde la hauteur fixe de son style (height:600px) ; augmente-la si le contenu est coupé.

Options en query (avant le #) : ?accent=%23FF6600, ?theme=dark, ?agendaUi=scoreboard, ?teams=ID1,ID2. Exemple : …/widgets.html?agendaUi=scoreboard#/{slug}/agenda.

Pour les autres widgets, seule la fin de l'adresse change :

Carte des déplacements. Elle s'affiche automatiquement en bas de la page d'une équipe (widget team / shortcode [handamateur_team]) dès qu'elle est activée — inutile de l'ajouter à part. Pour l'insérer seule, utilise l'adresse /map/{team_id} en iframe (l'onglet Site vitrine → Intégration en génère le code, avec le choix des informations affichées). Le paramètre ?map= liste les couches à montrer (lines = tracés, km = distances, results = résultats V/N/D, next = prochain déplacement) ; sans lui, la carte reprend le réglage par défaut du club. La couleur de la carte, elle, se règle une fois pour toutes dans Réglages (elle n'est pas un paramètre d'adresse).

Personnalisation

Les widgets s'adaptent à ta charte. Trois options, en paramètre d'adresse (juste après widgets.html, avant le #) :

<iframe src="https://coachbox.handamateur.fr/widgets.html?theme=dark&accent=%23FF6600#/{slug}/agenda"
  style="width:100%;max-width:820px;height:700px;border:0;display:block;margin:0 auto" loading="lazy"></iframe>

La largeur maximale (max-width:820px) est ajustable : augmente-la (ou retire-la) pour un encart pleine largeur.

Le caractère « # » d'une couleur s'écrit %23 dans une adresse. Sous WordPress, écris la couleur normalement : accent="#FF6600".

Si tu ne précises pas de couleur, le widget reprend automatiquement la couleur d'accent de ton club définie dans CoachBox.

Migration depuis l'ancien module HandAmateur

L'ancien module n'exposait que les données fédérales ; ces widgets exposent en plus les données live de ton club. Désactive l'ancien module (il réutilise certains noms de shortcodes), puis mets à jour tes shortcodes :

⚠ Attention au player_id. Le nom de l'attribut ne change pas, mais sa valeur change : l'ancien player_id était un identifiant fédéral, le nouveau est l'identifiant interne CoachBox (différent). Coller l'ancienne valeur affiche un widget vide. Utilise plutôt licence_id (n° de licence FFHB, invariant) ou récupère le nouvel player_id dans l'onglet Intégration.

Une fois la bascule faite, l'ancien module peut être désinstallé.

Vie privée & RGPD

Publier des données sur un site public engage ta responsabilité, en particulier pour les mineurs. CoachBox est conçu pour limiter les risques :

• Opt-in strict : rien n'est public tant que tu ne l'as pas explicitement coché.
• Aucune date de naissance n'est jamais exposée par les widgets.
• Les statistiques des joueurs ne sont publiées que si tu l'actives et joueur par joueur.
• Une équipe non publiée ne fuite jamais, même via la fiche d'un joueur qui y joue.

Notre recommandation. Pour les équipes de jeunes, recueille l'accord des représentants légaux avant de publier les noms et statistiques, et n'expose que ce qui est nécessaire. Voir aussi notre politique de confidentialité.

Dépannage

Le widget affiche « indisponible » ou reste vide

• La publication est-elle activée (Administration → Site vitrine) ?
• L'équipe / le joueur est-il bien coché comme publié ?
• Pour les stats joueur : l'option « Statistiques des joueurs » est-elle activée dans les réglages ?
• L'URL de base et le slug du club sont-ils corrects (plugin WordPress) ?

L'encart est trop court / coupé

Sous WordPress, la hauteur s'ajuste automatiquement. Ailleurs, ajoute le petit script d'auto-hauteur (voir Méthode iframe) ou augmente la hauteur fixe : height:800px dans le style de l'iframe.

Les couleurs ne correspondent pas à mon site

Règle l'option accent et choisis theme="light" (par défaut, conçu pour les sites clairs) ou theme="dark".

Où trouver le slug, les team_id et player_id ?

Dans CoachBox, onglet Site vitrine → Intégration : les extraits y sont pré-remplis pour chaque équipe publiée.

Une question ? Écris-nous à [email protected].