Der Yaml-Header « ◉ » Markdown

Seitenlayouts

Aktualisiert am 10.03.2024 Lesedauer 3 - 4 Min.

Mit dem über den Yaml-Header zugewiesenen Layout wird die Darstellung der Zielseite im Browser definiert. Sie enthält die Strukturelemente und Formatanweisungen, die der Browser für die (ansprechende) Darstellung benötigt.

Mit dem Layout-Parameter könnte jeder Seite eine eigene Vorlage zugewiesen werden. Für Wartung und Pflege sind möglichst wenige vorteilhafter. Tatsächlich funktionieren die meisten  OSE -Webseiten mit einem einzigen Layout, deren Varianten mittels Variablen und Funktionen individuellen Seitenanforderungen angepasst werden.

Die Webseiten dieser Domäne verwenden das nachfolgende Layout. Es ist „ein bisschen spezieller“, bietet dafür sehr konkrete Beispiele, wie Variablen und Funktionen in einer Seitenvorlage verwendet werden können.

Das Layout ist das zentrale Element für die Erstellung von Webseiten mit  OSE .

Es ist unkritisch, wenn anfangs einiges im Beispiel unklar bleibt. Bei Anforderungen an Resultate wird das Layout in den Fokus rücken. Hier finden sich dann wahrscheinlich viele Antworten auf Fragen.

Layout dieser Webseite

Ein Layout kann sich mit der Zeit verändern. Das hier abgebildete war bei der letzten Bearbeitung dieser Seite am 10.03.2024 das aktuelle.

Zu den Erläuterungen

/* PHP-Variablen für verwendete Scripte */
<?php
$base = $_SERVER['REQUEST_SCHEME'] . '://'. $_SERVER['SERVER_NAME'];
$greeting='%%%title%%%';
$gruppe = intval('%%%gruppe%%%');
$rang = intval('%%%!rang%%%');
$menu   = '%%%!submenu%%%'; include_once ($_SERVER["DOCUMENT_ROOT"] . '/res/zListe.php');
include_once ($_SERVER["DOCUMENT_ROOT"] . '/res/zFold.php');
$wo = pathinfo($_SERVER['REQUEST_URI'], PATHINFO_DIRNAME) . '/';
$navblock = blaettern($wo,str_pad(intval('%%%!rang%%%'), 5 , '0' , STR_PAD_LEFT) . '%%%title%%%','fold');
$nav = (!isset($_GET['m'])) ? 'checked ' : '';
­?­>
/* Hier fängt das „eigentliche“ HTML-Layout an */
<!DOCTYPE html><html id="top" lang="de" prefix="og: http://ogp.me/ns#">
<head>
/* Die Meta-Daten werden mit Yaml-Variablen gefüllt oder ggf. eintfernt */
<title>%%%title%%%</title>
<meta charset="utf-8" />
<meta name="robots" content="%%%!robots%%%" />
<meta name="title" content="%%%title%%%" />
<meta name="description" content="%%%description%%%" />
<meta name="keywords" content="%%%!keywords%%%" />
<meta name="author" content="%%%author%%%" />
/* Einige selbstdefinierte Meta-Einträge werden von PHP-Scripten ausgewertet */
<meta name="rang" content="%%%!rang%%%" />
<meta name="menu" content="%%%!menu%%%" />
<meta name="summary" content="%%%!summary%%%" />
<meta name="published" content="%%%!published%%%" />
<meta name="modified" content="%%%!modified%%%" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta http-equiv=“expires“ content="14400" />
/* Steuerung der Verknüpfungsdarstellung bei „X“ & Co. */
<meta property="og:site_name" content="%%%rooturl%%%" />
<meta property="og:url" content="<?php echo $base ?>/%%%filewithoutext%%%" />
<meta property="og:locale" content="de_DE" />
<meta property="og:type" content="website" />
<meta property="og:title" content="%%%title%%%" />
<meta property="og:description" content="%%%description%%%" />
<meta property="og:image" content="<?php echo $base ?>%%%!image%%%" />
<meta property="og:image:alt" content="%%%!imagealt" />
<meta name="twitter:card" content="summary%%%twitter-grosses-bild%%%" />
<link rel="stylesheet" type="text/css" media="all" href="/res/nav.css" />
/* Die Verwendung von „$base“ ermölgicht das lokale Testen (http) und die Online-Nutzung (https). */
<?php 
echo '<link rel="icon" type="image/png" href="' . $base .'/res/icon.png" />'.PHP_EOL; 
echo '<link rel="canonical" href="' . $base .'$$$ choice canonical : %%%filewithoutext%%% | %%%canonical%%%  $$$" />'.PHP_EOL; 
­?­>
</head>
<body>
<main>
/* mit „data-*“ wird das bewegliche Seitenmenü gesteuert */
<input data-function="swipe" <?php echo $nav; ?> id="swipe" type="checkbox" accesskey="m">
<label data-function="swipe" for="swipe"></label>
<content>
<?php
/* Die Kopfzeile ist in eine Datei ausgelagert, das aktualisiert bei Änderungen alle Seiten */
include ($_SERVER["DOCUMENT_ROOT"] . "/res/a-top.php");  
/* Steuerung eines optionalen Untermenüs auf der Seite */
echo ((isset($navblock)>'') ? $navblock : '') ;
­?­>
<article>
/* Wahlweise der „normale“ oder der Ersatztitel, das was verwendet wird, ist auch Anker*/
<H1>$$$ choice +hdr : %%%title%%% | %%%ersatztitel%%% $$$</H1>
<div class="meta">
<?php
/* Darstellung der Informationszeile, abhängig von vorhandenen Yaml-Einträgen */
$datum = '';
$datum = '<span>Erstellt am '. date_format(date_create('%%%!published%%%'),'d.m.Y') .' </span>';
$datum .= '<span>Aktualisiert am ' . date_format(date_create('%%%!modified%%%'),'d.m.Y').' </span>';
$datum .= '<span>Lesedauer %%%!Lesezeit%%% Min.</span>';
echo $datum;
­?­>
</div>
/* Hier wird das übersetzte Markdown eingefügt */
%%%content%%%
</article>
<?php 
/* Steuerung eines optionalen Untermenüs auf der Seite */
echo (isset($navblock)>'') ? $navblock : '';
­?­>
<?php
/* Die Fußzeile ist ebenfalls ausgelagert */
include($_SERVER["DOCUMENT_ROOT"] . "/res/a-foot.php");
­?­>
</content>
/* Erst hier wird das Seitenmenü eingebunden */
<div class="sidebar"><nav class="menu" role="navigation">
<?php
include ($_SERVER["DOCUMENT_ROOT"] . "/res/a-toc.php");  
­?­>
</nav></div>
</main>
/* Falls ein Javascript durch PHP-Aktionen eingebunden werden muss, kann das hier erfolgen */
<?php 
if (isset($fusszeile)) {
	echo $fusszeile . PHP_EOL;
}
­?­>
</body>
</html>

