YAML-Integration

YAML ist ein von Dirk Jesse entwickeltes Framework für moderne, flexible, browserfeste und mehrspaltige Layouts mit einem hohen Anspruch an Zugänglichkeit für die Nutzer (siehe www.yaml.de). Die Unterstützung von YAML durch conceptcms besteht im Wesentlichen in folgenden Funktionen:

  1. YAML wird von uns in einem mit conceptcms kompatiblen Format in der kostenfreien Open Source Version zum Download und zur Installation bereitgestellt.
  2. Nach Import des Frameworks sind alle YAML-CSS unter einer Gruppe "YAML" (für den "Core") und "MyYaml" (für die zu modifizierenden CSS) zusammengefasst.
  3. Die durch YAML vorgegebenen Pfade (Import von CSS, Pfade zu JavaScript und Bildern) funktionieren in conceptcms (sie werden beim Speichern automatisch umgeschrieben).
  4. Benötigte Bilder und JavaScript werden automatisch bereitgestellt; auch hier werden beim Speichern die Pfade automatisch umgeschrieben.

 

Hinweis: YAML unterliegt der Creative Commons Attribution 2.0 Lizenz (CC-A 2.0) Open Source Lizenz. Für die kostenfreie Nutzung des YAML-Frameworks die Rückverlinkung zur YAML-Homepage (http://www.yaml.de) in der Fußzeile der Website oder im Impressum vorgeschrieben. Alternativ kann eine Lizenz erworben werden. Bitte beachten Sie die Lizenzbedingungen (siehe /www.yaml.de/de/lizenz/lizenzbedingungen.html).

YAML installieren

Zuerst laden Sie unter www.conceptcms.com die entsprechende YAML-Version herunter. Wir bieten "YAML Only" (nur die CSS-Dateien) oder "YAML mit Beispiel/en" (CSS und Beispielimplementierung mit conceptcms-Vorlagen) an.

Die Installation in conceptcms erfolgt über den Website/Kunden-Import (siehe Website-Import). Tatsächlich handelt es sich bei unserer YAML-Version für conceptcms um eine bis auf die CSS (und gegebenenfalls die Beispiel-Vorlagen) leere Website.

Die Installation ist auch in bestehenden Kunden/Websites problemlos möglich. Bestehende CSS oder Vorlagen werden nicht modifiziert, sondern YAML wird nur zusätzlich installiert.

Nach der Installation erscheinen in der Stylesheet-Liste (siehe Stylesheets verwalten / Stylesheet-Liste) die beiden Gruppen "YAML" und "MyYaml" sowie die beiden CSS "master.css" und "master_ie_patches.css". Sollten diese beiden CSS schon vorher existiert haben, existieren sie nun doppelt und sollten konsolidiert werden.

Sie können jederzeit später eine kommerzielleLizenz unter shop.yaml.de erwerben und so die nach Lizenzbedingungen zwingende Rückverlinkung auf YAML vermeiden.

YAML verwenden

Grundsätzlich bleibt es jedem Benutzer überlassen, wie er YAML einsetzen möchte. Aus Sicht von conceptcms sind vor allem die im folgenden beschriebenen Vorgehensweisen von Bedeutung.

Generell sollte bei der Arbeit mit YAML darauf geachtet werden, niemals den Core zu modifizieren, sondern jede Modifikation durch ein modifizierendes CSS vornzunehmen (für jede Modifikation die Kaskade/Vererbung nutzen). Mehr Informationen finden Sie unter www.yaml.de.

Import der YAML-Einstiegs-CSS in das/die Master-CSS

Es sollte in conceptcms aus verschiedenen Gründen immer ein sog. Master-CSS (master.css) geben (siehe Master-Stylesheet / Standard-Stylesheet / IE Hacks). Zusätzlich sollte es ein weiteres Master-CSS für Browserpatches geben (master_ie_patches.css). Diese beiden CSS sind selbst keine YAML-CSS, sondern sie sind elementarer Bestandteil von conceptcms und sollen verwendet werden, um das jeweilige "Einstiegs"-CSS von YAML zu importieren. In der Regel sollte es sich dabei um die folgenden YAML-CSS  handeln:

  • master.css importiert das YAML-CSS my_layout.css
  • master_ie_patches.css importiert das YAML-CSS patch_my_layout.css

Der Import muss mit dem echten Dateinamen in conceptcms stattfinden (ein Umschreiben des Namen/Pfades ist hier nicht möglich):

  • @import url(./ID_usr_style.css); wobei ID die jeweilige ID des betreffenden YAML-CSS in conceptcms ist (diese ID ist nicht fix; sie wird in der CSS-Liste bei dem jeweiligen CSS angezeigt)
Da bei einem kompletten Import von YAML die beiden CSS master.css und master_ie_patches.css bereits mitgeliefert werden, erübrigt sich hier das beschriebene Vorgehen, der Import erfolgt schon unter Berücksichtigung der korrekten ID. Das beschriebene Vorgehen ist dann relevant, wenn YAML in eine bestende Website importiert gibt, wo es bereits ein anderes Master-CSS gibt. In dieses müssen dann die YAML-Einstiegs-CSS eingebunden werden, bzw. das existierende und das mit YAML angelegte Master-CSS sollten konsolidiert werden. Dies gilt ebenso für das Master-CSS für Browserpatches.

Kaskade bei individuellen Erweiterungen adequat einsetzen

Wird YAML außerhalb von conceptcms eingesetzt, so können eigentlich alle individuellen Änderungen/Erweiterungen für das eigene Layout direkt in die dafür vorgesehenen CSS-Dateien geschrieben werden (z.B. in basemod.css und content.css) - solange der eigentliche Core niemals verändert wird. Dies ist, insbesondere bei nicht sehr komplexen Websites, die überwiegend direkt auf schon in YAML existierenden Styles basieren, natürlich auch in conceptcms möglich.

Es kann jedoch auch sinnvoll sein, eigene Styles, auch und gerade wenn sie jeweils existierende YAML-Styles überschreiben oder modifizieren sollen, immer in komplett eigene CSS-Dateien zu schreiben. Damit wird eine weitere Stufe der Kaskade eingeführt, die dazu führt, dass man noch mehr Flexibilität für den Fall erhält, dass vielleicht einmal ein individueller YAML-Style in unterschiedlichen Vorlagen mit unterschiedlichen Werten belegt werden soll.

Beispiel für das Arbeiten mit YAML für Vorlagen-Sets

Am besten lässt sich der Sinn einer Erweiterung von YAML an einem Anwendungsbeispiel verdeutlichen, mit dem Sie dann konfrontiert sein werden, wenn Sie Vorlagen-Sets in eine bestehende und mit YAML arbeitende Website importieren:

Wenn wir - in der Regel immer auch auf YAML basierende - Vorlagen-Sets (siehe Website-Export (ab Version 5.1)) bereitstellen, so werden diese komplett mit CSS geliefert. Im HTML-Code werden diese Styles verwendet, die auch zwingend erforderlich sind, damit die Vorlage überhaupt funktionieren kann. Dabei sind nun zwei mögliche Probleme zu adressieren:

  1. Die Styles sollten so geliefert werden, dass sie in beliebigen (allerdings natürlich auf YAML basierenden) Websites einfach integriert werden können, ohne in Konflikt mit bestehenden Definitionen zu geraten.
  2. Werden mehrere Vorlagen-Sets importiert (was häufiger vorkommen sollte), so muss es möglich sein, beim Einsatz der entsprechenden Vorlagen immer nur diejenigen CSS aufzurufen, die auch wirklich verwendet werden sollen (es ist durchaus denkbar, dass ein und dieselbe Klasse für verschiedene Vorlagen unterschiedliche Werte aufweisen muss, die sich ansonsten widersprechen würden).

Um diese Probleme möglichst gut zu lösen, liefern wir je Vorlagen-Set eine separate CSS-Datei (z.B. news_tpl_01.css), die zu einer eigenen Gruppe (TemplateSets) gehört. Diese kann bzw. wird Definitionen enthalten, die sich auch auf YAML-CSS beziehen. Sie muss nun so eingebunden werden, dass sie dem Zweck entsprechend funktioniert.

Dafür gibt es zwei Optionen:

  1. Nach der grundsätzlichen Logik einer YAML-basierten Website sollte diese Datei in das YAML Einstiegs-CSS (my_layout.css) eingebunden werden. Dies ist das normale Vorgehen.
  2. Das CSS kann auch direkt in master.css importiert werden, wobei dies dann nicht mehr der eigentlichen Logik von YAML entspricht.

Beispielhaft könnte dies (Variante 1) wie folgt aussehen:

/* import core styles | Basis-Stylesheets einbinden */
@import url(./48_usr_style.css);


/* import screen layout | Screen-Layout einbinden */ 

/* basemod.css */
@import url(./55_usr_style.css);

/* content.css */
@import url(./56_usr_style.css);

/* forms.css */
@import url(./61_usr_style.css);

/* nav_shinybuttons.css */
@import url(./50_usr_style.css);
/* nav_shinybuttons.css customized*/

/* nav_slidingdoor.css */
@import url(./51_usr_style.css);
/* nav_slidingdoor.css customized*/
 
/* nav_vlist.css */
@import url(./52_usr_style.css);
/* nav_vlist.css customized*/


/* import conceptcms template set CSS | conceptcms Vorlagen CSS einbinden */
/*this is the file name of news_tpl_01.css (in this example)*/
@import url(./12_usr_style.css);
 

So profitieren wir von der Kaskade (wir modifizieren kein existierenendes YAML-CSS, können aber auf Definitionen aus YAML Bezug nehmen), und alle komplett individuellen Defintionen sowie alle Modifikationen sind separat definiert - und können damit jederzeit über CSS-Ausnahmen in der Menüpunktvorlage gesteuert werden (siehe Manuell modifiziertes Stylesheet-Handling).

Würden wir dagegen unsere eigenen Styles und die Modifikationen direkt in einem zu YAML gehörenden CSS liefern, so liessen sich diese Styles weder an- noch ausschalten, ohne die bestehde Website zu beeinflussen, und außerdem müsste der Benutzer unsere Modifikationen in "seine" Dateien schreiben (er müsste diese quasi abgleichen uns konsolidieren) und würde damit "seine" und "fremde" Definitionen vermischen.

Hinweis: Generell - und unabhängig von YAML - sollten nur diejenigen Styles direkt in master.css bzw. master_ie_patches.css geschrieben werden, die dort stehen müssen, um in CE verfügbar zu sein (siehe Stylesheet Konventionen im Master-Stylesheet; und selbst in diesem Fall sollte man die Klassen selbst nicht in master.css definieren, sondern nur leer aufrufen). Alle anderen Styledefinitionen gehören aus Transparenzgründen in ein eigenes CSS; und außerdem kann man nur so nach Bedarf in Menüpunktvorlagen über die CSS-Ausnahmen steuern (siehe Manuell modifiziertes Stylesheet-Handling).

Pfade und Namen in YAML - automatische Anpassung

conceptcms schreibt alle in originalen YAML-CSS-Dateien enthaltene Original-Pfade und Namen (Import von CSS, Pfade zu JavaScript, Pfade zu Bildern) beim Speichern automatisch in Namen/Pfade um, die der Logik von conceptcms entsprechen. Dies funktioniert beliebig oft, d..h. immer, wenn eine YAML-Pfad geschrieben wird, wird er automatisch wieder umgewandelt.

Aus

@import url(../yaml/navigation/nav_shinybuttons.css);

wird z.B.

@import url(./ID_usr_style.css);

(wobei die ID jeweils spezifisch für die jeweilige Installation bzw. den jeweiligen Kunden ist).

Oder aus

url("images/shiny_buttons/background.png")

wird z.B.

url(../../external/yaml/v_3.1/yaml/navigation/images/shiny_buttons/background.png)

In gespeicherten CSS-Dateien stehen also niemals YAML-Pfade und Namen, sondern immer nur die Pfade/Namen von conceptcms.

Wichtiger Hinweis: Die Funktionalität des automatischen Erkennens und Überschreibens von YAML-Pfaden bzw. Namen funktioniert nur, wenn exakt die aus YAML vorgegebenen Namen/Pfade verwendet werden. Wird der Name irgendeines bei der YAML-Installation mitgelieferten CSS geändert, oder wird irgendein Pfad z.B. in Code, der aus dem YAML-Builder gewonnen wurde, geändert, funktioniert dieser Mechanismus gegebenenfalls nicht mehr.
Wir empfehlen generell nach dem Kopieren zu überprüfen, ob das Überschreiben korrekt funktioniert hat und gegebenefalls eine manuelle Korrektur vorzunehmen. Für einem kompletten YAML-Import ist dies in der Regel nicht relevant.

YAML Builder verwenden

Aufgrund der automatischen Umschreibung von Pfaden in conceptcms-kompatible Pfade/Namen (s.o.) kann jederzeit auch der YAML-Builder (siehe builder.yaml.de) verwendet werden, um Code für die folgenden YAML-CSS zu erzeugen:

  • my_layout.css
  • patch_my_layout.css
  • basemod.css

Der Code kann einfach aus dem YAML-Builder kopiert werden und in die entsprechenden CSS eingefügt werden. Die im Code enthaltenen, YAML-spezifischen Pfade werden beim Speichern der Datei automatisch auf conceptcms-Pfade und Namen umgeschrieben. Der vom YAML-Builder bereitsgestellte HTML-Code kann gegebenenfalls als Grundlage für die Erstellung von Menüpunktvorlagen und Dokumentenvorlagen verwendet werden.

Bei der Verwendung des YAML-Builders sollte allerdings darauf geachtet werden, dass nicht etwa schon individueller Code in die betroffenen CSS geschrieben wurde, der dann durch den aus dem Builder kopierten Code überschrieben würde. Außerdem sollte geprüft werden, ob das Umschreiben des Pfade korrekt funktioniert hat.

YAML updaten

Es gibt keinen vom conceptcms unterstützten automatisierten Prozess zum Update von YAML, da a priori nicht feststeht, ob ein solches Update überhaupt kompatibel mit der auf YAML aufbauenden Website wäre. Ein Update kann aber natürlich manuell durch entsprechende Änderung in den existierenden Dateien erfolgen. Dies wäre dann auch der einzige Fall, wo eine Änderung im Core zulässig ist.

Es sollte auf jeden Fall vermieden werden, YAML in einen Kunden in conceptcms zu importieren, der bereits YAML importiert hat. Dies gilt auch z.B. für Website-Vorlagen, die YAML enthalten. Wird YAML doppelt importiert, so werden zwar keine Daten überschrieben, aber alle Dateien existieren dann doppelt. Das automatisierte Umschreiben von Pfaden/Namen funktioniert dann nicht mehr, und der Benutzer dürfte Probleme haben, einfach zu identifizieren, welche Dateien eigentlich verwendet werden.

YAML Versionen

Wir versuchen, die jeweils aktuellste YAML-Version immer so schnell wie möglich für conceptcms azupassen und unter www.conceptcms.com zum Download anzubieten. Es gibt allerdings auch für jede YAML-Version gegebebenfalls einige Änderungen an conceptcms: wir müssen neue Verzeichnisse für die Version erstellen und z.B. den automatischen Prozess zum Umschreiben von Pfaden etc. anpassen, wenn z.B. neue Dateien hinzukommen. In der Zwischenzeit können Sie den neuesten YAML-Download durchaus schon benutzen, aber vielleicht funktionieren einige Kleinigkeiten nicht wie gewünscht. Erst mit dem nächsten geplanten conceptcms-Release passt dann alles wieder zusammen.

Um zu wissen, welche YAML-Version Ihre aktuelle conceptcms-Version voll unterstützt, suchen Sie in Ihrer Installation nach dem Verzeichnis

../../external/yaml/

Das folgende Unterverzeichnis gibt die Version an (Schema: /v_3.1/). Sofern Sie sich gut genug auskennen, könnten Sie die neue Struktur auch - auf Basis der alten - manuell den Verzeichnissen hinzufügen. Das automatisierte Umschreiben der Pfade funktioniert dann aber immer noch nicht, wobei dies ja auch manuell geschehen kann.

Jede conceptcms-Version unterstützt nur jeweils eine YAML-Version in bezug auf das automatische Erkennen und Umschreiben von Pfaden etc. Ist also conceptcms einmal (intern) auf eine bestimmte YAML-Version aktualisiert, so erfolgt das Umschreiben immer für diese Version. Das hat jedoch keinerlei Einfluss auf Ihre existierende Implementierung, denn für diese hat das Umschreiben längst stattgefunden und auch die Strukturen älterer YAML-Versionen bleiben in conceptcms erhalten und funktionieren weiter.  Nur wenn Sie nun z.B. aus dem YAML-Builder Code in ein existierendes YAML-CSS kopieren würden, würde beim Speichern auf die neue Struktur umgeschrieben (was sogar erwünscht sein könnte und natürlich manuell wieder korrigiert werden kann).