Data type Area

Value range of the data type Area

In FirstSpirit it is possible to create link-sensitive graphics (also called “image map”). A link-sensitive graphic can have one or more areas which can be selected or opened by use of an input device (for example mouse, trackball). When selecting the area the link which is stored on the area will be opened .

The IMAGEMAP input component can be used to create and manage link-sensitive graphics. This input component returns an object of the data type MappingMedium.

The hot-spots or active areas are output using the .getAreas() method (in Bean syntax: .areas). This returns a list of objects of the data type Area (List<Area>). See also API documentation, interface Area.

As several hot-spots or active areas can be entered within a CMS_INPUT_IMAGEMAP input component, the instruction $CMS_FOR(...)$ is used to enable the attributes of each individual area to be output:

$CMS_FOR(AREA, st_imagemap.areas)

The following forms are supported:

• rectangular areas (see interface RectArea)
• circular areas (see interface CircleArea)
• polygonal areas (see interface PolyArea)

Different methods can be used, according to the form which was selected by the editor. The selected form can be identified in advanced for the output using a $CMS_FOR(...) instruction or the if(...) method, in combination with the method .getShape() (in Bean syntax: .shape), for example:

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

Creation via API

Link-sensitive regions (“Areas”) can be created not only using the GUI in FirstSpirit SiteArchitect or ContentCreator, but also using the FirstSpirit API:

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

Creating a frame requires use of a builder that is specific to each frame type (CircleBuilder, RectangleBuilder, PolygonBuilder), which may be obtained by calling the method get*Builder(), e. g.

getCircleBuilder()

Each builder requires specific parameters which are provided to it by calling specialized builder methods:

• CircleBuilder requires information about the x and y coordinates of the center point (center(int x, int y)) as well as the desired radius of the circle (radius(int radius))
• RectangleBuilder requires information about the x and y coordinates of both the upper left and the lower right corners of the rectangle (bounds(int left, int top, int right, int bottom))
• PolygonBuilder requires information about the x and y coordinates of each of the polygon's vertices (add(int x, int y)); the area's boundary is drawn along the vertices in the order in which they are added, whereas the first and last vertices added via the builder will automatically be connected

All builders support the method link(Link link) which may be used to assign a link object to the area that is being configured.

The builder pattern supports chained calls to a builder's methods, e.g.:

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

After configuring the builder with the desired parameters, the area is created using the method build(), e. g.:

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

Example: Configuring an image map with various areas using ImageMapAgent
Obtaining an ImageMapAgent object

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

Building an area object
The following code configures and builds a circular area, centered at (80, 80), with a radius of 70 pixels:

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

The following code configures and builds a rectangular area with a top-left vertex at (328, 258) and a bottom-right vertex at (573, 422):

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

The following code configures a polygonal area in the shape of a triangle (three vertices):

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.

Adding a link to an area object
Link data (choice of link template, link text, link target, etc.) is usually added to areas by editors, using the GUI. Via the API, such data may be defined using a link template that was obtained via the interface StoreElementAgent (Package de.espirit.firstspirit.agency, FirstSpirit Developer API), e.g.:

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 line 2 of the above code example, the string "link" indicates the reference name of the desired link template.
• In lines 5 and 6, "text" indicates the link form's input component which should carry the link text, and "link" indicates the name of the input component which carries the link target (here, a URL).

This fully configured link object, myLink, may now be passed to the builder method link(Link link):

// Continuing the polygonBuilder example from further above...

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

Adding areas to an imagemap input component
In order to add the configured areas to an imagemap input component's value of type MappingMedium (see API documentation), it is necessary to first obtain the imagemap's areas object. For an imagemap input component named myImagemap in the form data object myFormData, e. g.:

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

The individual area objects that have been built above can be added to the areas object using the method add(Area area), passing one Area object per call:

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

Lastly, the areas object (now containing at least the three area objects that were added above) is set on the myImagemap value object, and the updated myImagemap object is set in the fitting form field of the form data:

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

Methods on Area objects

The table below lists all methods which can be invoked on objects of data type Area:

equals(Object)

Overview

getClass

The .getClass() (in Bean syntax: .class) method returns the class of the invoking object (cf. java.lang.Class).

Invocation:

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

Output:

java.lang.String

Overview

getCoordinates

The method .getCoordinates() (in Bean syntax: .coordinates) returns – in dependency of the selected form – a comma-separated list of the hot-spot's coordinates in pixels, for example.

$CMS_VALUE(AREA.coordinates)$

Rectangular hotspots
If the hot-spot is a rectangle the x and y coordinates of the top left-hand and of the bottom right-hand corner are returned, for example:

30,322,130,422

The x and y coordinate of the top left-hand corner can be determined using

$CMS_VALUE(AREA.leftTop)$

the x and y coordinate of the bottom right-hand corner can be determined using

$CMS_VALUE(AREA.rightBottom)$

See also interface RectArea.

Circular hot-spots
If the hot-spot is a circle the x and y coordinates of the centre of the circle and the radius are returned, for example:

260,252,50

The x and y coordinate of the centre can be determined using

$CMS_VALUE(AREA.center)$

the radius can be determined using

$CMS_VALUE(AREA.radius)$

See also interface CircleArea.

Polygonal hot-spots
If the hot-spot is a polygon the x and y coordinates of each point are returned, for example:

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

for a pentagon.

The x and y coordinate of the corners can be determined using

$CMS_VALUE(AREA.points)$ 

As a polygon have many vertices the $CMS_FOR(...)$ instruction must be used for being able to output all vertices:

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

See also interface PolyArea.

Overview

getLink

The method .getLink() (in Bean syntax: .link) returns the link which is referenced to the hot-spot.

The link destination (reference) and link text can be resolved using

$CMS_VALUE(AREA.link.LINKDESTINATION)$ 

and

$CMS_VALUE(AREA.link.LINKTEXT)$

with LINKDESTINATION is the identifier of the input component in which the destination of the link (reference) is stored, and LINKTEXT is the identifier of the input component in which the text of the link is stored, for example:

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

(cf. also Chapter Link templates).

Overview

getShape

The method .getShape() (in Bean syntax: .shape) returns the form of the selected hot-spot:

• RECT (rectangle)
• CIRCLE (circle)
• POLY (polygon)

Specific methods are available for each of these forms. They must be used case-related. See also

• interface RectArea
• interface CircleArea
• interface PolyArea

Overview

isCase(Object)

Overview

isNull

The .isNull() (in Bean syntax: .isNull) method checks whether an expression or object is null , e.g. storeElement.isNull(). In the case of objects with complex values or objects, the object decides when it is null. The data type DomElement for example always contains an empty document, thus it is never null. For this reason, checking an empty DOM editor input component by using the method .isNull() returns the value false, whereas checking the component with .isEmpty() would return the value true.

The method .isNull() returns a Boolean value as the check result. true is the check result if the expression or object is null and false if not.

Overview

print

Overview

receive(Area$Visitor)

Overview

set(String, Object)

Overview

toJSON

Overview

toString

Overview

type

Overview