Startseite / Vorlagenentwicklung / Vorlagensyntax / Datentypen / Area

Datentyp AreaVerfügbar ab FirstSpirit-Version 5.1R2

Wertebereich des Datentyps Area

In FirstSpirit gibt es die Möglichkeit, verweissensitive Grafiken (sogenannte „Imagemaps“) zu erstellen. Eine verweissensitive Grafik verfügt über einen oder mehrere Bereiche, die mithilfe eines Eingabegeräts (z. B. Maus, Trackball) ausgewählt bzw. aufgerufen werden können. Beim Aufruf des Bereichs mit dem Eingabegerät wird der dem Bereich hinterlegte Verweis aufgerufen.

Für die Pflege von verweissensitiven Grafiken steht die Eingabekomponente IMAGEMAP zur Verfügung. Diese Eingabekomponente liefert ein Objekt vom Datentyp MappingMedium zurück.

Die verweissensitiven Bereiche werden über die Methode .getAreas() (in Bean-Syntax: .areas) ausgegeben. Diese liefert eine Liste von Objekten vom Datentyp Area zurück (List<Area>). Siehe dazu auch API-Dokumentation, Interface Area.

Da innerhalb einer CMS_INPUT_IMAGEMAP-Eingabekomponente mehrere verweissensitive Bereiche gepflegt sein können, wird die Anweisung $CMS_FOR(...)$ verwendet, um die Attribute jedes einzelnen Bereichs ausgeben zu können:

$CMS_FOR(BEREICH, st_imagemap.areas)

Da die einzelnen Bereiche üblicherweise drei unterschiedliche Formen haben (Rechteck, Kreis und Polygon), steht auch für jede Form ein eigenes Interface im Paket de.espirit.firstspirit.access.editor.value.imagemap zur Verfügung:

In Abhängigkeit der vom Redakteur gewählten Form stehen unterschiedliche Methoden zur Verfügung. Die gewählte Form kann bei der Ausgabe vorab über eine $CMS_FOR(...)-Anweisung oder die if(...)-Methode in Kombination mit der Methode .getShape() (in Bean-Syntax: .shape) ermittelt werden, z. B.

$CMS_IF(BEREICH.shape=="CIRCLE")$
...
$CMS_END_IF$

Erzeugung via API

Verweissensitive Bereiche („Areas“) können nicht nur über die GUI im FirstSpirit SiteArchitect oder ContentCreator erzeugt werden, sondern auch über die FirstSpirit-API:

Interface ImageMapAgent, Package de.espirit.firstspirit.access.editor.value.imagemap (FirstSpirit Access-API).

Um einen Rahmen zu erstellen, wird ein Builder verwendet, der spezifisch zur gewünschten Rahmenform ist (CircleBuilder, RectangleBuilder, PolygonBuilder). Diese Builder-Objekte werden über die Methode get*Builder() eingeholt, z. B.

getCircleBuilder()

Jeder Builder verwendet spezifische Parameter, die über die spezialisierten Builder-Methoden übergeben werden:

  • CircleBuilder erfordert Angaben zu den x- und y-Koordinaten des Mittelpunktes (center(int x, int y)) und zum Radius des gewünschten Kreises (radius(int radius))
  • RectangleBuilder erfordert Angaben zu den x- und y-Koordinaten sowohl der linken oberen als auch der rechten unteren Ecke des Rechtecks (bounds(int left, int top, int right, int bottom))
  • PolygonBuilder erfordert Angaben zu den x- und y-Koordinaten jeder einzelnen Ecke des Polygons (add(int x, int y)); der Umriss des Rahmens wird entlang der Eckpunkte in der Reihenfolge gezogen, in der die Eckpunkte hinzugefügt wurden, wobei der erste und der letzte hinzugefügte Eckpunkt automatisch miteinander verbunden werden

Alle Builder unterstützen die Methode link(Link link), über die der Area, die konfiguriert wird, ein Verweis hinzugefügt werden kann.

Das Builder-Pattern unterstützt verkettete Aufrufe der Builder-Methoden, z. B.:

circleBuilder.center(151, 106).radius(102)

Nachdem der Builder mit den erforderlichen Parametern konfiguriert wurde, wird die Area mit der Methode build() erzeugt, z. B.:

circleBuilder.center(151, 106).radius(102).build();

Beispiel: Konfiguration einer Imagemap mit mehreren Areas unter Nutzung des ImageMapAgent
ImageMapAgent-Objekt einholen

import de.espirit.firstspirit.access.editor.value.imagemap.ImageMapAgent;
imageMapAgent = context.requireSpecialist(ImageMapAgent.TYPE);

Area-Objekte erzeugen
Der folgende Beispiel-Code konfiguriert und erzeugt eine kreisförmige Area, die um den Punkt (80, 80) zentriert ist und einen Radius von 70 Pixel hat:

circleBuilder = imageMapAgent.getCircleBuilder();
areaCircle = circleBuilder.center(80, 80).radius(70).build();

Der folgende Code konfiguriert und erzeugt eine rechteckige Area mit dem linken oberen Eckpunkt bei (328, 258) und dem rechten unteren Eckpunkt bei (573, 422):

rectangleBuilder = imageMapAgent.getRectangleBuilder();
areaRectangle = rectangleBuilder.bounds(328,258,573,422).build();

Der folgende Code konfiguriert und erzeugt eine polygonale Area, die ein Dreieck repräsentiert (drei Eckpunkte):

polygonBuilder = imageMapAgent.getPolygonBuilder();
polygonBuilder.add(30,660);
polygonBuilder.add(270,260);
polygonBuilder.add(30,260);

// Im folgenden Beispiel werden wir den polygonBuilder benutzen, um der Area einen Verweis hinzuzufügen;
// polygonBuilder.build() wird später aufgerufen.

Einen Verweis einem Area-Objekt hinzufügen
Verweisdaten (Wahl der Verweisvorlage, Verweistext, Verweisziel usw.) werden den Areas meist von Redakteuren über die GUI hinzugefügt. Diese Daten können aber auch per API hinzugefügt werden; dies erfordert die Nutzung einer Verweisvorlage, die beispielsweise über das Interface StoreElementAgent (Package de.espirit.firstspirit.agency, FirstSpirit Developer-API) eingeholt wurde, z. B.

storeElementAgent = context.requireSpecialist(StoreElementAgent.TYPE);
linkTemplate = storeElementAgent.loadStoreElement("link",IDProvider.UidType.TEMPLATESTORE_LINKTEMPLATE,false);
myLink = linkTemplate.createLink(null);
linkFormData = myLink.getFormData();
linkFormData.get(null,"text").set("e-Spirit Website");
linkFormData.get(null,"link").set("https://www.e-spirit.com");
myLink.setFormData(linkFormData);

  • In Zeile 2 des obigen Code-Beispiels gibt der String "link" den Referenznamen der gewünschten Verweisvorlage an.
  • In den Zeilen 5 und 6 gibt "text" die Eingabekomponente im Verweisformular an, in der der Verweistext gespeichert werden soll, und "link" gibt den Namen der Eingabekomponente an, in der das Verweisziel (hier eine URL) gespeichert werden soll.

Dieses komplett konfigurierte Verweisobjekt, myLink, kann nun der Builder-Methode link(Link link) übergeben werden:

// Fortsetzung des polygonBuilder-Beispiels von oben...

areaPolygon = polygonBuilder.link(myLink).build();

