README

Stellt Schachstellungen als Bild dar. Die Stellung wird in der Forsyth-Edwards-Notation (FEN) eingegeben — der Schreibweise, die jedes Schachprogramm und jede Partiedatenbank ausgibt. Das Diagramm entsteht auf dem Server als PNG-Bild und braucht im Browser weder JavaScript noch eine eigene Schriftart.

Zwei Wege führen zum Diagramm: das Inhaltselement FEN-Diagramm mit allen Einstellmöglichkeiten und der Inserttag {{fen::…}} für schnell eingestreute Stellungen im Fließtext.

Funktionen

Inhaltselement mit Unterschrift und umfließendem Text
Inserttag {{fen::…}} für jede Stelle, an der Contao Inserttags ersetzt
16 Figurensätze, Feldgröße von 20 bis 40 Pixeln
Frei wählbare Farben für helle Felder, dunkle Felder und Rahmen
Koordinaten wahlweise ein- oder ausgeblendet
Brett drehbar (Schwarz unten)
Systemweite Voreinstellungen, auf Wunsch verbindlich für alle Diagramme

Voraussetzungen

Software	Version
PHP	8.1 oder neuer, mit der Erweiterung `gd`
Contao	4.13 LTS oder Contao 5

Die PHP-Erweiterung gd zeichnet das Bild. Sie ist bei nahezu jedem Hoster vorhanden; ob sie läuft, zeigt im Contao Manager die Systemprüfung oder auf der Kommandozeile php -m.

Installation

Im Contao Manager das Paket schachbulle/contao-fen-bundle suchen und installieren, oder auf der Kommandozeile:

composer require schachbulle/contao-fen-bundle

Danach die Datenbank aktualisieren — im Contao Manager unter „System-Wartung“ oder auf der Kommandozeile:

vendor/bin/contao-console contao:migrate

Dabei entstehen die zusätzlichen Felder in tl_content. Eine eigene Tabelle legt die Erweiterung nicht an.

Schnelleinstieg

Im Backend einen Artikel öffnen und ein neues Inhaltselement anlegen.
Als Typ unter Schach-Elemente den Eintrag FEN-Diagramm wählen.
Im Feld FEN-Code die Stellung eintragen. Voreingestellt ist die Grundstellung.
Speichern — fertig. Alle weiteren Felder sind wahlfrei.

Das Inhaltselement

FEN-Code und Diagrammtext

Feld	Bedeutung
FEN-Code	Die Stellung, siehe FEN in aller Kürze. Ein vollständiger Code darf eingefügt werden; beim Speichern bleibt davon nur der Stellungsteil übrig.
Diagramm-Unterschrift	Erscheint unter dem Brett und zusätzlich als Alternativtext des Bildes. Gut geeignet für Angaben wie „Weiß am Zug, matt in zwei Zügen“.

Figuren

Feld	Bedeutung
Figurensatz	Einer von 16 Sätzen, siehe Figurensätze.
Figurengröße	Kantenlänge eines Feldes in Pixeln: 20, 25, 30, 35 oder 40. Das Brett ist achtmal so breit, zuzüglich Rahmen und Koordinaten.

Diagramm (Rahmen)

Feld	Bedeutung
Diagramm-Rahmen	Schaltet den Rahmen ein. Erst dann erscheinen die beiden folgenden Felder.
Rahmenbreite	1 bis 6 Pixel.
Rahmenfarbe	Über den Farbwähler oder als sechsstellige Hexadezimalzahl ohne `#`.

Felderfarben

Feld	Bedeutung
Farbe weiße Felder	Voreinstellung `eecfa3` (heller Sandton).
Farbe schwarze Felder	Voreinstellung `8a8a8a` (mittleres Grau).

Diagramm (Darstellung)

Feld	Bedeutung
Koordinaten anzeigen	Linien `a`–`h` über und unter dem Brett, Reihen `1`–`8` links und rechts. Die Beschriftung liegt in einem weißen Streifen und vergrößert das Bild.
Brett drehen	Zeigt die Stellung aus der Sicht von Schwarz: Schwarz steht unten, die Koordinaten laufen rückwärts. Der FEN-Code bleibt unverändert.

