Rendering-Dokumente schreiben

Der vollständige Sprachumfang: Werte des aktuellen Elements, Blöcke, Abfragen verwandter Elemente, Tabellen und Kürzungsfilter.

Ein Rendering-Dokument ist Markdown mit zwei Ergänzungen: Platzhaltern für Werte des aktuellen Elements und Blöcken für Inhalte, die Metapad für Sie zusammenstellt.

Das Element, um das es auf einer Seite geht, heißt durchgängig das Subjekt.

Werte des Subjekts

Verwenden Sie {{ ... }} an beliebiger Stelle im Text:

• {{ subject.label }} — der Name des Elements
• {{ subject.description }} — seine Beschreibung
• {{ subject.properties.owner }} — jede Eigenschaft, über ihren Namen
• {{ subject.auto_id }} — seine Kurz-ID, etwa SRV-12

Ein Verweis, der nicht aufgelöst werden kann, wird als nichts gerendert statt als Fehler — prüfen Sie die Schreibweise also in der Vorschau.

Blöcke

Ein Block ist eine Zeile, die mit ::: beginnt:

Block	Wirkung
:::prose{ source=subject.description }	Rendert ein Textfeld als Markdown
:::properties	Die Eigenschaften des Subjekts als Tabelle
:::view{ source=... }	Eine Liste oder Tabelle verwandter Elemente
:::metric{ source=... label="..." }	Eine einzelne Kennzahl
:::diagram{ source=... }	Eine Ansicht, in die Seite gezeichnet

Verwandte Elemente einbinden

:::view muss wissen, welche Elemente. Das definieren Sie einmal oben im Dokument in einem query_spec-Block und verweisen dann über den Namen darauf.

Um auf jeder Prozess-Seite die beteiligten Rollen zu zeigen:

{"sections":[{"name":"roles","selection":{"Relative":{"hops":[{"rel":{"relationship_type_ids":["involves"],"direction":"Outgoing"}}]}},"shape":{"Collect":{"include":{"node_properties":"All","edge_properties":"All"}}}}],"locale":"de"}

und danach an beliebiger Stelle:

:::view{ source=roles }

Verwenden Sie den exakten Namen des Beziehungstyps aus Ihrem Modell — ein Name, den es nicht gibt, trifft auf nichts zu, ohne jede Meldung. direction ist Outgoing, Incoming oder Both; mit Incoming zeigt eine Seite, was auf sie verweist.

Zwei Darstellungen

Als Tabelle, mit den Spalten Ihrer Wahl:

:::view{ source=roles columns="label, description | summary: 160, properties.owner" }

Als Liste — oder in beliebiger anderer Form — über eine Vorlage je Eintrag:

:::view{ source=roles template="- [{{ label }}](node:{{ id }}) — {{ via.involvement }}" }

In einer solchen Vorlage beziehen sich {{ label }}, {{ id }}, {{ description }} und {{ properties.x }} auf den jeweiligen Eintrag, nicht auf das Subjekt. {{ via.x }} liest eine Eigenschaft der Beziehung, die beide verbindet — dort steht üblicherweise die Art der Beteiligung oder der RACI-Buchstabe.

Eine Vorlage wird für jeden Eintrag einzeln gerendert. Eine Vorlage in Form einer Tabellenzeile ergibt deshalb keine Tabelle — dafür ist columns= da.

Eine Spalte wird nach dem letzten Teil ihres Ausdrucks benannt — aus properties.owner wird owner. Mit as bestimmen Sie die Überschrift selbst, und sie wird dadurch auch übersetzbar:

:::view{ source=roles columns="auto_id as ID, label as Name" }

Langen Text kürzen

Eine vollständige Beschreibung in einer Tabellenzelle zerstört das Layout. Schicken Sie sie durch einen Filter:

• | summary: 160 — der einleitende Absatz, geglättet und auf 160 Zeichen gekürzt (der Standardgriff)
• | first_paragraph — nur der einleitende Absatz
• | truncate: 200 — auf Länge gekürzt

Links zwischen Seiten

[{{ label }}](node:{{ id }}) verlinkt auf die Seite eines anderen Elements. In der veröffentlichten Website wird daraus ein echter Link; gehört das Element nicht zur Publikation, wird daraus reiner Text statt eines toten Links.

ID-Spalten verlinken sich selbst. In einer columns=-Tabelle müssen Sie den Link gar nicht bauen — aus einer auto_id-Spalte wird ein Link auf die Seite des jeweiligen Elements:

:::view{ source=roles columns="auto_id, label" }

Es gilt dieselbe Regel: Gehört das Element nicht zur Publikation, bleibt die ID reiner Text statt eines toten Links. Nur ID-Spalten tun das — damit der Name anklickbar wird, nehmen Sie eine Vorlage mit [{{ label }}](node:{{ id }}).

Blöcke mit eigener Überschrift

Ihr Text wird exakt so ausgegeben, wie Sie ihn schreiben — Überschriften eingeschlossen —, auch wenn der Block darunter nichts findet. Eine von Hand geschriebene ## Beteiligte Rollen erscheint dann auf jeder Seite, denn nur der Block weiß, ob er etwas gefunden hat.

Setzen Sie die Überschrift deshalb an den Block:

:::view{ source=roles heading="Beteiligte Rollen" level=2 empty="Noch keine Rollen zugeordnet." }

• heading= erscheint nur, wenn der Block etwas enthält. level= bestimmt die Überschriftenebene (2, wenn Sie nichts angeben).
• empty= ist das, was die Leser stattdessen sehen, wenn er nichts enthält. Lassen Sie empty= weg, verschwindet der Block — samt Überschrift — vollständig.

Genauso funktioniert es bei einer Beschreibung, die fehlen kann:

:::prose{ source=subject.description heading="Hintergrund" empty="Noch keine Beschreibung vorhanden." }

Bei :::prose heißt „nichts zu zeigen“, dass die Eigenschaft leer oder nicht gesetzt ist.

heading= und empty= sind gewöhnlicher Text und werden mit dem Rest der Seite übersetzt.

Beide Formate prüfen

Überschriftenebenen unterscheiden sich zwischen Website und PDF: Eine #-Überschrift ist auf der Website der Seitentitel, im PDF ordnet sie sich unter die Kapitelüberschrift ein. Wenn ein Dokument in beiden zählt, sehen Sie sich beide an.