[3.3] Toggle Control (Schalter-Stil zentral festlegen)

[LukeWCS]

Name der Erweiterung:

Toggle Control

Autor:

LukeWCS

Aktuelle Version der Erweiterung:

1.1.0

Voraussetzungen:

• phpBB 3.3.0 - 3.3.x
• PHP 7.1.3 - 8.3.x

Beschreibung der Erweiterung:

Ermöglicht es, bei Erweiterungen zentral entscheiden zu können, welcher visuelle Stil für Ja/Nein-Schalter verwendet werden soll, sofern Erweiterungen kompatibel mit Toggle Control sind. Dabei werden andere Erweiterungen nicht direkt beeinflusst, sondern es wird lediglich eine Schnittstelle zur Verfügung gestellt, die Entwickler nutzen können. Zur Auswahl stehen folgende Stile:

• Schiebeschalter (Toggle)
• Kontrollkästchen (Checkbox)
• Radio Knöpfe (phpBB Standard)

Für Entwickler hat Toggle Control den Vorteil, das keine eigene Umschalt-Möglichkeit eingebaut werden muss. Dadurch entfällt:

1. Eine Konfig-Variable per Migration anlegen.
2. Einen Schalter im ACP Template einbauen.
3. Den Schalter im ACP Controller behandeln.
4. Sprachvariablen anlegen.

Hintergrund
Die grundsätzliche Idee zu dieser Erweiterung hatte ich, als ich begonnen hatte in meine Erweiterungen die Kirk-Toggles einzubauen. Inzwischen werden diese Toggles auch von anderen Entwicklern eingesetzt. Bei den bisherigen Erweiterungen, wo Toggles verwendet werden, gibt es a) entweder eine direkte Möglichkeit im ACP Modul die Toggles auf klassische Ja/Nein Radio Buttons umstellen zu können, b) eine "hardcoded" Möglichkeit im Template oder c) gar keine Möglichkeit. Mit Toggle Control werden alle 3 Szenarien quasi standardisiert und eine zentrale Möglichkeit zur Umschaltung geboten.

Ein weiterer Grund ist der Umstand, dass es Menschen mit visuellen oder motorischen Störungen gibt. Solche Menschen haben unter Umständen also gewisse Handicaps bei der Bedienung einer GUI (Graphical User Interface = Grafische Benutzer-Oberfläche). Radio Buttons für simple Ja/Nein Schalter sind eigentlich ein Relikt aus der Web Steinzeit, haben aber einen Vorteil gegenüber Checkboxen und Toggles: ein gewünschter Zustand kann explizit ausgewählt werden und der Schalter ändert dann auch bei erneutem Klick darauf nicht mehr seinen Zustand. Wir haben hier also eine direkte Zustandsänderung. Bei Checkboxen/Toggles kann dagegen ein Zustand nicht gezielt ausgewählt werden, weil der vorherige Zustand des Schalters relevant ist. Deswegen haben wir hier eine indirekte Zustandsänderung.

Enthaltene Sprachen:

• de
• de_x_sie
• en

Download der Erweiterung:

GitHub Releases (mit Changelog)

Hinweis: Versionen aus dem genannten GitHub Release-Bereich sind für das Live-Forum gedacht. Dagegen dürfen Versionen aus dem Entwickler-Bereich nicht in einem Live-Forum installiert werden! Im Entwickler-Bereich können sich laufend Dateien und Strukturen ändern, das liegt in der Natur der Sache. Wer Versionen aus dem Entwickler-Bereich vorab testen will, kann (und sollte) diese in einem Test-Forum installieren.

Für Administratoren: Liste der kompatiblen Erweiterungen

Die Reihenfolge ist chronologisch nach Zeitpunkt des Updates, ab dem eine Erweiterung kompatibel zu Toggle Control ist.