Erläuterung

  1. Mit diesem Layout werden PHP-Seiten erzeugt.
  2. PHP ermöglicht das komfortable Auslagern des Kopf- und Fußbereichs. Das spart einerseits Platz auf dem Server, wenn es kein Bestandteil jeder Seite ist, andererseits könnte damit auf jeder Seite sehr schnell z.B. ein Weihnachtsgruß oder eine neue Kontakt-Email eingefügt werden.
  3. Mit PHP lässt sich bequem das Dilemma der verschiedenen Protokolle in der aktiven Umgebung (http - kein Zertifikat) und dem Server (https - Webseiten-Zertifikat vorhanden) lösen.
  4. In die Seitenstruktur wird mit %%%content%%% das Ergebnis der Markdown-Übersetzung eingefügt. Dort können sowohl Yaml-Variablen als auch Funktionen enthalten sein, die im weiteren Verlauf behandelt werden, als würden sie direkt in der Layout-Datei stehen.
  5. Mit Yaml-Variablen lässt sich steuern,
    1. ob PHP-Scripte geladen werden (s. „!submenu“),
    2. ob Meta-Einträge im Kopf erscheinen (z.B. „!summary“),
    3. welchen Inhalt eine Überschrift hat (Funktion „choice“ mit „title“ oder „ersatztitel“)
    4. welchen Inhalt eine PHP-Variable bekommt, bevor sie ausgewertet wird ($datum → „!published“, „!modified“, „!lesezeit“)
Kopf und Fußzeilen mit der Funktion „datei“ einbetten?

Das funktioniert. Doch wo ist der Vorteil? Die Seiten müssten trotzdem alle neu generiert werden. Das direkte Einbetten von Kopf- und Fußbereich dürfte dagegen einfacher und übersichtlicher sein.

Es findet keine Kontrolle statt, ob eine syntaktisch korrekter, ordnungsgemäß funktionierender Code in die Zieldatei geschrieben wird.

Kontrolle bitte!

Werden „reine“ HTML-Seiten erzeugt, ist die Kontrolle sehr einfach: Exportieren, im Browser anschauen.