Text

Feld	Bedeutung
Text	Beliebiger Fließtext, im Rich-Text-Editor bearbeitbar. Inserttags sind erlaubt.
Diagrammausrichtung	Legt fest, wo das Diagramm im Verhältnis zum Text steht: oberhalb, links, rechts oder unterhalb. Bei links und rechts umfließt der Text das Brett.

Der Inserttag

Für eine Stellung mitten im Fließtext genügt der Inserttag. Er funktioniert in jedem Feld, in dem Contao Inserttags ersetzt — im Text eines beliebigen Inhaltselements, in Nachrichten, in Ereignissen, in Formularerklärungen.

{{fen::r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R}}

Ein vollständiger FEN-Code darf ebenfalls stehen, alles ab dem ersten Leerzeichen wird nicht ausgewertet:

{{fen::r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 0 1}}

Zwei Dinge unterscheiden den Inserttag vom Inhaltselement:

Er kennt nur die Stellung. Figurensatz, Größe, Farben, Rahmen und Koordinaten kommen immer aus den Systemeinstellungen.
Das Diagramm steht als eigener Block unterhalb des Absatzes, in dem der Tag steht — nicht mitten im Satz.

Mit {{cache_fen::…}} steht dieselbe Ersetzung zur Verfügung, ohne dass Contao sie mit der Seite zwischenspeichert. Nötig ist das für Diagramme praktisch nie, weil dieselbe Stellung immer dasselbe Bild ergibt.

Systemeinstellungen

Unter System → Einstellungen gibt es den Bereich FEN-Diagramm. Die Werte dort sind die Vorgabewerte für neu angelegte Inhaltselemente und zugleich die Einstellungen, mit denen der Inserttag zeichnet.

Der Haken Immer Voreinstellungen benutzen macht diese Werte verbindlich: Sämtliche Diagramme der Website sehen dann gleich aus, und im Inhaltselement verschwinden die Felder für Figuren, Farben, Rahmen und Koordinaten aus der Eingabemaske. Übrig bleiben FEN-Code, Unterschrift, Brettdrehung und Text. Die bereits gespeicherten Werte gehen dabei nicht verloren — sie werden nur nicht mehr ausgewertet und erscheinen wieder, sobald der Haken fällt.

FEN in aller Kürze

Ein FEN-Code beschreibt die Stellung Reihe für Reihe, beginnend mit der achten Reihe (oben, bei Schwarz) und endend mit der ersten. Die Reihen trennt ein Schrägstrich.

Großbuchstaben sind weiße Steine, Kleinbuchstaben schwarze.
K König, Q Dame, R Turm, B Läufer, N Springer, P Bauer.
Eine Ziffer von 1 bis 8 steht für so viele leere Felder in Folge.

Die Grundstellung lautet damit:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

Ein weißer König auf e1 gegen einen schwarzen König auf e8:

4k3/8/8/8/8/8/8/4K3

Vollständige FEN-Codes führen hinter der Stellung noch Zugrecht, Rochade- und En-passant-Rechte sowie zwei Zugzähler auf. Für ein Bild ist davon nichts von Belang; diese Angaben dürfen mitgeliefert werden und werden verworfen.

Unbekannte Zeichen werden übergangen, fehlende Felder bleiben leer. Ein Tippfehler führt also zu einem unvollständigen Brett, nicht zu einer Fehlermeldung.

Figurensätze

adventurer, alfonso, cases, condal, harlequin, kingdom, leipzig, line, lucena, magnetic, mark, marroquin, maya, mediaeval, merida, motif

Voreingestellt ist merida — der Satz, den auch die meisten Schachbücher verwenden. line und motif sind Strichzeichnungen und eignen sich für kleine Diagramme, mediaeval und kingdom sind reich verziert und wollen mindestens 35 Pixel Feldgröße.

Wie das Bild entsteht

Das Diagramm wird nicht in die Seite eingebettet, sondern über eine eigene Adresse geladen:

/fen/diagramm.png?fen=4k3/8/8/8/8/8/8/4K3&satz=merida&feld=35&koordinaten=1&drehen=0&rand=0&randfarbe=636060&hell=eecfa3&dunkel=8a8a8a