1. 07.12.2023 Adressverwaltung Tourziele (Mike-on-Tour)
2. 09.12.2023 Extension bridge for “Statistics Block” (chris1278)
3. 09.12.2023 Stats Permissions (Rechte für den Statistik-Bereich) (LukeWCS)
4. 09.12.2023 Disable Emojis (Emojis im Board deaktivieren) (LukeWCS)
5. 13.12.2023 Image upload use ImageMagick (IMC)
6. 13.12.2023 [Fork] Recent Topics NG (IMC & LukeWCS)
7. 15.12.2023 Hangman Spiel (Mike-on-Tour)
8. 19.12.2023 Extension Manager Plus (verbesserte Erweiterungsverwaltung) (LukeWCS)
9. 01.01.2024 BBCode Page (Kirk)
10. 06.01.2024 Newest X Users (Kirk)
11. 08.01.2024 LF who was here 2 (Wer war da?) (LukeWCS)
12. 09.01.2024 Usermap for phpBB (Mike-on-Tour)
13. 12.01.2024 DSGVO/GDPR Private Download´s (chris1278)
14. 13.01.2024 Sidebar (Kirk)
15. 10.02.2024 Top Posters (Kirk)
16. 21.02.2024 Collapse Quote (IMC)
17. 06.03.2024 Userreminder (Mike-on-Tour)
18. 13.03.2024 Sudoku (Mike-on-Tour)
19. 23.03.2024 Sitelogo responsive (Kirk)
20. 25.03.2024 Force Account Reactivation (Konto-Reaktivierung erzwingen) (LukeWCS)
21. 31.03.2024 Average Daily Posts and Topics on Index (adptstatistics) (Kirk)
22. 15.04.2024 Delete Inactive Members (Mike-on-Tour)

Für Entwickler: Anpassung an Toggle Control

Dieser Abschnitt ist für Entwickler bestimmt, die bereits die Kirk-Toggles (oder andere) nutzen und eine Kompatibilität ihrer Erweiterung zu Toggle Control schaffen möchten. Die Schnittstelle zu Toggle Control besteht aus einer simplen Template Variable, die in jedem ACP, MCP und UCP Template abgefragt werden kann.

Wer bereits die Kirk-Toggles nutzt, zusammen mit meinem Twig Makro switch(), muss lediglich das Makro durch eine neue Version ersetzen, das auch Checkboxen und Radio Buttons generieren kann. Dann genügt das Hinzufügen einer Twig Zeile am Anfang des Templates, sowie die Twig Variable switch_type bei jedem switch() Aufruf als dritten Parameter zu notieren. Nachfolgend alle benötigten Komponenten und Details dazu.

Übersicht

1. Lokale Twig Variable definieren
2. Generierung des Schalter-HTMLs per Makro-Aufruf
3. Das Twig Makro
4. Die Kirk-Toggles (CSS)
5. Vollständiges Beispiel
6. Link zu Toggle Control

1. Lokale Twig Variable definieren

Platzierung: Am Anfang des Templates
Anpassung nötig: Nein. Nur wenn man vom Standard abweichen will: Neben toggle gibt es noch checkbox und radio.

Code: Alles auswählen

{% set switch_type = TOGGLECTRL_TYPE ?? 'toggle' %}

Mit dieser Zeile wird die lokale Twig Variable switch_type mit dem Inhalt der globalen Template Variable TOGGLECTRL_TYPE definiert, sofern diese vorhanden ist. Wenn Toggle Control nicht installiert ist oder wenn der Hauptschalter von Toggle Control deaktiviert ist, dann wird auch die globale Template Variable nicht generiert. In diesem Fall gilt das, was hinter ?? definiert wurde. Wer also lieber Radio Buttons als Standard vorgeben möchte, ersetzt in der oben gezeigten Twig Zeile einfach toggle durch radio.

Zusatz:
Der Umstand, dass die globale Template Variable nur bei aktviertem Hauptschalter generiert wird, kann auch dazu genutzt werden, um im Template darauf reagieren zu können. Möchte man zum Beispiel einen Twig Block nur dann ausführen, wenn Toggle Control aktiviert ist, kann man das wie folgt erreichen:

Code: Alles auswählen

{% if TOGGLECTRL_TYPE is defined %}
...
{% endif %}

Möchte man umgekehrt einen Twig Block nur dann ausführen, wenn Toggle Control nicht aktiviert ist, ersetzt man im oben gezeigten Twig Block den Teil is defined durch is not defined.

