Admin Notices in Plugin UIs

Note: Content might be outdated!

WordPress bedient sich kurzer, dynamisch erzeugter Meldungen im Administrationsbereich, um Nutzer_innen zu informieren, zu warnen, oder zu bestimmten Aktionen aufzufordern. Plugins und Themes können mit dem bewussten Einsatz der farbig hervorgehobenen Admin Notices die User Experience in WordPress entscheidend aufwerten – oder sie komplett verkacken. Dieser Beitrag stellt einige grundsätzliche Überlegung für den Erfolgsfall an.

Der Name suggeriert Falsches: Admin Notices richten sich nicht unbedingt nur an Nutzer_innen mit Administrationsrechten. Die Erfolgsmeldungen nach dem Speichern, Aktualisieren, oder Veröffentlichen eines Beitrags beispielsweise sehen Autor_innen genauso wie Administrator_innen.

Sinn und Zweck

Der vorgesehene Verwendungszweck für Admin Notices besteht in der Anzeige nutzungsrelevanter Meldungen im Backend einer WordPress-Installation; wobei die Vorgänge in Plugins und Themes natürlich genauso Nutzungsrelevanz haben können, wie Core-Prozesse.

Und was heisst jetzt nutzungsrelevant? Ein Beispiel:

Nutzer_in klickt ein Button.
WordPress macht was-auch-immer.
Nutzer_in muss wissen, wann WordPress fertig ist damit, sonst bricht Nutzer_in den Vorgang möglicherweise aus Versehen ab.
Deswegen sagt WordPress Bescheid, sobald was-auch-immer gut gelaufen ist: Bin fertig, kannst weitermachen.

Oder: Selbe Aktion, aber WordPress stößt auf ein Problem, das es nicht alleine lösen kann. Um weiteren Schaden zu vermeiden, ruft es um Hilfe: Achtung, hier ist was kaputt! Dengel’ das mal bitte zurecht, bevor du weitermachst!

Plugin- und Theme-Autor_innen sollten grundsätzlich mit einer sinnvollen, im Sinne der User Experience wertschöpfenden Verwendung von Admin Notices vertraut sein, um Nutzer_innen pro-aktiv über den Status von Aktionen informieren zu können, die seitens Plugin oder Themes ausgelöst wurden.

Wozu solltest du Admin Notices nicht einsetzen?

Die wichtigste Qualität von Admin Notices besteht darin, dass sie Nutzer_innen auffallen. Damit sie innerhalb des WordPress UI als visuell hervorgehoben wirken können, muss ihre inflationäre Verwendung vermieden werden: Admin Notices können sich abnutzen, wenn es zu viele von ihnen gibt – mit negativen Folgen für die gesamte User Experience in WordPress.

Niemals solltest du als Entwickler_in Admin Notices für Werbung, Upsells, Branding, oder irgendeinen systemfremden Zweck einsetzen.
Die Aufmerksamkeit deiner Nutzer_innen, um die du an prominenter Stelle zu werben versuchst, wird nur allzu schnell überhaupt nicht mehr erreichbar für dich sein, wenn deine Admin Notices keinen direkten Wert im Sinne der User Experience erzeugen.

Zustände

Der WordPress Core sieht momentan (v4.4.2) vier mögliche Zustände für Admin Notices vor:

Fehler (.notice-error)
Warnung (.notice-warning)
Erfolg (.notice-success)
Information (.notice-info)

Die entsprechenden CSS-Klassen des Core (zu finden in wp-admin/css/common.css) kannst du einfach dem umschließenden <div>-Element deiner Admin Notice zuweisen, und schon bist du visuell voll auf einer Welle mit dem WordPress Core.

Farbig abgestufte Admin Notices — CSS-Klassen des Core für Zustände einer Admin Notice: Fehler (rot), Warnung (gelb), Erfolg (grün), Info (blau)

Is’ gut, geh’ weg: `.is-dismissible`

Optional kannst du noch die Klasse .is-dismissible verwenden. Sie sorgt automatisch dafür, dass deine Notice ohne erneuten Reload der jeweiligen Seite weggeklickt werden kann:

Schließen-Icon: diagonales Kreuz auf kreisförmiger Hintergrundfläche — Die Klasse `.is-dismissible` fügt der Admin Notice automatisch ein Schließen-Icon hinzu.

Wichtig: .is-dismissible speichert den Klick zum Entfernen der Meldung nicht automatisch als Status.
Das manchmal gewünschte Verhalten, dass eine einmal weggeklickte Notice zukünftig verborgen bleibt, lässt sich nicht durch .is-dismissible allein, sondern nur mittels eigener Erweiterungen abbilden.

Veraltet und problematisch: `.update-nag`

Die Klasse .update-nag war vor Einführung der .notice-*-Klassen die einzige, mit der sich der Zustand Warnung farblich darstellen ließ. Daher findet sie sich immer noch in vielen Plugin UIs anstatt von .notice-warning.

Update-Nag über dem Seitentitel ›Plugins‹ — Semantisch wohl gewählter Klassenname: Der über allem schwebende ›nag‹ nervt in der Tat und soll zum baldigen Update motivieren.

Ihre Verwendung im Plugin-Kontext ist allerdings problematisch. Sie bewirkt u.a., dass der entsprechende <div> mittels jQuery über den Seiten-Titel gehievt wird; damit bekommt die Meldung eine in ihrer Priorität dem jeweiligen Seiten-Kontext übergeordnete Bedeutung, die im Zusammenhang mit Themes oder Plugins selten wünschenswert erscheinen dürfte.

Im Zusammenspiel mit der jüngeren Klasse .notice wird das Chaos dann vollends perfekt: Das Floating wird nicht an jeder beliebigen Stelle automatisch geklärt. Admin Notice zerhackt Admin Layout.

