Schnipsel

An vielen Stellen in den FirstSpirit-Clients kann die Darstellung von Objekten,

• Seiten
• Absätze
• Datensätze
• Medien
• ...

beeinflusst werden, und zwar beispielsweise in

• Suchergebnislisten
• Reports
• Auswahldialogen
• ...

Welche Inhalte eines FirstSpirit-Objekts wie verwendet werden, kann über das Register „Schnipsel“ definiert werden.
Dazu stehen folgende Felder zur Verfügung:

• Miniaturansicht
  Auswahl eines repräsentativen Bildes für den betreffenden Objekt-Typ
  Siehe dazu Seite Miniaturansicht.
• Kennsatz
  Auswahl eines repräsentativen Texts für einen Titel des betreffenden Objekt-Typs
  Siehe dazu Seite Kennsatz.
• Ausriss
  Auswahl eines repräsentativen Texts für einen Textausschnitt des betreffenden Objekt-Typs
  Siehe dazu Seite Ausriss.

Ziel ist es, Inhalte zu definieren, die das jeweilige Objekt möglichst treffend widerspiegeln (quasi als „Teaser“). Auf diese Weise soll der Redakteur eine klare Vorstellung vom Inhalt des Objekts erhalten, um so beispielsweise im Fall von Suchen den relevantesten Treffer besser ausmachen zu können und schneller zum gesuchten Objekt zu gelangen.

Darstellung im SiteArchitect:

Darstellung im ContentCreator:

Darstellung im FragmentCreator:
Wird für Projekte, die per FirstSpirit FragmentCreator bearbeitet werden sollen, keine Schnipseldefinition für die betreffenden Seitenvorlage/n vorgenommen, werden beispielsweise in der Fragment-Liste (zentrales Navigationsbedienelement im FragmentCreator) standardmäßig technische Informationen angezeigt: die ID der jeweiligen Variante und der Ordner-Pfad.

Zugriff auf Inhalte

Grundsätzlich kann bei der Gestaltung von Schnipseln auf

• Eingabekomponenten der betreffenden Vorlage (Register „Formular“)
• in den Eingabekomponenten der Vorlage referenzierte Objekte
• Informationen von Medien

zugegriffen werden.
Die zurückgelieferten Objekt können mithilfe von speziellen Methoden manipuliert werden.

Sollen Schnipsel verwendet werden, sollte im Vorfeld überlegt werden, mit welchen Inhalten der verfügbaren Eingabekomponenten der betreffenden Vorlage sich das jeweilige FirstSpirit-Objekt (z. B. Absatz, Seite, Datensatz) am besten charakterisieren und sich von anderen Objekten bzw. Objekt-Typen unterscheiden lässt. Wichtig ist, dass der Benutzer das Objekt, das durch den Schnipsel dargestellt wird, schnell erfassen kann. Es sollte auch berücksichtigt werden, dass bei dieser Form der Darstellung strukturelle Informationen (z. B. Um welchen Objekt-Typ handelt es sich? Wo in der Hierarchie ist das Objekt angesiedelt?) in den Hintergrund treten.

Allgemeines zur Syntax

In die Felder auf dem Register „Schnipsel“ können beliebig viele Zeichen eingegeben werden. Sind mehr Zeichen vorhanden, als das Textfeld darstellen kann, erhält das Textfeld Scrollbalken.

Im Praxisfall sollte auf Ergebnisse der Logik für Kennsatz und Ausriss einer Schnipseldefinition ein XML-konformes Escaping angewendet werden, welches XML-spezifische Sonderzeichen in passende Entities umwandelt. Innerhalb der Schnipseldefinition kann auf einem String-Objekt die Methode xmlEscape() angewendet werden, welches als Rückgabewert eine XML-konforme Version des verwendeten String-Objekts liefert. Siehe Datentyp String.

Fallback

Wird keine Definition in den Feldern auf dem Register „Schnipsel“ angegeben, wird an den jeweiligen Stellen standardmäßig in der Regel der Name des Objekts und der Pfad zum Objekt dargestellt, im Falle von Verweisen wird kein Tooltip im ContentCreator (siehe Abschnitt Schnipsel in Verweisvorlagen) angezeigt. Dasselbe gilt, wenn die Eingabekomponenten, auf die die Schnipsel-Definition zugreift, vom Redakteur nicht gefüllt sind.

Schnipseldefinition

