$CMS_REF(...)$

Verwendung von $CMS_REF(...)$

FirstSpirit verwaltet unterschiedliche Objekttypen in getrennten Verwaltungsbereichen. Dieses Konzept erfüllt die Trennung von Inhalt, Struktur und Darstellung einer Website. So liegen beispielsweise alle redaktionell gepflegten Inhalte in der Inhalte-Verwaltung des Projekts, alle Medien (Bilder und Dateien) in der Medien-Verwaltung, die Struktur in der Struktur-Verwaltung und die Darstellung, also das Layout der Seiten und Inhalte, bekannterweise in der Vorlagen-Verwaltung.

Dieses Konzept wird konsequent weiterverfolgt: so werden beim Zugriff auf Objekte eines Verwaltungsbereichs aus einem anderen Verwaltungsbereich heraus lediglich Referenzen auf die Objekte angelegt. Bindet ein Redakteur beispielsweise ein Bild aus der Medien-Verwaltung über eine Eingabekomponente (FS_REFERENCE) in eine Seite der Inhalte-Verwaltung ein, wird dort lediglich eine Referenz auf das Bild gespeichert.

Analog dazu das Verhalten in der Vorlagen-Verwaltung: Damit beispielsweise ein Bild aus der Medien-Verwaltung im Browser ausgegeben werden kann, muss eine Referenz innerhalb der Vorlagen-Verwaltung zu einem Pfad aufgelöst werden, und zwar mithilfe des Tags $CMS_REF(..)$. Der Tag wird dazu im HTML-Ausgabekanal (Register HTML), im HTML-Bereich der Vorlage, in einem <img>-Tag ausgegeben. Innerhalb der Klammern wird der Name der zu referenzierenden Variable angegeben, in diesem Fall der Name der Bildeingabekomponente, z. B.

<img src="$CMS_REF(st_picture)$" alt="Alternativtext">

$CMS_REF(...)$ löst eine Referenz auf einen beliebigen Objektknoten zu einem Pfad auf, und sorgt gleichzeitig dafür, dass das referenzierte Objekt im generierten Stand des Projekts bzw. in der Vorschau vorhanden ist.

Die Anweisungen $CMS_REF(...)$ und $CMS_VALUE(...)$ sollten nicht ineinander geschachtelt verwendet werden, z. B. $CMS_REF($CMS_VALUE(...)$)$. In $CMS_REF(...)$ können, genau wie bei $CMS_VALUE(...)$ im Bezeichner (s. Syntax), auch Methodenaufrufe verwendet werden.

Syntax von $CMS_REF(...)$

Bei Verwendung von $CMS_REF(...)$ muss folgende Syntax eingehalten werden:

$CMS_REF(BEZEICHNER,
  abs:WERT,
  contentId:WERT,
  index:WERT,
  lang:"SPRACHKÜRZEL",
  language:"SPRACHKÜRZEL",
  postfix:BEZEICHNER,
  remote:"BEZEICHNER",
  res:"AUFLÖSUNG",
  resolution:"AUFLÖSUNG",
  template:"BEZEICHNER",
  templateSet:"KANALNAME",
  version:KANALNUMMER
)$

Alle Parameter bis auf den BEZEICHNER sind optional.

Innerhalb einer $CMS_REF(...)$-Anweisung können mehrere Parameter kommasepariert übergeben werden, z. B.:

$CMS_REF(pageref:"mithras", lang:"EN")$

Parameter von $CMS_REF(...)$

$CMS_REF(...)$ verfügt über folgende Parameter:

• BEZEICHNER
• abs
• contentId
• index
• lang / language
• postfix
• remote
• res / resolution
• template
• templateSet
• version

BEZEICHNER

Innerhalb von $CMS_REF(...)$ wird mit dem Bezeichner der Referenzname eines Objektes innerhalb von FirstSpirit angegeben.

Der Bezeichner besteht bei manueller Angabe der Objektes aus zwei Teilen:

1. Objekttyp
2. Referenzname des Objektes

Der Objekttyp richtet sich nach der Art eines Objektes. Es gibt folgende Objekttypen:

• Datei oder Bild aus der Medien-Verwaltung: media
• Seitenreferenz oder Dokumentengruppe aus der Struktur-Verwaltung: pageref
• Menüebene aus der Struktur-Verwaltung: pagefolder

Wenn die URL eines Bildes aus der Medien-Verwaltung mit dem Referenznamen „suedsee“ ermittelt werden soll, so ist folgender Bezeichner für $CMS_REF(...)$ anzugeben:

media:"suedsee"

Mithilfe der Angabe von pageref kann eine Verlinkung zur angegebenen Seitenreferenz erzeugt werden, z. B.

<a href="$CMS_REF(pageref:"detail")$">mehr...</a>

Handelt es sich bei der über pageref angegebene Seitenreferenz um eine Content-Projektion (Seitenreferenz, die auf einer Seite mit Datenabsatz basiert), so dass mehr als eine Seite gerendert wird, wird standardmäßig immer die Seite mit dem Datensatz mit der höchsten ID zurückgegeben. Dabei werden auch Filter und Sortierungen auf dem Register „Daten“ berücksichtigt.

Bei Verwendung von pagefolder wird standardmäßig immer die Start-Seitenreferenz verwendet, die zu oberst in der Hierarchie unterhalb des angegebenen Struktur-Ordner (Menüebene) liegt.