Ungeklärtes Floating von .update-nag.notice im WP-Admin — Keine harmonische Beziehung: `.update-nag` und `.notice`

Du solltest auf die Verwendung von .update-nag in jedem Fall verzichten, bzw. sie durch .notice-warning ersetzen, falls du sie bereits verwendest.

Markup

Das vom WordPress Core vorgesehene Markup für eine Admin Notice ist simpel gehalten:

ein umschließendes <div>-Element mit zwei bis drei bestimmten CSS-Klassen;
ein oder mehrere <p>-Elemente (oder theoretisch jedes andere Block-Level-Element) mit dem Inhalt der Notice

Ein simples Beispiel:

Oder mit automatisch generiertem Schließen-Icon:

Implementierung

Admin Notices können von einem Plugin oder Theme über einen Hook im WordPress-Core eingeschleust werden. Der Hook hält dabei lediglich die Position für die Anzeige vor; jegliches Verhalten der Notice, vom Auslöser für die Anzeige, bis zum Entfernen und Nicht-wieder-Anzeigen, muss vom Plugin oder Theme selbst geregelt werden.

Ein einfaches Beispiel:

Du kannst die Funktion auch wiederverwendbar schreiben:

… und dann dynamisch in Abhängigkeit von einem Optionswert und der Nutzungsberechtigungen aktiver Nutzer_innen anzeigen lassen, oder nicht:

Letzteres Beispiel hier als Mini-Plugin.

TL;DR

Admin Notices sind von einem Plugin oder Theme aus relativ leicht zu implementieren. Mit Umsicht angewendet, können sie für Nutzer_innen einen entscheidenden Mehrwert in der User Experience ihres WordPress bieten.

4 reactions on “Admin Notices in Plugin UIs”

Felix Arntz sagt:

14 February 2016 um 17:16 Uhr

Hilfreicher Beitrag! Ich muss zugeben, dass ich kürzlich irgendwann auch noch ein „update-nag“ verwendet habe… :/ Wird sofort gefixt!

Was mir noch relativ oft negativ auffällt: Nervige Admin Notices auf Multisites. Wenn man denn wirklich eine Admin Notice ausgeben möchte, nachdem das Plugin aktiviert wurde, die erst dann permanent verschwindet, wenn man sie „dismisst“ (z.B. mit AJAX), dann wäre es schön, wenn ich sie, sofern ich das Plugin im gesamten Multisite-Network aktiviere, nur einmal dort wegklicken müsste. Bitte nicht auf jeder Site einzeln.

Manchmal macht so eine Notice ja vielleicht wirklich Sinn, aber dann bitte Multisite-kompatibel.
1. Caspar Hübinger sagt:
  
  14 February 2016 um 17:24 Uhr
  
  …aber dann bitte Multisite-kompatibel
  
  Guter Punkt! Ich habe das Thema Multisite (den Hook network_admin_notices, Site Options, User Options etc.) hier absichtlich aussen vor gelassen. Wie wär’s mit einem eigenen Beitrag darüber? 😉
Chris sagt:

15 February 2016 um 10:01 Uhr

Heyho Caspar!

Es ist echt erstaunlich wie viele Plugin-/Theme-Autoren Ihre Werke nicht up-to-date halten. Ich würde aber eher darauf verweisen, dass es „Unwissenheit“ ist.. Es ist manchmal echt schwer alle Änderungen mitzubekommen. Solche Artikel helfen da immens. Danke!

Eventuell wäre so etwas auch für den Core geeignet, also eine Art „Helferlein“ (ums kurz zu halten – aber zukunftssicher zu sein):
```
function sample_the_admin_notice( $message, $type = 'info', $dismissable = FALSE ) {

	$allowed_types = array( 'error', 'warning', 'success', 'info' );

	if ( ! in_array( $type, $allowed_types ) ) {

		$msg = sprintf(
			__( 'Invalid type <code>"%s"</code>. Allowed types are: <code>"%s"</code>' ),
			esc_attr( $type ),
			implode( '", "', $allowed_types )
		);
		_doing_it_wrong( __FUNCTION__, $msg, '4.x' );

		return;
	}

	$tmpl = '<div class="notice notice-%1$s %2$s">%3$s</div>';
	printf(
		$tmpl,
		esc_attr( $type ),
		$dismissable ? 'is-dismissible' : '',
		wp_kses_post( $message )
	);
}
```
Leider nicht all so schöner Code wegen dem booleschen Parameter, müssten eigentlich 2 Funktionen sein. 🙁

Letzenendes würde ich aber gerne die Schuld auf WordPress selbst schieben, denn hier wird keinerlei Vorgabe gemacht und irgendwo in den ~4000 Zeilen CSS ein paar Klassen versteckt, die man vielleicht (nicht nur vielleicht, sondern muss) wissen sollte. Nicht mal die offizielle Doku scheint up-to-date zu sein: https://codex.wordpress.org/Plugin_API/Action_Reference/admin_notices hier ist noch „update-nag“ nicht als „veraltet“, sondern „kannste machen“ drin.

Hier kann man – mal wieder – ein Fass auf machen. Wieso gibt es keine Ordentliche API für Logging und Ausgabe von Errors? 🙂 Mhm…
1. Caspar Hübinger sagt:
  
  15 February 2016 um 13:21 Uhr
  
  Hey Chris, stimmt, die Codex-Seite ist veraltet, und das (neuere) Plugin Handbook sagt noch nichts zu Admin Notices. ~~Wäre~~ War eine gute Gelegenheit, da mal was zu ergänzen … die liebe Zeit! 🙂

Reactions are closed.