Bei Seiten, die – wie hier im Beispiel – mit PHP-Script vervollständigt werden, ist eine lokale Umgebung zum testen unerlässlich. Sie wirft (mehr oder weniger hilfreiche) Fehlermeldungen aus, während Server „draußen“ die Anzeige verweigern und aus Sicherheitsgründen keine detaillierten Auskünfte geben.

Grundsätzlich sollten immer mehrere Seiten überprüft werden, wenn das Layout oder andere, wiederholt verwendete Elemente (z.B. Module) geändert wurden.

Stylesheets

Das Layout liefert die Struktur, Stylesheets machen es „schick“. Für einige Markdown-Elemente werden von  OSE  fest vorgegebene Klassen erzeugt, die gezieltes Gestalten von Elementen ermöglichen. Wenn das gewollt ist, können diese Klassen in den eigenen Stilvorlagen mit Leben gefüllt werden.

Fußnoten

Fußnoten bestehen aus drei Elementen:

Fußnoten im Text↗1 haben
  • die Klasse fnl
    • die ID fnh + fortlaufende Nummer
    • die Referenz fnz + fortlaufende Nummer
Der Fußnotenbereich
  • ist mit der Klasse fnb eingeschlossenen
  • Jede Fußnote
    • … hat den ID fx + laufende Nummer
      • … steht in einem Absatz der Klasse fni
      • … hat die vorangestellte Nummer, eingefasst in die Klasse fnh
  • hat am Ende eine leere Rücksprungmarke mit
    • der Klasse fnz
    • der ID fnz + laufende Nummer
    • die Rückspungmarke fnh + laufende Nummer

Mehrsprachige Fußnotentitel

Generierte Fußnoten haben weder in der Referenz noch im Rücksprung eine Title-Eigenschaft im HTML-Code. Das ist dem Umstand geschuldet, dass  OSE  beim Erzeugen des HTML-Codes keine Kenntnis davon hat, welche Sprache die spätere Seite hat.

Mit dem lang-Parameter und CSS kann ein Titel „simuliert“ werden, der – soweit dem Autor bekannt – von Braille- und Lesehilfen für Blinde erkannt und angesagt wird. Die nachfolgenden Definitionen formatieren Fußnoten mit deutschen und englischen „Titeln“, abhängig von der im erzeugten Dateikopf eingestellten Sprache. Das kann um weitere Sprachen im Stylesheet erweitert, das Beispiel den eigenen Vorstellungen angepasst werden.

/* Fußnoten */
.fnb{margin:2em;font-size:0.8em;line-height:auto;border-top:1px solid var(--txtcol);position:relativ}
.fni{text-indent:-2em;margin-left:2em}
.fnl,.fnh{font-size:0.8em;line-height:1em;vertical-align:0.3em;}
.fnl{padding-top:2em;margin-top:-2em}
.fnh{display:inline-block;text-align:right;width:1.5rem;padding-right:0.5rem}
.fnz{padding:0 0.5em;}
.fnl:after{content:"⤦";color:red;}
.fnz:before{content:"⤣";color:red;}
.fnz:hover:after, .fnl:hover:before{color:var(--capcol);display:block;position:absolute;z-index:1;border:1px solid var(--capcol);background-color:var(--bginv);padding:0.2em;margin:0}
 
html[lang="de"] .fnz:hover:after{content:"→\a0Textnote";width:10ch;top:-1.5em;text-indent:0em}
html[lang="de"] .fnl:hover:before{content:"→\a0Fussnote";width:10ch;top:0.5em;}
html[lang="en"] .fnz:hover:after{content:"→\a0Textnote";width:10ch;top:-1.5em;text-indent:0em}
html[lang="en"] .fnl:hover:before{content:"→\a0Footnote";width:10ch;top:0.5em;}

Die Rücksprungmarke (fnl) hält etwas Abstand zum oberen Viewport-Rand. Das ist Geschmackssache.

Für Verknüpfungen gibt es in Markdown die Schreibweise für Referenzen und Hyperlinks.  OSE  unterscheidet über die Schreibweise, ob es eine „interne“ oder „externe“ Verknüpfung ist:

SchreibweiseInterpretation
Hyperlink:
[Verlinkter Text](Verknüpfung) 		„interner“ Link
Referenz:
[Verlinkter Text][Referenz]
{„irgendwo“ im Dokument:}
[Referenz]: Verknüpfung 		„externer“ Link

„Externe“ Referenzen erhalten

  • das target=_blank
  • die Klasse rrl, damit diese Links als „Seite in neuem Tab/anderem Fenster“ markiert werden können.

Siehe dazu auch Einfügen → Hyperlink

1Eine Musterfußnote – zum Besichtigen mit den Browser-Funktionen.

Der Yaml-Header « ◉ » Markdown