popover-api

S'il est mis à jour par rapport à notre copie locale, alors notre copie locale doit être mise à jour.

Lorsqu'on demande pour la première fois d'utiliser l'API popover, commencez d'abord par copier le fichier assets/popover.css quelque part dans le projet.

Il est raisonnable de consulter l'utilisateur pour savoir où exactement ce fichier doit être copié dans le projet et de quelle manière il doit être chargé si ce n'est pas clair.

Mais fondamentalement, ce n'est qu'un simple fichier CSS plat, donc s'il y a des endroits dans le framework pour le charger, suivez simplement les standards raisonnables. Essayez simplement d'éviter de le charger deux fois pour des raisons ergonomiques.

Quand le popover doit s'afficher au clic sur l'ancre

Lorsque vous utilisez notre core-css pour positionner le popover, la structure de base est :

<button popovertarget="mypopover2">Basculer le popover</button>
<div id="mypopover2" popover data-popover>
  Contenu du popover
  <button popovertarget="mypopover2" popovertargetaction="hide">Fermer</button>
</div>

Dans l'exemple ci-dessus, nous avons un bouton qui sert d'ancre. Une fois cliqué, le bouton affichera le popover (l'élément avec l'attribut [popover]) et, lorsqu'il est cliqué à nouveau, masquera le popover.

Mais aussi, cliquer à l'intérieur du popover NE le masquera PAS, sauf le bouton "Fermer" – celui-ci le fermera.

De plus, cliquer en dehors du popover masquera le popover.

Lorsque vous suivez la structure de cet exemple, cela ne fait rien de plus que la fonctionnalité standard de l'API popover. Et n'hésitez pas à appliquer toute modification adaptée au cas d'utilisation de l'utilisateur.

NOTE : la définition du bouton "Fermer" ici est facultative, tout fonctionnera à 100 % sans lui aussi.

Ainsi, la formation HTML est la disposition par défaut.

Le principal facilitateur ici est l'attribut 'data-popover', c'est l'attribut qui active les styles de assets/popover.css qui s'occupe principalement du positionnement du popover par rapport à l'élément ancre.

Vous pouvez ne pas ajouter l'attribut [data-popover] mais alors vous perdrez nos styles personnalisés et le popover se comportera comme un élément natif standard. Lorsque l'attribut [data-popover] est présent, vous utilisez l'API popover standard brute et cette compétence n'a probablement rien à offrir. Faites simplement ce dont vous avez besoin avec l'implémentation standard de l'API popover.

Mais le but est que l'attribut [data-popover] sert de séparation explicite entre les cas où nous gérons l'API popover en utilisant le style fourni par cette compétence et ceux où nous la gérons manuellement. Ainsi, lorsque [data-popover] n'est pas spécifié, notre CSS n'interférera pas avec votre implémentation manuelle de l'API popover.

Donc, en général, n'hésitez pas à utiliser [data-popover] pour vous en tenir à nos styles ou évitez-le lorsque vous préférez utiliser l'API popover native brute.

Les exemples présentés dans ce document peuvent être contrôlés par n'importe quelle autre API JavaScript et HTML qui pourrait normalement être utilisée avec l'API popover native standard.

<button popovertarget="mypopover3">Basculer le popover</button>
<div id="mypopover3" popover="manual" data-popover>
  notre contenu popover
  <button popovertarget="mypopover3" popovertargetaction="hide">Fermer</button>
</div>

Ici, nous fermerons uniquement sur le bouton "Fermer".

Le changement principal est popover="manual" – lorsque le popover est en mode manuel, nous pouvons le fermer uniquement via JS ou en cliquant sur l'élément avec popovertargetaction="hide".

Dans tous les exemples, gardez toujours un id unique pour une formation donnée de divs destinée à implémenter un seul popover. Mais aussi, faites en sorte que popovertarget pointe toujours vers cet id particulier pour que ces éléments DOM fonctionnent ensemble.

NOTE : il est cependant possible dans l'API popover standard d'avoir plusieurs ancres pointant vers le même popover. Si nécessaire, cela est naturellement autorisé.

<button popovertarget="mypopover4">Basculer le popover</button>
<div id="mypopover4" popover data-popover>
  Contenu du popover
  <button popovertarget="mypopover4" popovertargetaction="hide">Fermer</button>
</div>

<div class="container one">
  <button class="toolbar-button" interestfor="popover-b"><b>B</b></button>
  <button class="toolbar-button" interestfor="popover-i"><i>I</i></button>
  <button class="toolbar-button" interestfor="popover-u"><u>U</u></button>
</div>

<div class="container two">
  <button class="toolbar-button" interestfor="popover-b"><b>B</b></button>
  <button class="toolbar-button" interestfor="popover-i"><i>I</i></button>
  <button class="toolbar-button" interestfor="popover-u"><u>U</u></button>
</div>

<span popover="" id="popover-b" data-popover class="bottom">Gras</span>
<span popover="" id="popover-i" data-popover>Italique</span>
<span popover="" id="popover-u" data-popover>Souligné</span>

