Datentyp Area

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:

• Rechteck (siehe auch Interface RectArea)
• Kreis (siehe auch Interface CircleArea)
• Polygon (siehe auch Interface PolyArea)

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:

equals(Object)

Übersicht

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

Übersicht

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.

Übersicht

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

Übersicht

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

• Interface RectArea
• Interface CircleArea
• Interface PolyArea

Übersicht

isCase(Object)

Übersicht

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.

Übersicht

print

Übersicht

receive(Area$Visitor)

Übersicht

set(String, Object)

Übersicht

toJSON

Übersicht

toString

Übersicht

type

Übersicht