Die Schnipseldefinition erfolgt allgemein über die Angabe eines Variablennamens einer in der Vorlage definierten Eingabekomponente.

Um das zurückgelieferte Objekt manipulieren zu können, können Methoden eingesetzt werden, die mit $CMS_VALUE(...)$ verwendet werden können. Die verwendbaren Methoden sind dabei abhängig vom zurückgelieferten Objekttyp. So werden die einzelnen Einträge von Listen beispielsweise zumeist über die Methode map(String) ausgegeben (siehe dazu beispielsweise Datentyp List).

Validierung

Die Syntax von Schnipsel-Definitionen wird beim Speichern geprüft: Ist sie nicht korrekt ist, erscheint ein entsprechender Hinweis und das Speichern der Vorlage ist nicht möglich.
Beispielhafte Fehlermeldung:

Fehlerhafte Syntax im Ausriss
 ... (at line 4, column 48)

Es wird nur die generelle Syntax geprüft. Nicht geprüft hingegen wird, ob die verwendeten Variablennamen korrekt sind und ob die verwendeten Methoden und Operatoren mit dem jeweiligen Objekttyp kompatibel sind.

Leer- und Typ-Prüfungen

Leer-Prüfungen sollten immer verwendet werden, um darauf zu reagieren zu können, wenn eine Eingabekomponente vom Redakteur nicht gefüllt wird (an anderen Stellen kann es sonst auch zu Generierungsfehlern kommen)
Beispiel:

if(!cs_name.isEmpty, cs_name, "N/A")

In diesem Beispiel würde N/A ausgegeben, wenn die Eingabekomponente mit dem Variablenbezeichner cs_name nicht gefüllt ist, ansonsten wird der Wert von cs_name ausgegeben.

Speziell bei Verwendung von Eingabekomponenten, die eine Auswahl unterschiedlicher FirstSpirit-Objekttypen zulassen (z. B. FS_REFERENCE), sowie bei Zugriff in Schnipseln auf Felder von referenzierten Objekten kann darüber hinaus durch Typ-Prüfung auf Eingaben des Redakteurs flexibel reagiert werden z. B.

