Dokumentationsplattform (diese Seite)

Das Seitenlayout kann pro Bereich konfiguriert werden. Dieses bestimmt das Verhalten und die Darstellung der eingebundenen Inhalte und Unterbereiche. Konfigurierbar ist das Layout über das Konfigurationselement, dass sich in einem Bereich befindet:

<urn:Bereich xmlns:urn="urn:xoev-de:kosit:docs-plattform:informationsmodell">
    <urn:name>XÖV-Dokumentationsplattform</urn:name>
    <urn:pfad>/</urn:pfad>

    <!-- ... weitere Seiteninhalte ... -->

    <urn:konfiguration>
        <!-- Mögliche Werte für "layout" sind "homepage" und "standard" -->
        <urn:layout>homepage</urn:layout>
    </urn:konfiguration>
</urn:Bereich>

Mögliche Werte für das Layout sind homepage und standard, wobei eine Zukünftige Erweiterung der Optionen denkbar ist. homepage zeichnet das Layout der Homepage aus in dem z.B. Bereichsverlinkungen mit Kacheln möglich sind oder AsciiDoc Fragmente. Dieses Layout sollte nur ein mal vergeben sein. Alle anderen Bereiche sollten den Wert standard haben. Im Standard Layout umfassen Inhalte die gesamte Seite.

1. Homepage

homepage zeichnet das Layout der Homepage aus in dem z.B. Bereichsverlinkungen mit Kacheln möglich sind oder AsciiDoc Fragmente. Dieses Layout sollte nur ein mal vergeben sein.

1.1. Merkmale

  1. Spezifische Einrichtung für die Homepage der Dokumentationsplattform.

  2. Unterstützt AsciiDoc-Inhalte um Seitenfragmente zu erstellen

  3. Stellt Links in Unterbereiche in ansprechender Kachelform dar

  4. Enthält die Inhalte für statische Footer-Links wie Impressum

1.2. Fragmente

Fragmente sind AsciiDoc-Inhalte, die auf der Homepage vor oder nach den Kacheln dargestellt werden. Durch Unterbereiche können sie weiter strukturiert werden.

Es gelten folgende Regeln:

  1. Die Inhalte sind in einen Unterbereich gekapselt

  2. Dieser Unterbereich definierten einen div für die Inhalte

  3. Im Unterbereich dürfen NUR Asciidoc-Inhalte oder weitere Unterbereiche enthalten sein

  4. Enthält der Unterbereich mehr als einen Asciidoc-Inhalt, werden diese standardmäig in Spalten nebeneinander dargestellt

  5. Die Laufrichtung kann mittels eines Attributs layoutDirection konfiguriert werden, sodass Inhalte auch untereinander dargestellt werden können; mögliche Werte sind "COLUMN" und "ROW", wobei "ROW" der Standardwert ist

<!-- Ein Absatz über die ganze Seitenbreite mit adoc-Inhalte -->
<urn:unterbereich>
    <urn:name>Head</urn:name>
    <urn:adoc>
        <urn:name>someHead</urn:name>
        <urn:pfad>homepage/head.adoc</urn:pfad>
    </urn:adoc>
</urn:unterbereich>
<!-- Ein Absatz mit zwei Spalten -->
<urn:unterbereich>
    <urn:name>zwei_spalten</urn:name>
    <!--
        Dieser absatz enthält zwei Adoc dokumente, die untereinander angezeigt werden.
        Die Laufrichtung kann über das Attribut "layoutDirection" bestimmt werden.
        Mögliche Werte sind "COLUMN" und "ROW"
    -->
    <urn:unterbereich>
        <urn:name>zwei_inhalte_vertikal</urn:name>
        <urn:attribut name="layoutDirection" wert="COLUMN"/>
        <urn:adoc>
            <urn:name>adoc_links</urn:name>
            <urn:pfad>homepage/head_2_links.adoc</urn:pfad>
        </urn:adoc>
        <urn:adoc>
            <urn:name>adoc_links_2</urn:name>
            <urn:pfad>homepage/head_2_links_2.adoc</urn:pfad>
        </urn:adoc>
    </urn:unterbereich>
    <urn:adoc>
        <urn:name>adoc_rechts</urn:name>
        <urn:pfad>homepage/head_2_rechts.adoc</urn:pfad>
    </urn:adoc>
