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

Bei Verwendung von Remote-Medien-Projekten:

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

Automatisch erzeugte Bilddateien im Projekt beeinflussen

Bilder können in unterschiedlichen Dateiformaten (z. B. JPEG) und mit verschiedenen Auflösungen im Projekt vorliegen. Jedes Bild wird zunächst unverändert im Projekt abgelegt, d. h. in dem Format, in der es in der Medien-Verwaltung eingefügt wurde (Auflösung ORIGINAL).

Bei bestimmten Aktionen werden (basierend auf den ursprünglichen Bilddaten) automatisch neue Bilddateien von FirstSpirit erzeugt, beispielsweise:

• beim Erzeugen eines Vorschaubilds
• beim Erzeugen neuer Auflösungen
• bei der Verwendung einer automatisch generierten Auflösung
• beim Bildzuschnitt in ContentCreator oder SiteArchitect

Diese Erzeugung kann über Parameter beeinflusst werden.

Anwendungsbeispiele:

• Kompressionsrate von JPG-Bildern beeinflussen, um bei der Erzeugung eine bessere Bildqualität oder eine geringere Dateigröße zu erreichen.
• Bild-Format vorgeben (z. B. WebP)

Konfiguration im Projekt

Die Berechnung kann über die benutzerdefinierte Projekteigenschaft ImageWriterParams beeinflusst werden.

Benutzerdefinierte Projekteigenschaften (CUSTOM_PROPERTIES) können ausschließlich über die FirstSpirit Access-API (über die Methode setCustomProperties) definiert werden (nicht über den FirstSpirit ServerManager) (siehe Interface Project, Package: de.espirit.firstspirit.access.project, FirstSpirit Access-API).

Beispielskript (Beanshell) zum Anlegen einer Konfiguration:

project = context.getProject(); 
project.lock(); 
properties = new java.util.LinkedHashMap(); 
properties.put("thumbnail.jpg.compressionQuality", "0.75"); 
properties.put("default.jpg.compressionQuality", "0.75"); 
properties.put("resolution.HeaderPicture.jpg.compressionQuality", "0.95"); 
properties.put("resolution.HeaderPicture.png.compressionQuality", "0.95"); 
project.setCustomProperties("ImageWriteParam", properties); 
project.save(); 
project.unlock();

Die Parameter sollten über eine LinkedHashMap übergeben werden.
Das Skript muss mit Administratoren-Rechten im gewünschten Projekt ausgeführt werden.
Auf alle Bilder, von denen entsprechende Auflösungen verwendet werden, wird die jeweilige Konfiguration angewendet.

Verwendung der Methoden der Klasse ImageWriteParam
Es können alle Methoden der Klasse ImageWriteParam konfiguriert werden (vgl. https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/imageio/ImageWriteParam.html). Da die Methoden teilweise Abhängigkeiten zueinander haben, sollten die Parameter in der korrekten Reihenfolge hinzugefügt werden.

resolution.<Name der Auflösung>.<Art des Mediums>.<Name der zu konfigurierenden setter-Methode>

(wobei das set beim Methodennamen entfallen kann)

Für das Vorschaubild wird thumbnail anstelle von resolution.<Name der Auflösung> verwendet (siehe Beispiel).

Der compressionMode wird automatisch auf MODE_EXPLICIT gesetzt, kann aber gegebenenfalls mit einem anderen Wert überschrieben werden.

Verwendung des Parameters targetType
Weiterhin kann der Parameter targetType verwendet werden. Mit diesem kann das Bild-Format von automatisch erzeugten Bilder vorgegeben werden.
Beispielskript, mit dem alle automatisch erzeugten Bilddateien im Format WebP erzeugt werden:

project = context.getProject();
project.lock();
properties = new java.util.LinkedHashMap();
properties.put("default.targetType", "webp");
project.setCustomProperties("ImageWriteParam", properties);
project.save();
project.unlock(); 

Darüber hinaus können entsprechende Definitionen für einzelne Bildformate und/oder Auflösungen definiert werden.
Dabei wird die Einstellung für den aktuellen bestimmten Bildtypen verwendet. Wenn nicht vorhanden, wird die für die Auflösung und als Fallback die globale Einstellung verwendet.
Beispielskript, das bei PNG-Bildern den Typ PNG beibehält, für die Auflösung „Icon“ den Typ JPG verwendet und für alle anderen skalierten Bilder den Typ WebP anwendet:

project = context.getProject();
project.lock();
properties = new java.util.LinkedHashMap();
properties.put("default.targetType", "webp");
properties.put("default.png.targetType", "png");
properties.put("resolution.Icon.targetType", "jpg");
project.setCustomProperties("ImageWriteParam", properties);
project.save();
project.unlock(); 

Jedes Bildformat hat eine spezifische ImageWriteParm Implementierung, die sich von den möglichen Parametern (die Parameter werden generisch auf Setter-Methoden von ImageWriteParm abgebildet) und von Verhalten her zu anderen Bildformaten unterscheiden kann.

Verwendung des Parameters discardMetadata

Mittels der Projekteigenschaft ImageWriteParam können für automatisch erzeugte Bilddateien die Metadaten des Originalbildes (bspw. EXIF-Informationen) verworfen werden. Standardmäßig werden diese übernommen.

Im folgenden Beispiel werden für alle Bilder bis auf PNGs die Metadaten verworfen.

project = context.getProject(); 
project.lock(); 
properties = new java.util.LinkedHashMap(); 
properties.put("default.discardMetadata", "true"); 
properties.put("default.png.discardMetadata", "false"); 
project.setCustomProperties("ImageWriteParam", properties); 
project.save(); 
project.unlock();

Auslesen einer bestehenden Konfiguration
Das Auslesen der aktuell definierten Konfiguration erfolgt über den Aufruf

context.project.getCustomProperties("ImageWriteParam"); 

Wird hier <null> zurückgegeben, ist aktuell keine Konfiguration gesetzt.

Entfernen / Zurücksetzen einer bestehenden Konfiguration
Eine bestehende Konfiguration wird entfernt, indem sie mit einer leeren Konfiguration überschrieben wird, z. B.

project = context.getProject();
project.lock();
properties = new java.util.LinkedHashMap();
project.setCustomProperties("ImageWriteParam", properties);
project.save();
project.unlock();

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 Vorlagensatz definiert, kann es sinnvoll bzw. gewünscht sein, ein Referenzobjekt zu einem anderen Vorlagensatz 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 Vorlagensatzes im Projekt, eingefasst in doppelten Hochkommata, anzugeben.

version

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

Die Zählung der Vorlagensätze beginnt in einem Projekt mit 0, d.h. der erste Vorlagensatz 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)$