if(
   st_ref.get.elementType == "Page", 
       st_ref.get.displayName(#global.language),

   st_ref.get.elementType == "PageRef", 
        bold(st_ref.get.displayName(#global.language)) +
            italic(truncate(st_ref.pageRef.page.formData.pt_text.toText(false),100)),

    !st_ref.media.file(#global.language).isNull, 
        st_ref.get.displayName(#global.language) + " (" +
            st_ref.media.file(#global.language).extension.toUpperCase + ", " +
            st_ref.media.file(#global.language).size.humanReadable("kB",",000 kB") + ")",
 
    !st_ref.media.picture(#global.language).isNull, 
        st_ref.get.displayName(#global.language) + " [Picture]",
    
    "---")

In diesem Beispiel wird für eine FS_REFERENCE-Eingabekomponente (Bezeichner st_ref) geprüft, ob es sich bei der Wahl des Redakteurs um eine Seite (Inhalte-Verwaltung), Seitenreferenz (Struktur-Verwaltung), Datei oder um ein Bild (jeweils Medien-Verwaltung) handelt. Je nach Ergebnis der Prüfung wird in diesem Beispiel für

• eine Seite der Anzeigename,
• eine Seitenreferenz der Anzeigename und Text aus einem DOM-Editor mit dem Bezeichner pt_text der zugehörigen Seite aus der Inhalte-Verwaltung,
• eine Datei der Anzeigename sowie Dateityp und -größe
• ein Bild der Anzeigename und der Zusatz [Picture]

ausgegeben. Ist keiner dieser Objekttypen gewählt, wird --- ausgegeben.

Beispielhafte Ausgaben:

Startseite

Mithras-Homepage Sonnenenergie ist die Zukunft, der wir uns verschrieben haben. Mit unseren Lösungen und Produkten …

Briefvorlage (DOC, 522 kB)

Unternehmenszentrale [Picture]

• Zur if(...)-Funktion siehe auch diese Seite.
• Zu #global.language siehe auch diese Seite. Alternativ kann statt #global.language auch die verkürzte Schreibweise #language verwendet werden.

Spezifische Eingabekomponenten für Schnipsel-Informationen

Es wäre generell denkbar, dass für die Schnipsel nicht nur Eingabekomponenten genutzt werden, deren Inhalte später über die Vorlagensätze ausgegeben werden, sondern in den Formularen spezielle Eingabekomponenten definiert werden, in denen die Redakteure Schlagworte, Beschreibungstexte usw. hinterlegen können, die nur für die Ausgabe innerhalb des Projekts (also als „Schnipsel“) verwendet werden, nicht aber für die Ausgabe beispielsweise auf der Webseite.

Vorschau von Schnipseln

Eine Vorschau der Schnipselausgabe erhält man in der Integrierten Vorschau über das Register „Schnipsel“. Dazu muss auf dem Register „Eigenschaften“ eine Vorschau-Seite ausgewählt sein.

Sprachabhängige Schnipsel

Um eine bestimmte Sprache anzugeben, die für die Anzeige der Schnipsel verwendet werden soll, kann folgende Syntax verwendet werden:

#form.BEZEICHNER.SPRACHKÜRZEL

Dabei ist der Platzhalter BEZEICHNER der Variablenname der gewünschten Eingabekomponente der jeweiligen Vorlage, deren Inhalt für die Schnipselausgabe verwendet werden soll.

SPRACHKÜRZEL ist die Abkürzung der gewünschten Sprache, die im ServerManager in den Server-Eigenschaften unter „Sprach-Vorlagen“, Feld „Abkürzung“, definiert wurde. Darüber hinaus kann #master für die Projekt-Mastersprache verwendet werden (diese wird ausgewählt in den Projekt-Eigenschaften im ServerManager, Bereich „Sprachen“).

Beispiele

truncate(if(!pt_headline.isEmpty, #form.pt_headline.DE), 30)

In diesem Beispiel wird der Text der Eingabekomponente mit dem Bezeichner pt_headline in der Sprache DE auf die ersten 30 Zeichen gekürzt ausgegeben.

truncate(if(!pt_headline.isEmpty, #form.pt_headline.#master), 30)

In diesem Beispiel wird der Text der Eingabekomponente mit dem Bezeichner pt_headline in der Mastersprache des Projekts auf die ersten 30 Zeichen gekürzt ausgegeben.

Zugriff auf Metadaten

Metadaten, die direkt auf einem Element definiert wurden, können mittels

#meta.BEZEICHNER

ausgegeben werden.
Hierbei muss als BEZEICHNER der Name der gewünschten Eingabekomponenten aus den Metadaten verwendet werden, wobei die Beispiele für die Ausgabe der einzelnen Eingabekomponententypen in folgender Tabelle auch hier zutreffend sind.

Siehe dazu auch Systemobjekt #meta.

Schnipseldarstellung von Medien

Modifizierte Schnipseldarstellung für Medien (SiteArchitect und ContentCreator)

Medien werden in FirstSpirit standardmäßig mit Name des Mediums, Beschreibung bzw. Pfad und einem Vorschaubild dargestellt.
Mithilfe der Metadaten-Vorlage kann diese Darstellung modifziert werden. So können z. B. auch der Dateiname, der Dateityp und die Dateigröße angezeigt werden.
Welche Seitenvorlage eines Projekts als Metadaten-Vorlage verwendet werden soll, kann im FirstSpirit ServerManager definiert werden, unter „Projekteinstellungen / Optionen / Metadaten-Vorlage“ (siehe dazu auch Optionen (→Dokumentation für Administratoren) und Seite zu Metadaten).

Die Definition, welche Informationen eines Mediums für die Schnipseldarstellung verwendet werden sollen, erfolgt in der Metadaten-Vorlage auf dem Register „Schnipsel“. In den Feldern „Kennsatz“ und „Ausriss“ stehen dazu folgende Variablen zur Verfügung:

Beispiel

Kennsatz:

#filename + "." + #extension + if(#mediumtype == "Picture", " (" + #resolution + "px)", "")

Ausriss:

#item.displayName(#item.project.masterLanguage) + " (" + #mimetype + ")"

Gibt als Titel den Dateinamen mit Dateiendung sowie die Auflösung des jeweils gewählten Mediums, als Textausschnitt den Anzeigenamen sowie den MIME-Typ an., z. B.

electric-power-supply.jpg (849x562px)
Netzgerät (image/jpeg)

Schnipsel in Verweisvorlagen

Für die Darstellung von Tooltips im ContentCreator zu Verweisen können Schnipsel in Verweisvorlagen definiert werden. Diese Tooltips werden in CMS_INPUT_DOM- sowie CMS_INPUT_DOMTABLE-Formularen und im InEdit-Modus (siehe Abbildung) angezeigt.

Für interne Verweise auf eine über FS_REFERENCE referenzierten Seite (in den folgenden Beispielen gespeichert in lt_reference) bietet es sich z. B. an, ein Bild, eine Überschrift und eine Textpassage der Seitenreferenz für die Tooltip-Anzeige zu verwenden.

Neben FS_REFERENCE können in Verweisen aber selbstverständlich auch andere Eingabekomponenten-Typen verwendet werden. Zu deren Verwendung in Schnipseln siehe folgende Tabelle sowie Datentyp FormData.

Beispiel

Feld „Miniaturansicht“
Anzeige eines Bildes, das in der Eingabekomponente mit dem Bezeichner pt_highlightPicture der über lt_reference referenzierten Seite gespeichert ist:

if ( 
           !lt_reference.isEmpty && !lt_reference.pageRef.isEmpty && !lt_reference.pageRef.page.formData.pt_highlightPicture.isEmpty, 
           lt_reference.pageRef.page.formData.pt_highlightPicture 
       )

Dabei wird lt_reference zur Pflege und Speicherung des Verweisziels (Seitenreferenz im selben Projekt, Auswahl über FS_REFERENCE) verwendet. Bei pt_highlightPicture handelt es sich um die Variable, in der ein Bild gespeichert wird, das sich auf der Seite befindet, die zu der in lt_reference gewählten Seitenreferenz gehört.

Feld „Kennsatz“
Anzeige von Text, der in den Eingabekomponenten mit den Bezeichnern pt_headline und/oder pt_subheadline der referenzierten Seite gespeichert ist, getrennt durch einen Schrägstrich:

if (
           !lt_reference.isEmpty && !lt_reference.pageRef.isEmpty,
           if (
                   !lt_reference.pageRef.page.formData.pt_headline.isEmpty,
                   lt_reference.pageRef.page.formData.pt_headline
               ) +
           if (
                   !lt_reference.pageRef.page.formData.pt_headline.isEmpty && !lt_reference.pageRef.page.formData.pt_subheadline.isEmpty,
                   " / "
               ) + 
           if (
                   !lt_reference.pageRef.page.formData.pt_subheadline.isEmpty,
                   lt_reference.pageRef.page.formData.pt_subheadline
               )           
)

Denkbar wäre auch, für den Kennsatz den Anzeigenamen der referenzierten Seitenreferenz zu verwenden, z. B.

lt_reference.get.displayName(#language)

In diesem Beispiel wird der Anzeigename der in der Eingabekomponente mit dem Bezeichner lt_reference gespeicherten Seitenreferenz im Tooltip angezeigt.

Feld „Ausriss“
Anzeige des Textes (auf 65 Zeichen gekürzt), der in der Eingabekomponente mit dem Bezeichner pt_intro der referenzierten Seite gespeichert ist:

if (
    !lt_reference.isEmpty && !lt_reference.pageRef.isEmpty && !lt_reference.pageRef.page.formData.pt_intro.isEmpty,
    truncate(lt_reference.pageRef.page.formData.pt_intro, 65)
)

Dabei wird lt_reference wiederum zur Pflege und Speicherung des Verweisziels (Seitenreferenz im selben Projekt, Auswahl über FS_REFERENCE) verwendet. Bei pt_intro handelt es sich um die Variable, in der Fließtext in der Seite gespeichert wird, die zu der in lt_reference gewählten Seitenreferenz gehört.

Da der Redakteur meist an Informationen des Verweises auf der Vorschauseite (Verweistext, Verweisbild, Tooltip) nicht erkennen kann, ob es sich z. B. um einen internen oder externen Verweis handelt, könnte ihm diese Information per Tooltip ebenfalls geeignet eingeblendet werden.

Im SiteArchitect werden Schnipsel-Definitionen in Verweisvorlagen darüber hinaus für die Anzeige in FS_CATALOG mit Verweisen (<TEMPLATES type="link">) verwendet.

Zugriff per API

Auf Schnipsel-Definitionen kann per FirstSpirit Access-API über folgende Interfaces zugegriffen werden:

• Interface Snippet
• Interface SnippetContainer
• Interface SnippetAgent