ref(...)

Die ref(...)-Funktion bietet die Möglichkeit, Methoden auf ein über den Bezeichner angegebenes Medium oder eine Seitenreferenz direkt anzuwenden. Dies ist insbesondere dann sinnvoll, wenn z. B. ein Gestaltungselement in einer Seitenvorlage manuell angegeben werden soll.

Syntax von ref(...)

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

$CMS_VALUE(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
).METHODE)$

Alle Parameter bis auf den BEZEICHNER sind optional.

Parameter von ref(...)

ref(...) verfügt über folgende Parameter:

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

BEZEICHNER

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

Der Bezeichner besteht bei manueller Angabe des Objekts 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 ref(...) anzugeben:

media:"suedsee"

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

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

Handelt es sich bei der über pageref angegebenen 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. Bei der Ermittlung der Seite bzw. des Datensatzes mit der höchsten ID 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 kann ein Variablenname oder auch ein Systemobjekt angegeben werden, z. B. die aktuelle Seite (mit #global.node). Auf die Objekte können Methodenaufrufe angewendet werden.

abs

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

Mit dem optionalen Parameter kann die Projekteigenschaft für eine ref(...)-Angabe überschrieben werden. Dabei 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 des URL bei abs:1 wird die Angabe Präfix für absolute Pfade in der Auftragsverwaltung verwendet. Das angegebene Präfix (z. B. http://meinServer) wird der absoluten Pfadangabe vorangestellt.

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

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

Dieses Präfix wird dann für alle folgenden ref(...).getUrl()-Aufrufe verwendet.

contentId

Mit dem Parameter contentId kann das Referenzobjekt zum angegebenen Datensatz ermittelt werden.

Als Wert erwartet der Parameter contentId die ID eines Datensatzes.

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

Damit sich der Parameter contentId auswirkt, 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_VALUE(ref(pageref:"datenquelle", contentId:374).METHODE)$

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

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

index

Mit dem Parameter index kann ein Referenzobjekt 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_VALUE(ref(pageref:"datenquelle", index:3).METHODE)$

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 des Referenzobjektes berücksichtigt werden.

lang / language

Bei Angabe des optionalen Attributs lang bzw. language wird bei der Ermittlung des Referenzobjekts zusätzlich die angegebene Projektsprache berücksichtigt. Wird der Parameter nicht angegeben, so wird mit der aktuellen Sprache (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_VALUE(ref(media:"suedsee", lang:"EN").METHODE)$

postfix

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

Ein Beispiel für einen themenbasierten Teilbereich ist ein Teaser-Bild, welches je nach Menüpunkt unterschiedlich 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 ein abweichendes Suffix. Zusätzlich kann ein „Rückfallbild“ angegeben werden, das kein Suffix enthält.

Die Ermittlung eines Referenzobjektes 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_VALUE(ref(media:"suedsee", postfix:"_A").METHODE)$

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 gleich lautende 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_VALUE(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_VALUE(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_VALUE(ref(lt_reference_remote))$ aufgelöst. (Siehe dazu auch Kapitel Verweisvorlagen.)

res / resolution

Soll bei Ermittlung eines Referenzobjektes 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 im Projekt vorhandenen Auflösung, eingefasst in doppelten Hochkommata, anzugeben (z. B. SKALIERT).

$CMS_VALUE(ref(media:"suedsee", res:"SKALIERT").METHODE)$

Mit der Funktion 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 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.

Um die URL zum Datensatz (wie bei Verwendung von $CMS_REF(...)$) zu ermitteln, muss die Methode .getUrl() verwendet werden.

Beispiel:

$CMS_VALUE(ref(pagefolder:"root", contentId:322, template:"products.product_group".url))$  

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, kann es sinnvoll bzw. gewünscht sein, ein Referenzobjekt zu einem anderen Präsentationskanal zu ermitteln (z. B. die Druckversion).

Hierfür kann der optionale Parameter templateSet verwendet werden.

Als Wert für templateSet ist ein gültiger Bezeichner eines Präsentationskanales im Projekt, eingefasst in doppelten Hochkommata, 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.

Referenzobjekt

Die ref(...)-Funktion liefert ein Referenzobjekt zurück, welches abhängig vom Referenztyp Methoden zur Verfügung stellt.

Folgende Referenzobjekte können durch die ref(...)-Funktion zurückgeliefert werden:

• ContentProducerReference bei Seitenreferenzen
• MediaReference bei Medien

ContentProducerReference (Struktur-Verwaltung)

Folgende Methoden sind auf dem Referenzobjekt ContentProducerReference anwendbar:

Ausgabe des Dateinamens:

$CMS_VALUE(ref(pageref:"unternehmen").filename)$

Ausgabe der eindeutigen Identifikationsnummer einer Seitenreferenz (PageRef):

$CMS_VALUE(ref(pageref:"unternehmen").target.id)$

MediaReference (Medien-Verwaltung)

Folgende Methoden sind auf dem Referenzobjekt MediaReference anwendbar:

Ausgabe der Breite:

$CMS_VALUE(ref(media:"suedsee").width)$

Ausgabe der Höhe:

$CMS_VALUE(ref(media:"suedsee").height)$

Ausgabe der Breite für die Auflösung W100:

$CMS_VALUE(ref(media:"suedsee", res:"W100").width)$

Ausgabe der Höhe für die Auflösung H100:

$CMS_VALUE(ref(media:"suedsee", res:"H100").height)$

Ausgabe der eindeutigen Identifikationsnummer einer Seitenreferenz (Media):

$CMS_VALUE(ref(media:"suedsee").target.id)$