2. Generierung des Schalter-HTMLs per Makro-Aufruf

Platzierung: Anstelle des bisherigen Schalter-HTMLs bzw. Makro-Aufruf, sofern schon vorhanden.
Anpassung nötig: Ja. Hier sind die Namen der Formular-Elemente und Template-Variablen der jeweiligen Erweiterung relevant.

Code: Alles auswählen

{{ _self.switch('name_des_formular_elements', TEMPLATE_VARIABLE_DES_FORMULAR_ELEMENTS, switch_type) }}

Beispiel:

Code: Alles auswählen

		<dl>
			<dt>
				<label>{{ lang('TOGGLECTRL_ENABLED') ~ lang('COLON') }}</label><br>
				<span>{{ lang('TOGGLECTRL_ENABLED_EXP') }}</span>
			</dt>
			<dd>
				{{ _self.switch('togglectrl_enabled', TOGGLECTRL_ENABLED, switch_type) }}
			</dd>
		</dl>

3. Das Twig Makro

Platzierung: Am Ende des Templates.
Anpassung nötig: Nein. Es sei denn, es werden andere Toggles als die Kirk-Toggles benutzt, dann muss das Makro eventuell angepasst werden.

Code: Alles auswählen

{% macro switch(name, checked = false, type = 'toggle') -%}
	{% if type == 'toggle' || type == 'checkbox' -%}
		<input type="checkbox" class="{{ type }}" name="{{ name }}" value="1"{{ checked ? ' checked' }}>
	{%- elseif type == 'radio' -%}
		<label><input type="radio" class="radio" name="{{ name }}" value="1"{{ checked ? ' checked' }}> {{ lang('YES') }}</label>
		<label><input type="radio" class="radio" name="{{ name }}" value="0"{{ !checked ? ' checked' }}> {{ lang('NO') }}</label>
	{%- endif %}
{%- endmacro %}

4. Die Kirk-Toggles (CSS)

Platzierung: Einfach im bestehenden CSS des ACP Moduls einfügen. Optional wäre auch eine separate CSS Datei denkbar.
Anpassung nötig: Nein. Das ist aber eine Frage des Geschmacks.

Code: Alles auswählen

/*
* phpBB ACP Toggles - A CSS class that makes it easy to display checkboxes as toggles.
* Source     : https://danklammer.com/articles/simple-css-toggle-switch/
* Revision by: Kirk (customization and optimization), LukeWCS (optimization)
*/

.toggle {
	-webkit-appearance: none;
	-moz-appearance: none;
	appearance: none;
	width: 38px;
	height: 17px;
	position: relative;
	border-radius: 50px;
	cursor: pointer;
	font-family: FontAwesome;
	transition: background-color 0.2s;
}

.toggle:before {
	position: absolute;
	width: 14px;
	height: 13px;
	background-color: #ffffff;
	top: 2px;
	border-radius: 50%;
	display: flex;
	justify-content: center;
	align-items: center;
	left: 22px;
	content: "\f00d";
	transition: 0.2s;
}

.toggle,
.toggle:hover,
.toggle:focus {
	background-color: #cccccc;
	border: none;
	color: #000000;
}

.toggle:checked {
	background-color: #3b87ab;
}

.toggle:checked:before {
	left: 2px;
	content: "\f00c";
}

5. Vollständiges Beispiel

Wer die einzelnen Komponenten als Ganzes sehen möchte, kann dazu die Dateien von Toggle Control sichten:

adm/style/acp_togglectrl_settings.html zeigt:

• Die Zeile mit der set Anweisung.
• Den Aufruf des switch() Makros.
• Das switch() Makro selbst.

adm/style/acp_togglectrl_settings.css zeigt:

• Das CSS für die Kirk-Toggles.

6. Link zu Toggle Control

Wer seine Erweiterung kompatibel zu Toggle Control gestaltet hat und darauf hinweisen möchte, könnte dazu den folgenden BBcode verwenden:

Code: Alles auswählen

