stopsopa/skill-popover-api

Wenn sie im Vergleich zu unserer lokalen Kopie aktualisiert wird, muss unsere lokale Kopie entsprechend angepasst werden.

Wenn zum ersten Mal um die Nutzung der Popover-API gebeten wird, beginne damit, die Datei assets/popover.css irgendwo ins Projekt zu kopieren.

Es ist sinnvoll, mit dem Benutzer abzustimmen, wohin genau die Datei kopiert und wie sie geladen werden soll, falls dies nicht klar ist.

Im Grunde ist es aber eine einfache flache CSS-Datei. Wenn das Framework also Orte zum Laden vorsieht, folge einfach den üblichen Standards. Versuche lediglich, ein doppeltes Laden aus ergonomischen Gründen zu vermeiden.

Wann das Popover bei Klick auf den Anker angezeigt werden soll

Bei Verwendung unseres core-css zur Positionierung des Popovers ist die grundlegende Struktur:

<button popovertarget="mypopover2">Popover umschalten</button>
<div id="mypopover2" popover data-popover>
  Popover-Inhalt
  <button popovertarget="mypopover2" popovertargetaction="hide">Schließen</button>
</div>

Im obigen Beispiel haben wir einen Button, der als Anker dient. Ein Klick auf den Button zeigt das Popover an (das Element mit dem [popover]-Attribut), und ein erneuter Klick verbirgt es.

Ein Klick innerhalb des Popovers verbirgt es jedoch NICHT, mit Ausnahme des Schließen-Buttons – dieser schließt es.

Ein Klick außerhalb des Popovers verbirgt das Popover.

Wenn du der Struktur dieses Beispiels folgst, wird nichts anderes als die Standardfunktionalität der Popover-API genutzt. Du kannst gerne beliebige Anpassungen für den Anwendungsfall des Benutzers vornehmen.

HINWEIS: Die Definition eines „Schließen“-Buttons ist hier optional; alles funktioniert auch ohne ihn zu 100%.

Die HTML-Formation entspricht also dem Standard-Layout.

Der Haupt-Enabler hier ist das Attribut 'data-popover'. Es aktiviert die Styles aus assets/popover.css, die hauptsächlich für die Positionierung des Popovers relativ zum Anker zuständig sind.

Du kannst das Attribut [data-popover] auch weglassen, dann verlierst du unsere benutzerdefinierten Styles und das Popover verhält sich wie ein normales natives Element. Wenn das Attribut [data-popover] fehlt, verwendest du die reine, rohe Popover-API, und dieses Skill hat vermutlich nichts zu bieten. Tue dann einfach, was mit der Standard-Popover-API-Implementierung nötig ist.

Der Punkt ist aber, dass das Attribut [data-popover] als explizite Trennung dient: Einerseits die Handhabung der Popover-API mit den von diesem Skill bereitgestellten Styles, andererseits die manuelle Handhabung. Wenn [data-popover] nicht angegeben ist, greift unser CSS nicht in deine manuelle Popover-API-Implementierung ein.

Du kannst also grundsätzlich [data-popover] verwenden, um bei unseren Styles zu bleiben, oder es weglassen, wenn du die rohe native Popover-API bevorzugst.

Die in diesem Dokument gezeigten Beispiele können durch jedes beliebige JavaScript und andere HTML-APIs gesteuert werden, die normalerweise mit der nativen Popover-API verwendet werden können.

<button popovertarget="mypopover3">Popover umschalten</button>
<div id="mypopover3" popover="manual" data-popover>
  unser Popover-Inhalt
  <button popovertarget="mypopover3" popovertargetaction="hide">Schließen</button>
</div>

Hier schließt du das Popover nur über den Schließen-Button.

Die wesentliche Änderung ist popover="manual" – im manuellen Modus kann das Popover nur per JS oder durch Klick auf ein Element mit popovertargetaction="hide" geschlossen werden.

In allen Beispielen sollte die id für eine bestimmte Gruppe von Divs, die ein einzelnes Popover implementieren, immer eindeutig sein. Außerdem sollte popovertarget immer auf diese bestimmte id verweisen, damit diese DOM-Elemente zusammen funktionieren.

HINWEIS: Es ist jedoch in der Standard-Popover-API möglich, mehrere Anker auf dasselbe Popover zeigen zu lassen. Falls nötig, ist das natürlich erlaubt.

<button popovertarget="mypopover4">Popover umschalten</button>
<div id="mypopover4" popover data-popover>
  Popover-Inhalt
  <button popovertarget="mypopover4" popovertargetaction="hide">Schließen</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">Fett</span>
<span popover="" id="popover-i" data-popover>Kursiv</span>
<span popover="" id="popover-u" data-popover>Unterstrichen</span>

Oben gibt es zwei Containergruppen -> class="container". (mit den separaten Klassen 'one' und 'two')

Jeder Container hat 3 Buttons.

Jeder Button hat ein 'interestfor'-Attribut, das auf die id in den 3 Popovern verweist.