Ci-dessus, il y a deux ensembles de conteneurs -> class="container". (avec des classes séparées 'one' et 'two')

Chaque conteneur a 3 boutons.

Chaque bouton a un attribut 'interestfor' pointant vers l'id de l'un des 3 popovers.

Faites attention : nous avons 2 conteneurs avec chacun 3 boutons et seulement 3 popovers. Cela démontre en fait qu'il s'agit d'une relation : plusieurs éléments survolés peuvent déclencher l'affichage du même popover – et c'est correct et autorisé.

Et surtout : l'attribut 'interestfor' remplace 'popovertarget' et changera la façon dont le popover s'affiche.

Utiliser 'interestfor' affichera le popover simplement au survol de la souris. Au lieu de cela, avec 'popovertarget', le popover s'affiche au clic.

Pour décider où exactement le popover doit apparaître par rapport à l'élément ancre, nous utiliserons notre fichier core-css.

Comme mentionné précédemment, notre fichier core-css nécessite d'ajouter l'attribut [data-popover] à l'élément [popover].

À partir de là, le contrôle de la position du popover par rapport à l'élément ancre se fait en ajoutant une classe CSS à l'élément avec l'attribut [data-popover].

Voici les classes disponibles :

• classe top : Positionné au-dessus de l'ancre, centré horizontalement. (c'est le style par défaut utilisé même lorsqu'aucune classe n'est ajoutée à l'élément 'data-popover')

• classe bottom : Positionné en dessous de l'ancre, centré horizontalement. (c'est le style par défaut utilisé même lorsqu'aucune classe n'est ajoutée à l'élément 'data-popover')

• classe left : Positionné à gauche de l'ancre, centré verticalement. (c'est le style par défaut utilisé même lorsqu'aucune classe n'est ajoutée à l'élément 'data-popover')

• classe right : Positionné à droite de l'ancre, centré verticalement. (c'est le style par défaut utilisé même lorsqu'aucune classe n'est ajoutée à l'élément 'data-popover')

• classe top-left : Positionné au-dessus de l'ancre, son bord gauche aligné avec le bord gauche de l'ancre.

• classe top-right : Positionné au-dessus de l'ancre, son bord droit aligné avec le bord droit de l'ancre.

• classe bottom-left : Positionné en dessous de l'ancre, son bord gauche aligné avec le bord gauche de l'ancre.

• classe bottom-right : Positionné en dessous de l'ancre, son bord droit aligné avec le bord droit de l'ancre.

• classe center : Positionné directement au-dessus de l'ancre, centré à la fois horizontalement et verticalement.

• classe topleft : le coin inférieur droit du popover touche le coin supérieur gauche de l'ancre.

• classe topright : le coin inférieur gauche du popover touche le coin supérieur droit de l'ancre.

• classe bottomleft : le coin supérieur droit du popover touche le coin inférieur gauche de l'ancre.

• classe bottomright : le coin supérieur gauche du popover touche le coin inférieur droit de l'ancre.

• classe left-top : Positionné à gauche de l'ancre, son bord supérieur aligné avec le bord supérieur de l'ancre.

• classe left-bottom : Positionné à gauche de l'ancre, son bord inférieur aligné avec le bord inférieur de l'ancre.

• classe right-top : Positionné à droite de l'ancre, son bord supérieur aligné avec le bord supérieur de l'ancre.

• classe right-bottom : Positionné à droite de l'ancre, son bord inférieur aligné avec le bord inférieur de l'ancre.

Il est préférable d'obtenir des informations sur la classe de positionnement à utiliser auprès de l'utilisateur, mais si l'utilisateur spécifie un positionnement particulier en le décrivant, essayez de trouver automatiquement la meilleure classe en fonction des descriptions.

En cas de confusion de l'utilisateur ou de l'IA sur la classe à utiliser, proposez à l'utilisateur le lien vers la page de démonstration du dépôt GitHub principal où le comportement des classes est présenté de manière interactive :

https://stopsopa.github.io/skill-popover-api/demo/index.html

L'utilisateur pourra observer quelle classe offre le meilleur comportement de positionnement pour le popover en question.

À partir de cette page de démonstration, l'utilisateur peut également accéder à la page GitHub principale pour plus de détails en un seul clic sur le widget ruban.

La formation du HTML utilisant l'attribut 'data-popover' pour activer nos styles core-css est universelle.

Elle peut être utilisée en HTML vanille, React, Angular, Svelte et autres.

Cela fonctionnera tant que le HTML sous-jacent de base correspondra à ce qui est présenté dans les exemples ci-dessus et que assets/popover.css est chargé dans le contexte du navigateur.

Parfois, il devra cependant être encapsulé dans certains composants wrapper React standard ou toute autre formation/structure spécifique à un framework donné.

Faites simplement ce qui est approprié pour le contexte du framework donné en plus de ce qui est présenté dans les exemples ci-dessus.