Kompatibel mit [url=https://www.phpbb.de/community/viewtopic.php?t=246978]Toggle Control (Schalter-Stil zentral festlegen)[/url]

[Mike-on-Tour]

Wir hatten uns ja schon zu Toggle Control ausgetauscht und ich bin einer derjenigen mit einer "hardcoded" Möglichkeit im Template, um von Toggles auf Radio Buttons wechseln zu können, deshalb werde ich jetzt nach und nach meine Erweiterungen kompatibel mit Toggle Control machen.
Das erweitert einerseits die Möglichkeiten der Darstellung der von mir genutzten Ja/Nein-Schalter (um einfache Checkboxen) und vereinfacht andererseits die Auswahl durch den jeweiligen Administrator.

Ich finde deine Erweiterung also gut.

[IMC]

Ich habe mir jetzt auch die Zeit genommen TC zu testen.
Dazu habe ich die Unterstützung von TC auch in einer meiner Erweiterungen eingebaut. Alle drei unterstützenden Erweiterungen in meinem Testboard haben tadellos auf die Umschaltung von TC reagiert. Meine anderen Erweiterungen werde ich ebenfalls entsprechend ergänzen.

[LukeWCS]

Release 1.0.0 online

@Mike-on-Tour

Merci Mike. Ich habe eine weitere Spoiler Box eingebaut und TZV hinzugefügt.

@IMC

Alles klar Thorsten. Sobald das soweit ist, füge ich die Exts der Liste hinzu. RT ist ja schon angepasst.

[Mike-on-Tour]

Release 1.0.0 heruntergeladen, wird dann wohl heute noch installiert.

Danke für die Spoiler Box mit den Erweiterungen, das wird sicher hilfreich sein, wenn die kompatiblen Erweiterungen zentral aufgelistet werden.
Wie soll die später, wenn es mehr kompatible Exts gibt, organisiert werden? Zeitlich oder nach vendor (alphabetisch)?

[LukeWCS]

@Mike

Erstmal nur eine chronologische Auflistung nach Release. Sortierung nach Name oder Vendor eher nicht, so eine Link Liste ist in BBcode sehr umständlich anzulegen und zu pflegen. ^^

[Mike-on-Tour]

Stimmt, das ist mühsam.
Ich werde es bei meinen Exts mit dazu schreiben, dann kann man es auch dort nachlesen.

[LukeWCS]

Version 1.0.1 veröffentlicht.

Das Update betrifft Entwickler insofern, weil das switch() Makro einen kleinen Schönheitsfehler hatte: bei Checkboxen wurde kein Pointer-Cursor erzeugt. Das betrifft also nicht nur TC selbst, sondern jede Ext die das Makro nutzt. Das ist allerdings wirklich nur ein minimales optisches Problem, kein echter Fehler.

https://github.com/LukeWCS/toggle-contr ... f1ceef4cf8

Anleitung ebenfalls angepasst.

Laut meiner Recherche werden von phpBB Checkboxen in insgesamt 24 ACP Templates verwendet. In 23 wird dabei die Klasse radio definiert, nur in 1 Template wird, was korrekt wäre, checkbox definiert. Im ACP wäre das:

ACP > ANPASSEN > STYLE-VERWALTUNG > Styles

Das Makro verwendet jetzt für Checkbox entsprechend die Klasse checkbox. Ob nun das oder radio ist unterm Strich aber irrelevant, denn die CSS Definition von phpBB sieht so aus:

Code: Alles auswählen

input.radio, input.checkbox, input.permissions-checkbox {
	width: auto !important;
	background-color: transparent;
	border: none;
	cursor: pointer;
}

Das geht zurück bis 3.1.0.

[Mike-on-Tour]

Merci, habe das geänderte Makro jetzt übernommen.
Werde ich die Tourzielverwaltung wohl nochmal nachbessern müssen, aber da genügt eigentlich der Austausch einer HTML-Datei, die kann ich einzeln nachschieben für die Leute, die unbedingt die Checkbox möchten.

[LukeWCS]

Jo das ist nur Kleinkram und nichts, was ein Update nur deswegen nötig machen würde. Die Checkbox funktioniert ja trotzdem.

Aber ein Fehler ist ein Fehler und wird korrigiert und kommuniziert, auch weil TC ja gleichzeitig neben seiner Funktion auch als Referenz und Demo für Entwickler dient.