</urn:unterbereich>

1.3. Bereichsverlinkungen (Kacheln)

In der Homepage können Kacheln für die Definition der Bereichsverlinkungen definiert werden. Hierfür gelten folgende Regeln:

  1. Alle Definition sind unterhalb des Unterbereichs "GRUPPEN" definierten werden

  2. Auf der ersten Ebene darunter findet sich für jede Gruppe ein weiterer Unterbereich

  3. Im Gruppen-Unterbereich befinden sich Link-Inhalte, die auf die jeweiligen Bereich verweisen

  4. Die Teaser-Texte können in den Links über ein dynamisches Attribut konfiguriert werden:

<link>
    <name>Codelisten</name>
    <!-- Das optionale Attribut "teaser" wird verwendet um einer Kachel eine kurzbeschreibung hinzuzufügen -->
    <attribut name="teaser" wert="lorem ipsum" />
    <target>/codelisten-bereich</target>
</link>
<!-- Definition der Kacheln auf der Homepage -->
<urn:unterbereich>
    <!-- Durch den reservierten Namen "GRUPPEN" wird der Unterbereich als Kachellayout erkannt -->
    <urn:name>GRUPPEN</urn:name>

    <!-- Die folgenden Unterbereiche sind die einzelnen Kachelgruppen. Der Name bestimmt die Bereichsüberschrift -->
    <urn:unterbereich>
        <urn:name>Bausteine</urn:name>
        <!-- Die Links werden als Kacheln dargestellt -->
        <urn:link>
            <urn:name>XÖV-Bibliothek</urn:name>
            <urn:target>bibliothek</urn:target>
        </urn:link>
        <urn:link>
            <urn:name>XÖV-Codelisten</urn:name>
            <urn:attribut name="teaser" wert="Lorem ipsum dolor sit amet..." />
            <urn:target>xoevcodelisten</urn:target>
        </urn:link>
    </urn:unterbereich>

    <!-- Es können beliebig viele Bereiche mit beliebig vielen Kacheln definiert werden -->
    <urn:unterbereich>
        <urn:name>Modellierung und Betrieb </urn:name>
        <urn:link>
            <urn:name>XÖV-Profil</urn:name>
            <urn:target>xoev-profil</urn:target>
        </urn:link>
        <urn:link>
            <urn:name>Starterpaket</urn:name>
            <urn:target>starterpaket</urn:target>
        </urn:link>
        <urn:link>
            <urn:name>XGenerator</urn:name>
            <urn:target>xgenerator</urn:target>
        </urn:link>
    <urn:unterbereich>
<urn:unterbereich>

1.4. Footer

TODO

2. Standard

Im gegensatz zum Homepage Layout umfassen Inhalte im Standard Layout die gesamte Seite. Auf Standard Seiten können AsciiDoc Dokumente und OpenAPI Definitionen angezeigt werden.

2.1. AsciiDoc Dokumente

AsciiDoc Dokumente können im Standard Layout nicht als Fragmente eingebunden werden, sondern nehmen die ganze Seitenbreite und -höhe ein. Falls ein TOC konfiguriert ist wird dieses ebenfalls in dynamischer Variante am rechten Seitenrand dargestellt. AsciiDoc Dokumente können in der inhalte.xml mit dem adoc Element definiert werden:

<urn:adoc>
    <urn:name>Einführung</urn:name>
    <urn:pfad>einführung.adoc</urn:pfad>
</urn:adoc>

2.2. OpenAPI Definitionen

OpenAPI Definitionen können über ein openapi Element eingebunden werden:

<urn:openapi>
    <urn:name>Public API</urn:name>
    <urn:pfad>api/openapi_PublicServices.json</urn:pfad>
</urn:openapi>