Beachte, dass wir 2 Container mit jeweils 3 Buttons haben, aber nur 3 Popover. Dies zeigt tatsächlich, dass die Beziehung erlaubt ist: Mehrere überfahrene Elemente können dasselbe Popover auslösen – das ist in Ordnung und erlaubt.

Und am wichtigsten: Das Attribut 'interestfor' anstelle von 'popovertarget' ändert, wie das Popover angezeigt wird.

Die Verwendung von 'interestfor' zeigt das Popover bereits beim Darüberfahren mit der Maus an. Im Gegensatz dazu zeigt 'popovertarget' das Popover erst bei einem Klick an.

Um zu entscheiden, wo genau das Popover relativ zum Anker erscheinen soll, verwenden wir unsere core-css-Datei.

Wie bereits erwähnt, erfordert unsere core-css-Datei, dass wir dem [popover]-Element das Attribut [data-popover] hinzufügen.

Ab diesem Punkt wird die Position des Popovers relativ zum Anker durch das Hinzufügen einer CSS-Klasse zu dem Element mit dem [data-popover]-Attribut gesteuert.

Hier sind die verfügbaren Klassen:

• Klasse top: Über dem Anker positioniert, horizontal zentriert. (Dies ist der Standardstil, der auch verwendet wird, wenn dem 'data-popover'-Element keine Klasse hinzugefügt wird)

• Klasse bottom: Unter dem Anker positioniert, horizontal zentriert. (Dies ist der Standardstil, der auch verwendet wird, wenn dem 'data-popover'-Element keine Klasse hinzugefügt wird)

• Klasse left: Links vom Anker positioniert, vertikal zentriert. (Dies ist der Standardstil, der auch verwendet wird, wenn dem 'data-popover'-Element keine Klasse hinzugefügt wird)

• Klasse right: Rechts vom Anker positioniert, vertikal zentriert. (Dies ist der Standardstil, der auch verwendet wird, wenn dem 'data-popover'-Element keine Klasse hinzugefügt wird)

• Klasse top-left: Über dem Anker positioniert, seine linke Kante bündig mit der linken Kante des Ankers.

• Klasse top-right: Über dem Anker positioniert, seine rechte Kante bündig mit der rechten Kante des Ankers.

• Klasse bottom-left: Unter dem Anker positioniert, seine linke Kante bündig mit der linken Kante des Ankers.

• Klasse bottom-right: Unter dem Anker positioniert, seine rechte Kante bündig mit der rechten Kante des Ankers.

• Klasse center: Direkt über dem Anker positioniert, sowohl horizontal als auch vertikal zentriert.

• Klasse topleft: Die untere rechte Ecke des Popovers berührt die obere linke Ecke des Ankers.

• Klasse topright: Die untere linke Ecke des Popovers berührt die obere rechte Ecke des Ankers.

• Klasse bottomleft: Die obere rechte Ecke des Popovers berührt die untere linke Ecke des Ankers.

• Klasse bottomright: Die obere linke Ecke des Popovers berührt die untere rechte Ecke des Ankers.

• Klasse left-top: Links vom Anker positioniert, seine obere Kante bündig mit der oberen Kante des Ankers.

• Klasse left-bottom: Links vom Anker positioniert, seine untere Kante bündig mit der unteren Kante des Ankers.

• Klasse right-top: Rechts vom Anker positioniert, seine obere Kante bündig mit der oberen Kante des Ankers.

• Klasse right-bottom: Rechts vom Anker positioniert, seine untere Kante bündig mit der unteren Kante des Ankers.

Es ist vorzuziehen, die Information, welche Positionierungsklasse verwendet werden soll, vom Benutzer zu erfragen. Wenn der Benutzer jedoch eine bestimmte Positionierung nur beschreibt, versuche, basierend auf der Beschreibung automatisch die beste Klasse zu finden.

Falls der Benutzer oder die KI unsicher ist, welche Klasse verwendet werden soll, schlage dem Benutzer den Link zur Haupt-GitHub-Demoseite vor, auf der das Verhalten der Klassen interaktiv dargestellt wird:

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

Der Benutzer kann dort beobachten, welche Klasse das beste Positionierungsverhalten für das betreffende Popover bietet.

Von dieser Demoseite aus kann der Benutzer auch mit nur einem Klick auf das Ribbon-Widget zur Haupt-GitHub-Seite für weitere Details gelangen.

Die HTML-Formation unter Verwendung des 'data-popover'-Attributs zur Aktivierung unserer core-css-Styles ist universell.

Sie kann in Vanilla HTML, React, Angular, Svelte und anderen verwendet werden.

Sie funktioniert, solange das grundlegende zugrunde liegende HTML den oben gezeigten Beispielen entspricht und assets/popover.css im Browserkontext geladen ist.

Gelegentlich muss sie jedoch mit einigen Standard-React-Wrapper-Komponenten oder anderen frameworkspezifischen Strukturen umschlossen werden.

Tue einfach, was für den jeweiligen Framework-Kontext richtig ist, basierend auf den obigen Beispielen.