Alternativ können für das Objekt auch ein Variablenname oder Systemobjekte angegeben, z. B. die aktuelle Seite (mit #global.node), und Methodenaufrufe auf diese Objekte angewendet werden.

abs

Standardmäßig hängen die von $CMS_REF(...)$ ermittelten Pfade von der Projekteigenschaft Absolute Links ab. Ist diese Eigenschaft aktiviert, werden von $CMS_REF(...)$ absolute Pfadangaben (entspricht abs:1) zurückgeliefert. Ist die Eigenschaft deaktiviert, relative (entspricht abs:0).

Mit dem optionalen Parameter kann man die Projekteigenschaft für eine $CMS_REF(...)$-Angabe überschreiben. Hierbei sind folgende Angaben möglich:

Absolute Pfadangaben sind immer absolut zur Wurzel der Webanwendung. Dies ist bei der Generierung das Generierungsverzeichnis (z. B. FirstSpirit-Server/web/fs4staging/project_1234/2345).

Zur Vervollständigung der URL bei abs:1 wird die Angabe Präfix für absolute Pfade in der Auftragsverwaltung verwendet. Der angegebene Präfix (z. B. http://meinServer) wird der absoluten Pfadangabe vorangestellt.

Alternativ kann der Präfix auch in einer Vorlage angegeben werden. Hierzu muss mithilfe von $CMS_SET(...)$ der Wert des Systemobjektes #global.urlCreator.urlPrefix entsprechend gesetzt werden:

$CMS_SET(#global.urlCreator.urlPrefix,"http://meinServer")$

Dieser Präfix wird dann für alle folgenden $CMS_REF(...)$-Aufrufe verwendet.

contentId

Mit dem Parameter contentId kann die URL zum angegebenen Datensatz ermittelt werden.

Als Wert erwartet der Parameter contentId die ID eines Datensatzes.

Bei dem Objekt mit dem für $CMS_REF(...)$ angegebenen BEZEICHNER muss es sich um eine Content-Projektion (Seitenreferenz, die auf einer Seite mit Datenabsatz basiert) handeln.

Damit sich der Parameter contentId in der URL niederschlägt, muss der Wert auf dem Register „Daten“ der Content-Projektion für „Anzahl der Beiträge pro Seite“ 1 sein (d.h. auf jeder Seite wird nur ein Datensatz dargestellt).

Beispiel:

$CMS_REF(pageref:"datenquelle", contentId:374)$

Im Beispiel ist die Seitenreferenz datenquelle eine Content-Projektion. Es soll hier der Datensatz mit der ID 374 für die Ermittlung der URL berücksichtigt werden.

Beispiel für eine erzeugte URL:

/preview/1/site/DE/current/2/3/contentId=374

Mit dem Parameter template kann die Suche des Datensatzes auf eine Tabellenvorlage eingegrenzt werden.

index

Mit dem Parameter index kann die URL zu einer bestimmten Unterseite, z. B. einer Content-Projektion, ermittelt werden.

Als Wert erwartet der Parameter index die Nummer der gewünschten Unterseite. Die Zählung der Unterseiten beginnt mit 0.

Beispiel:

$CMS_REF(pageref:"datenquelle", index:3)$

Im Beispiel ist die Seitenreferenz datenquelle eine Content-Projektion. Es soll hier die durch die Projektion erzeugte 4. Unterseite (index = 3) für die Ermittlung der URL berücksichtigt werden.

Beispiel für eine erzeugte URL:

/preview/1/site/DE/current/2/3/contentId=374

lang / language

Bei der Angabe des optionalen Attributes lang bzw. language wird bei der Auflösung einer Referenz zusätzlich die angegebene Projektsprache berücksichtigt. Wird der Parameter weggelassen, so wird mit der aktuellen Sprachen (Vorschau und Generierung) aufgelöst.

Die Verwendung des Parameters ist bei sprachabhängigen Bildern und Dateien oder bei einem gewünschten Sprachwechsel sinnvoll.

Als Wert für das Attribut ist ein für das Projekt gültiges Sprachkürzel, in doppelten Hochkommata eingefasst, anzugeben (z. B. lang="DE").

$CMS_REF(media:"suedsee", lang:"EN")$

postfix

Bei themenbasierten Teilbereichen in der Struktur- bzw. Medien-Verwaltung kommt es vor, dass alle Objekte eines Teilbereiches den gleichen Suffix (z. B. _d) enthalten.

Ein Beispiel für einen themenbasierten Teilbereich ist ein Teaser-Bild, welches je nach Menüpunkt anders aussehen soll. Für diesen Einsatzzweck könnte der Referenzname für das Bild den gemeinsamen Namensbestandteil „teaser“ enthalten und für jeden Menüpunkt einen abweichenden Suffix. Weiterhin könnte es noch ein „Rückfallbild“ geben, welches den Suffix nicht enthält.

Die Referenzermittlung bei der Verwendung des optionalen Parameters postfix ist wie folgt:

1. Zunächst wird versucht, ein Objekt mit dem Referenznamen und dem angegebenen Postfix zu finden (BEZEICHNER + postfix).
2. Wurde kein Objekt gefunden, wird versucht ein Objekt ohne den angegebenen Postfix zu finden (BEZEICHNER).

Für den Parameter kann entweder ein in doppelten Hochkommata eingefasster fester Wert angegeben werden oder alternativ ein Variablenname (z. B. aus der Struktur-Verwaltung).

Beispiel:

$CMS_REF(media:"suedsee", postfix:"_A")$

In diesem Fall wird zunächst versucht, in der Medien-Verwaltung ein Bild oder eine Datei mit dem Referenznamen suedsee_A zu finden. Wird kein Bild oder keine Datei gefunden, so wird versucht, ein Bild oder eine Datei mit dem Referenznamen suedsee zu ermitteln.

Für den Suffix sollten keine numerischen Angaben (z. B. _1) gewählt werden, da es sonst zu Überschneidungen mit der automatischen Unifizierung von Referenznamen kommen kann. Wird z. B. in der Struktur-Verwaltung eine Seitenreferenz mit dem Referenzname meineReferenz angelegt und existiert bereits eine gleichlautende Seitenreferenz, so wird dem Referenzname ein Suffix in der Form _GANZZAHL angehängt.

remote

Mit dem Parameter remote können Verweise auf Remote-Projekte erzeugt werden (Informationen zur Konfiguration von Remote-Projekten bzw. Remote-Medien siehe Seite Remote-Zugriff und Dokumentation zur Funktionalität FirstSpirit Remote-Media).

Für die Verwendung des Parameters remote ist eine gültige Lizenz für den Remote-Media-Zugriff erforderlich.

Als Wert erwartet der Parameter den symbolischen Namen, der in der Konfiguration des Remote-Projekts (in den Projekt-Eigenschaften) festgelegt wurde.

Beispiel:

$CMS_REF(pageref:"seitenreferenz_test", remote:"remoteprojekt")$

In diesem Beispiel wird die Seitenreferenz mit der UID seitenreferenz_test des Remote-Projektes mit dem Symbolischen Bezeichner remoteprojekt aufgelöst.

Verweise auf Remote-Projekte werden analog zu solchen auf das aktuelle lokale Projekt ausgegeben, z. B.

<a href="$CMS_REF(lt_reference_remote)$" title="$CMS_VALUE(lt_comment)$">$CMS_VALUE(lt_text)$</a>

In diesem Beispiel wird ein Verweis zu der über die Eingabekomponente lt_reference_remote gewählten Seitenreferenz erzeugt. Handelt es sich bei der Eingabekomponente um eine mit Remote-Zugriff (z. B. FS_REFERENCE mit <PROJECTS> / <REMOTE>) und wurde eine Seitenreferenz eines Remote-Projekts vom Redakteur ausgewählt, wird diese einfach über $CMS_REF(lt_reference_remote)$ aufgelöst. (Siehe dazu auch Kapitel Verweisvorlagen.)

res / resolution

Soll bei der Auflösung der Referenz eines Bildes aus der Medien-Verwaltung eine andere Auslösung als die Originalauflösung (Auflösung mit dem Bezeichner ORIGINAL) verwendet werden, so ist der Parameter res bzw. resolution anzugeben.

Als Wert des Parameters ist eine gültige Bezeichnung einer Auflösung im Projekt, in doppelten Hochkommata eingefasst, anzugeben (z. B. SKALIERT).

$CMS_REF(media:"suedsee", res:"SKALIERT")$

Mit der Anweisung $CMS_REF(...)$ können neben Bildern aus dem gleichen Projekt („Zielprojekt“) auch Bilder aus Remote-Projekten referenziert werden. (Dazu muss das Attribut remote angegeben werden.) Bei der Referenzierung aus einem Remote-Projekt ist zu beachten, dass die Auflösungen von Remote- und Zielprojekten unterschiedlich sein können.

Wenn der Vorlagenentwickler eine Auflösung über das Attribut res bzw. resolution angibt, die im Remote-Projekt nicht vorhanden ist, so kann es beim Anfordern einer Vorschau oder bei der Generierung zu Fehlern kommen. Das Medium wird in diesem Fall in der Originalauflösung ausgegeben.

Gibt es in Remote- und Zielprojekt unterschiedliche Auflösungen mit demselben Namen (z. B. Zielprojekt: Auflösung „thumbnail“ mit Breite 10 px, Remote-Projekt: Auflösung „thumbnail“ mit Breite 50 px), werden nur die Auflösungen aus dem Projekt ausgewertet, aus dem das Medium ausgewählt wurde. Das heißt, wird ein Bild aus einer Remote-Medien-Verwaltung ausgewählt, werden nur die Auflösungen berücksichtigt, die für das Remote-Projekt konfiguriert wurden. Wird ein Bild aus der lokalen Medien-Verwaltung ausgewählt, werden die Auflösungen aus dem Zielprojekt berücksichtigt.

Beispiel:

• das Zielprojekt besitzt eine Auflösung „thumbnail“ (Breite 10 px)
• das Remote-Projekt A besitzt eine Auflösung „thumbnail“ (Breite 50 px)
• das Remote-Projekt B besitzt eine Auflösung „thumbnail“ (Breite 75 px)

Im Zielprojekt wird nun:

• ein Medium aus der lokalen Medien-Verwaltung des Zielprojekts mit der Auflösung „thumbnail“ mit einer Breite von 10 px ausgegeben,
• ein Medium aus der Remote-Medien-Verwaltung von Remote-Projekt A mit der Auflösung „thumbnail“ mit einer Breite von 50 px ausgegeben,
• ein Medium aus der Remote-Medien-Verwaltung von Remote-Projekt B mit der Auflösung „thumbnail“ mit einer Breite von 75 px ausgegeben.

Es wird daher empfohlen, bei der Verwendung von Remote-Projekten innerhalb von Vorlagen über den Parameter res bzw. resolution nur dann eine Auflösung anzugeben, wenn entweder die Auflösungen in Ziel- und Remote-Projekten identisch sind oder sichergestellt werden kann, aus welcher Medien-Verwaltung die ausgewählten Medien stammen, z. B. wenn die Auswahl zuvor über

...
 <PROJECTS>
         <REMOTE name="remoteproject">
            <SOURCES>
                 <FOLDER name="root" store="mediastore"/>
            </SOURCES>
         </REMOTE>
 </PROJECTS>
...

eingeschränkt wurde (siehe dazu z. B. FS_REFERENCE).

template

Der Parameter template stellt eine Einschränkung zum Parameter contentId dar und muss mit diesem zusammen angegeben werden. Über template wird die Suche, die über contentId ausgeführt wird, durch die Angabe der UID einer Tabellenvorlage auf diese Vorlage eingeschränkt, wenn z. B. zwei Tabellenvorlagen denselben Datensatz darstellen. Die Angabe von template ist also beispielsweise sinnvoll, um einen Datensatz in einer bestimmten Darstellung zu verlinken, z. B. in einer Detaildarstellung.

Als Wert erwartet der Parameter template die UID einer Tabellenvorlage.

Die Suche wird in diesem Fall von einem Struktur-Ordner aus gestartet (Objekttyp pagefolder). Dabei wird immer die Start-Seitenreferenz zurückgeliefert, die zu oberst in der Hierarchie unterhalb des angegebenen Struktur-Ordner (Menüebene) liegt. Damit eine Angabe von contentId eine Auswirkung hat, muss es sich bei dieser Start-Seitenreferenz um eine Content-Projektion handeln.

Soll eine andere Seitenreferenz als die Start-Seitenreferenz berücksichtigt werden, kann der Parameter template verwendet werden.
Beispiel:

$CMS_REF(pagefolder:"root", contentId:322, template:"products.product_group")$

In diesem Beispiel wird ab dem Wurzelknoten der Struktur-Verwaltung eine Seite einer Content-Projektion gesucht, die auf Basis der Tabellenvorlage products.product_group den Datensatz mit der ID 322 rendert.

templateSet

Ist in einem Projekt mehr als ein Präsentationskanal definiert, so kann es z. B. sinnvoll bzw. gewünscht sein, zwischen zwei Kanälen einer Seite zu wechseln (Anzeige einer Druckversion).

Hierfür gibt es den optionalen Parameter templateSet.

Als Wert für templateSet ist ein gültiger Bezeichner eines Präsentationskanales im Projekt, in doppelten Hochkommata eingefasst, anzugeben.

version

Der optionale Parameter version entspricht dem Parameter templateSet, jedoch wird als Wert die Nummer des Präsentationskanales angegeben.

Die Zählung der Präsentationskanäle beginnt in einem Projekt mit 0, d.h. der erste Präsentationskanal hat die Nummer 0, der zweite die Nummer 1 usw.

Beispiele zu $CMS_REF(...)$

Nachfolgend werden einige Beispiele zur Verwendung der Anweisung innerhalb von Vorlagen gezeigt. Die Beispiele sollen die konkrete Auswirkung der Anweisung verdeutlichen und eine Hilfe für den Vorlagenentwickler bei der Erstellung eigener Vorlagen sein.

Für die Verwendung innerhalb eines Projekts, müssen die hier gezeigten Beispiele angepasst werden! Beispielsweise müssen Variablennamen auf die spezifischen Variablennamen des Projekts geändert werden, in dem die Anweisung verwendet werden soll.

1. Beispiel: Anzeige einer Druckversion

Codebeispiel:

$CMS_REF(#global.node, templateSet:"print")$

Beschreibung:

Durch die Angabe von #global.node wird die aktuell erzeugte Seitenreferenz (Vorschau, Veröffentlichung usw.) ermittelt.
Mit der Angabe von print für den Parameter templateSet soll die URL zur erzeugten Seitenreferenz im Präsentationskanal mit der Bezeichnung print aufgelöst werden.

Ausgabe:

z. B. ../../de_1/suedsee.html

2. Beispiel: Bild in einer anderen Auflösung

Codebeispiel:

$CMS_REF(media:"suedsee", res:"100_HOCH")$

Beschreibung:

Anstelle der Originalauflösung des Bildes suedsee soll die Referenz zum Bild in der Auflösung 100_HOCH ermittelt werden. Die Auflösung 100_HOCH skaliert das Bild auf eine Höhe von 100 Pixel.

Ausgabe:

z. B. ../../media/suedsee_100_HOCH.png