Areas einer Imagemap-Eingabekomponente hinzufügen
Um die Area einer Imagemap-Eingabekomponente (repräsentiert von einem Wertobjekt des Typs MappingMedium (siehe API-Dokumentation) hinzuzufügen, muss zunächst das Areas-Objekt der Imagemap eingeholt werden. Z. B., für eine Imagemap-Eingabekomponente namens myImagemap im Formulardatenobjekt myFormData:

myImagemap = myFormData.get(null,"myImagemap").get();
areas = myImagemap.getAreas();

Die einzelnen Area-Objekte, die weiter oben erzeugt wurden, können nun einzeln diesem Areas-Objekt über die Methode add(Area area) hinzugefügt werden:

areas.add(areaCircle);
areas.add(areaRectangle);
areas.add(areaPolygon);

Zuletzt muss das areas-Objekt (welches nun mindestens die drei oben hinzugefügten Areas enthält) wieder ins myImagemap-Wertobjekt zurückgeführt und das aktualisierte myImagemap-Objekt ins passende Formularfeld der Formulardaten zurückgeschrieben werden:

myImagemap.setAreas(areas);
myFormData.get(null,"myImagemap").set(myImagemap);

Methoden auf Area-Objekten

In der unten angegebenen Tabelle werden alle Methoden aufgelistet, die auf Objekten vom Datentyp Area aufgerufen werden können:

Methodenname Rückgabetyp Kurzbeschreibung Verfügbar seit
equals(Object) boolean
getClass Class Klasse des aufrufenden Objektes
getCoordinates String Koordinaten des verweissensitiven Bereichs 5.1.207
getLink Link Verweis, der mit dem verweissensitiven Bereich verknüpft ist 5.1.203
getShape String Form des verweissensitiven Bereichs 5.1.207
isCase(Object) boolean
isNull boolean Prüft, ob ein Ausdruck Null ist
print void
receive(Area$Visitor) Object Receive the handed visitor. 5.1.203
set(String, Object) Object
toJSON String Convert to a JSON-compatible string representation including necessary quotes and escaping for immediate use. Handles Maps, Collections, Arrays, Numbers, Strings, Boolean, Date, and JsonElement. A date instance will be converted to an ISO-8601 formatted date string. Any object other than above will be converted using its 'toString()' value. 5.2.11
toString String
type String

equals(Object)

Methodenname Rückgabetyp Verfügbar seit
equals(Object) boolean

getClass

Die Methode .getClass() (in Bean-Syntax: .class) liefert die Klasse des aufrufendes Objektes zurück (vgl. java.lang.Class).

Aufruf:

$CMS_VALUE(myString.class)$
$CMS_VALUE(myString.getClass())$

Ausgabe:

java.lang.String
Methodenname Rückgabetyp Verfügbar seit
getClass Class

getCoordinates

Die Methode .getCoordinates() (in Bean-Syntax: .coordinates) liefert – in Abhängigkeit der gewählten Form – eine kommaseparierte Liste der Koordinaten der verweissensitiven Bereiche in Pixeln zurück, z. B.

$CMS_VALUE(BEREICH.coordinates)$

Rechteckige verweissensitive Bereiche
Handelt es sich bei dem verweissensitiven Bereich um ein Rechteck, werden die x- und y-Koordinaten des linken oberen und des rechten unteren Punkts ausgegeben, z. B.:

30,322,130,422

Die x- und y-Koordinate der linken oberen Ecke kann mit

$CMS_VALUE(BEREICH.leftTop)$

die x- und y-Koordinate der rechten unteren Ecke mit

$CMS_VALUE(BEREICH.rightBottom)$

ermittelt werden.
Siehe dazu auch Interface RectArea.

Kreisförmige verweissensitive Bereiche
Handelt es sich bei dem verweissensitiven Bereich um einen Kreis, werden die x- und y-Koordinaten des Mittelpunkts ausgegeben sowie der Radius, z. B.:

260,252,50

Die x- und y-Koordinate des Mittelpunkts kann mit

$CMS_VALUE(BEREICH.center)$

der Radius mit

$CMS_VALUE(BEREICH.radius)$

ermittelt werden.
Siehe dazu auch Interface CircleArea.

Vieleckige verweissensitive Bereiche
Handelt es sich bei dem verweissensitiven Bereich um ein Vieleck, werden die x- und y-Koordinaten aller Ecken ausgegeben, z. B.:

369,215,427,182,449,223,417,264,350,265

für ein Fünfeck.

Die x- und y-Koordinate der einzelnen Punkte kann mit

$CMS_VALUE(BEREICH.points)$

ermittelt werden.

Da ein Vieleck aus mehreren Ecken besteht, muss die $CMS_FOR(...)$-Anweisung verwendet werden, um die x- und y-Koordinaten aller Ecken auszugeben:

$CMS_FOR(point, BEREICH.points))$
x: $CMS_VALUE(point.x)$, y: $CMS_VALUE(point.y)$
$CMS_END_FOR$

