Startseite / Vorlagenentwicklung / Vorlagensyntax / Funktionen / in Anweisungen / ref

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,
  contentId:WERT,
  index:WERT,
  lang:"SPRACHKÜRZEL",
  language:"SPRACHKÜRZEL",
  postfix:BEZEICHNER,
  res:"AUFLÖSUNG",
  resolution:"AUFLÖSUNG",
  templateSet:"KANALNAME",
  version:KANALNUMMER
).METHODE)$

Alle Parameter bis auf den BEZEICHNER sind optional.

Parameter von ref(...)

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

BEZEICHNER
abs
lang/language
postfix
res/resolution
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:

Objekttyp
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 aus der Struktur-Verwaltung: pageref

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"

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:

Angabe	Bedeutung
abs:0	Liefert relative Pfadangaben zurück (=Standard).
abs:1	Liefert absolute Pfadangaben mit Präfix zurück
abs:2	Liefert absolute Pfadangaben ohne Präfix zurück.
abs:3	Liefert einen internen URL für die Verwendung in internen Prozessoren (z.B. die PDF-Erzeugung in FirstSpirit) zurück. Wichtig: Die Angabe von abs:3 ist nur für Medien sinnvoll.
abs:4	Liefert einen externen URL für die Verwendung in externen Prozessoren zurück. Wichtig: Die Angabe von abs:4 ist nur für Medien sinnvoll.

Absoluten 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 für ref(...) angegebenen BEZEICHNER muss es sich um eine Content-Projektion handeln.

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.

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 erzeugt 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 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:

Zunächst wird versucht ein Objekt mit dem Referenznamen und dem angegebenen Postfix zu finden (BEZEICHNER + postfix)
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.

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)$

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.

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:

Methode	Bedeutung	Rückgabedatentyp
ref(...).filename	Ermittelt den Dateinamen	String
ref(...).page	Liefert (falls vorhanden) die referenzierte Seite aus der Inhalte-Verwaltung zurück.	Page
ref(...).target	Liefert das eigentliche Element aus der Verwaltung zurück, z.B. die Seitenreferenz.	Elementabhängig, z.B. PageRef
ref(...).url	Liefert die URL äquivalent zur $CMS_REF(...)$ -Anweisung zurück.	String

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:

Methode	Beschreibung	Rückgabedatentyp
ref(...).crc	Liefert den CRC-Wert des Bildes zurück.	Long
ref(...).description	Liefert die Beschreibung eines Bildes zurück.	String
ref(...).extension	Liefert die Erweiterung eines Bildes zurück.	String
ref(...).extension("AUFLÖSUNG")	Liefert die Erweiterung eines Bildes für die angegebene Auflösung zurück.	String
ref(...).height	Liefert die Höhe eines Bildes in Pixel zurück. Wichtig: Die Verwendung von .height ist nur für Bilder möglich.	Integer
ref(...).height("AUFLÖSUNG")	Liefert die Höhe eines Bildes für die angegebene Auflösung in Pixel zurück. Wichtig: Die Verwendung von .height(...) ist nur für Bilder möglich.	Integer
ref(...).size	Liefert die Dateigröße eines Bildes zurück.	Long
ref(...).size("AUFLÖSUNG")	Liefert die Dateigröße eines Bildes für die angegebene Auflösung zurück.	Long
ref(...).target	Liefert das eigentliche Element aus der Verwaltung zurück, z.B. das Medium.	Elementabhängig, z.B. Media
ref(...).url	Liefert die URL äquivalent zur $CMS_REF(...)$ -Anweisung zurück.	String
ref(...).width	Liefert die Breite eines Bildes in Pixel zurück. Wichtig: Die Verwendung von .width ist nur für Bilder möglich.	Integer
ref(...).width("AUFLÖSUNG")	Liefert die Breite eines Bildes für die angegebene Auflösung in Pixel zurück. Wichtig: Die Verwendung von .width(...) ist nur für Bilder möglich.	Integer

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)$

Druckversion | Seitenanfang