Diese Adresse baut das Inhaltselement beziehungsweise der Inserttag zusammen; von Hand aufgerufen werden muss sie nie. Die Antwort ist ein Jahr lang gültig und trägt ein ETag, sodass Browser und vorgeschaltete Zwischenspeicher dasselbe Diagramm nur einmal holen.

Alle Werte werden beim Zeichnen geprüft. Unbekannte Figurensätze, unsinnige Größen oder fehlerhafte Farbangaben führen zur jeweiligen Voreinstellung, nie zu einem Fehler. Feldgröße und Rahmenbreite sind nach oben begrenzt, damit ein von Hand zusammengebauter Aufruf den Server nicht mit riesigen Bildern beschäftigen kann.

Eigene Vorlage

Die Vorlage ce_fen.html5 lässt sich wie jede Contao-Vorlage im Verzeichnis templates/ überschreiben. Zur Verfügung stehen darin:

Variable	Inhalt
`$this->src`	Adresse des Diagrammbildes
`$this->diasize`	Kantenlänge des Bildes in Pixeln
`$this->caption`	Diagramm-Unterschrift
`$this->text`	Der Text des Elements
`$this->floatClass`	Ausrichtung: `above`, `left`, `right` oder `below`
`$this->alignment`	`left` oder `right`, sonst leer

Über das Feld Vorlage im Bereich Vorlageneinstellungen des Elements lässt sich außerdem eine eigene Vorlage auswählen, deren Name mit ce_fen_ beginnt.

Umstieg von Version 1.x

Version 2.0.0 zeichnet die Diagramme über eine Symfony-Route statt über die Datei fen.php im Asset-Verzeichnis. Für die Inhalte ändert sich nichts — Datenbankfelder, Inhaltselement und Inserttag bleiben, wie sie waren. Zu beachten ist:

Zwischenspeicher leeren. Erst danach kennt Contao die neue Route und die Seiten enthalten die neue Bildadresse.
Eigene Kopien von ce_fen.html5 anpassen. Statt $this->params und dem fest eingetragenen Pfad /bundles/contaofen/fen.php gibt es jetzt die fertige Adresse in $this->src.
Feldrechte prüfen. Die Felder des Inhaltselements sind jetzt rechtepflichtig. Benutzergruppen, die nicht als Administrator arbeiten, brauchen sie unter Benutzergruppen → Felder freigegeben. Administratoren sind nicht betroffen.
Die Einstellung „Nur Gäste anzeigen“ ist aus dem Element entfallen. Contao hat sie in Version 5 gestrichen.

Fehlersuche

Es erscheint kein Bild, nur der Rahmen. Der häufigste Grund ist ein nicht geleerter Zwischenspeicher nach dem Update. Danach prüfen, ob die Adresse /fen/diagramm.png?fen=4k3/8/8/8/8/8/8/4K3 im Browser ein Brett zeigt.

Die Adresse liefert „Seite nicht gefunden“. Dann ist die Route nicht registriert. Im Contao Manager den Zwischenspeicher neu aufbauen oder auf der Kommandozeile vendor/bin/contao-console cache:clear.

Die Felder bleiben leer, nur das Brettmuster erscheint. Der Figurensatz fehlt: Das Verzeichnis vendor/schachbulle/contao-fen-bundle/src/Resources/figuren ist unvollständig, die Erweiterung sollte neu installiert werden.

Das Bild ist verzerrt. Eine eigene Vorlage rechnet die Bildbreite noch selbst aus. Statt eigener Rechnung $this->diasize verwenden.

Herkunft der Figurengrafiken

Die Figurensätze und das ursprüngliche Zeichenverfahren stammen aus dem Projekt ChessImager von Steven L. Eddins und stehen unter der MIT-Lizenz; der Lizenztext liegt bei den Grafiken in src/Resources/figuren/license.txt. Der Zeichencode selbst wurde für Version 2.0.0 neu geschrieben.

Lizenz

LGPL-3.0-or-later

Frank Hoppe

schachbulle / contao-fen-bundle

Maintainers

Package info

Statistics

Security