Siehe dazu auch Interface PolyArea.

Methodenname Rückgabetyp Verfügbar seit
getCoordinates String 5.1.207

getLink

Die Methode .getLink() (in Bean-Syntax: .link) liefert den Verweis zurück, der mit dem verweissensitiven Bereich verknüpft ist.

Verweisziel und Verweistext können über

$CMS_VALUE(BEREICH.link.VERWEISZIEL)$ 

bzw.

$CMS_VALUE(BEREICH.link.VERWEISTEXT)$

aufgelöst werden, wobei VERWEISZIEL der Bezeichner der Eingabekomponente des Verweises ist, in der das Verweisziel gespeichert wird, und VERWEISTEXT der Bezeichner der Eingabekomponente des Verweises, in der der Verweistext gespeichert wird, z. B.:

<a title="$CMS_VALUE(BEREICH.link.lt_text)$" href="$CMS_VALUE(BEREICH.link.lt_reference)>

(vgl. dazu auch Kapitel Verweisvorlagen).

Methodenname Rückgabetyp Verfügbar seit
getLink Link 5.1.203

getShape

Die Methode .getShape() (in Bean-Syntax: .shape) liefert die Form des gewählten verweissensitiven Bereichs zurück:

  • RECT (Rechteck)
  • CIRCLE (Kreis)
  • POLY (Vieleck)

Für jede dieser Formen gibt es spezifische Methoden, die fallbezogen verwendet werden müssen. Siehe dazu auch

Methodenname Rückgabetyp Verfügbar seit
getShape String 5.1.207

isCase(Object)

Methodenname Rückgabetyp Verfügbar seit
isCase(Object) boolean

isNull

Die Methode .isNull() (in Bean-Syntax: .isNull) prüft, ob ein Ausdruck bzw. Objekt Null ist, z. B. storeElement.isNull(). Bei Objekten mit komplexen Werten oder Objekten entscheidet das Objekt, wann es null ist. Der Datentyp DomElement enthält beispielsweise immer ein leeres Dokument, ist also nie null. Die Prüfung einer leeren DOM-Editor-Eingabekomponente mit der Methode .isNull() liefert daher den Wert false, während die Prüfung der Komponente auf .isEmpty() den Wert true liefern würde.

Die Methode .isNull() gibt einen booleschen Wert als Ergebnis der Prüfung zurück. true (=wahr) ist die Prüfung, wenn der Ausdruck bzw. das Objekt Null ist und false (=unwahr) wenn nicht.

Methodenname Rückgabetyp Verfügbar seit
isNull boolean

print

Methodenname Rückgabetyp Verfügbar seit
print void

receive(Area$Visitor)

Receive the handed visitor.
Methodenname Rückgabetyp Verfügbar seit
receive(Area$Visitor) Object 5.1.203

set(String, Object)

Methodenname Rückgabetyp Verfügbar seit
set(String, Object) Object

toJSON

Convert to a JSON-compatible string representation including necessary quotes and escaping for immediate use. Handles Maps, Collections, Arrays, Numbers, Strings, Boolean, Date, and JsonElement. A date instance will be converted to an ISO-8601 formatted date string. Any object other than above will be converted using its 'toString()' value.
Methodenname Rückgabetyp Verfügbar seit
toJSON String 5.2.11

toString

Methodenname Rückgabetyp Verfügbar seit
toString String

type

Methodenname Rückgabetyp Verfügbar seit
type String

© 2005 - 2024 Crownpeak Technology GmbH | Alle Rechte vorbehalten. | FirstSpirit 2024.2 | Datenschutz