Dev: SM: Javascript API Reference

From AAT Wiki
Jump to: navigation, search

Contents

Mapping Services - Technical Documentation

Document Revision History

16-Jan-08 Greg Mahlknecht Initial Revision
28-Jul-08 Greg Mahlknecht Added SetShowProgress, SetHotkeys, SetMouse

CAatMap Object

Introduction

The CAatMap object is the base object which encapsulates a map. It can contain as many bitmap/data layers as is feasible within the constraints of the user's computer power. A number of callbacks offer interactivity between the user and the website application, and there is a rich set of commands to maintain the map's state and content.

Dependant Objects

CAatBitmapLayer

A raster map layer; this may contain street centerline data, satellite data, statistical data, and the API has facilities for users to create their own CAatBitmapLayer via URL callbacks to their own server which serves images.

CAatPointLayer

A data layer, which holds data points overlayed; usually overlayed onto the lower CAatBitmapLayer layers on the map.

About Zoom Levels

Properties

RedrawCallback

Assign this property to a function that is called whenever the map has finished redrawing, usually as a result of the Init() function. The function declaration should be

function RedrawCallbackFunction (mapobj,x,y,source,forcemove)

Where

mapobj (CAatMap) The map object that has just finished redrawing
x (float) The geographical X coordinate of the center of the map
y (float) The geographical Y coordinate of the center of the map
source (string) A description passed through from the item which invoked the redraw. Useful for debugging.
forcemove (Boolean) Treat the redraw as if the map has moved since the last time RedrawCallbackFunction was invoked, even if it has not.

PopupMenuCallback

Assign this property to a function which is called when the user selects an item from the rightclick-popup menu that is not handled by the system ; ie. A user function. The function declaration should be

function PopupMenuCallbackFunction(mapobj, selected, x, y)

Where

mapobj (CAatMap) object that the menu was invoked from
selected (string) The string associated with the menu item which was selected
x (float) The geographical X coordinate at which the menu was invoked
y (float) The geographical Y coordinate at which the menu was invoked

ClickCallback

Description

Assign this property to a function which will be fired each time the user clicks on the map. The declaration of the function should be

function ClickCallbackFunction (mapobj, x, y)

Where

x (float) The geographical X coordinate at which the cursor was clicked
y (float) The geographical Y coordinate at which the cursor was clicked
mapobj (CAatMap) The map which was clicked on.

You can get the pixel position relative to the top-left of the map, by accessing the mapobj.nClickX and mapobj.nClickY properties.


RightClickCallback

Description

Assign this property to a function which will be fired each time the user right-clicks on the map. Note: the handling function/page must take care of ensuring the browser does not pop up the context menu. The declaration of the function should be

function RightClickCallback(mapobj, x, y)

Where

x (float) The geographical X coordinate at which the cursor was clicked
y (float) The geographical Y coordinate at which the cursor was clicked
mapobj (CAatMap) The map which was clicked on.

You can get the pixel position relative to the top-left of the map, by accessing the mapobj.nClickX and mapobj.nClickY properties.

Methods - Setup / Initialization

AddLayer (type, position, id)

Adds a new layer to the map.

Arguments
type (string) Type of layer to add, currently defined layers are:
map: The basic bitmapped streetmap layer CAatBitmapLayer
point: CAatPointLayer layer
custom: Allows the use of custom CAatBitmapLayer layers
position (number) Z-Position of the layer in the stack – the higher this number is, the further toward the bottom of the stack of layers it will be. Layers with a lower position will appear to be stacked on top of ones with a higher number.
id (string) A unique reference for this layer; It only needs to be unique should you need to use it later, the system does not require this to be unique to function correctly.

Returns

Depending on the "type" argument; "map" and "custom" will return a CAatBitmapLayer, and "point" will return a CAatPointLayer object.

Init (callbacks)

Redraws the map object, and effects all the changes you have made the variables.

Arguments

callbacks true: Once the map has redrawn, it will call any of the callbacks that you have set.
false: The callbacks will not be called after the redraw, even if they are set.

Returns

Nothing.

Jump (newx, newy, newzoom)

Updates the internal variables to the new position. The map is not affected, only internal variables are updated. To update them and then perform the map update, use the JumpTo method.

Arguments

newx (float) New geographic X coordinate
newy (float) New geographic Y coordinate
newzoom (float) New Zoom Level; this has to be a valid zoom level, one of the following:
10.24, 5.12, 2.56, 1.28, 0.64, 0.32, 0.12, 0.05, 0.02, 0.01, 0.005, 0.0025, 0.00125, 0.000625
This represents the amount of map, in degrees, per 300x300 pixel tile, between the center an an edge.

Returns

Nothing

JumpTo(newx, newy, newzoom)

The JumpTo method invokes the Jump method to update the internal parameters, then calls Init(true) to update the map.

Returns

Nothing

See Also

Jump, Init

SetBranding (logoname, width, height)

Sets the logo that is placed at the bottom-right of the map for branding purposes.

Arguments

logoname (string-url) URL of the logo to be displayed. Preferably a PNG logo with an alpha channel so that it's non-obtrusive and blends into the ma pwell.
width (float) The width, in pixels, of the image speicified in logoname
height (float) The height, in pixels, of the image speicified in logoname

Returns

Nothing

SetOutput (ctrlname)

Set the container into which the map shall be rendered. This should be a <div> section, with a size that doesn't change, ie. It should be made sure that the dimensions are not dynamic in the markup which encapsulates the <div>. This is easiest done through style="width:X;height:Y;" when the div is declared.

Arguments

ctrlname (string) The name of the <div> section into which the map will be rendered.

Returns

Nothing

Methods - Map Navigation / Positioning

DegWidth ()

Methods used to discover the width of the map pane, in degrees.

Returns

(float) The total distance, in degrees, from the left to the right edges of the map pane.

DegHeight ()

Methods used to discover the height of the map pane, in degrees.

Returns

(float) The total distance, in degrees, from the top to the bottom edges of the map pane.

FindBigger (closeto)

Arguments

closeto (float) The desired zoom level

Returns

(float) The next largest (zoomed-out) CAatMap supported zoom level that is close to the closeto argument.

FindZoom (numdegx, numdegy, notfound)

Find a zoom level that will fit the specified geographical dimensions on the map.

Arguments

numdegx (float) Number of geographical degrees to fit into the X dimension of the map
numdegy (float) Number of geographical degrees to fit into the Y dimension of the map
notfound (float, optional) If the speicified arguments cannot be made to fit onto the screen (either too small or large), this value wll be used

Returns

(float) The closest zoom level that will contain the given dimensions.

GetTileZoom ()

Returns

(float) The zoom level of the individual tiles in the map. Each tile is 300x300 pixels.

GetX ()

Returns

(float) The geographic X coordinate of the center of the displayed map.

GetY ()

Returns

(float) The geographic X coordinate of the center of the displayed map.

GetZoom ()

Returns

(float) The zoom level which represents the entire map area. This zoom level is the number of degrees between the center of the map and the furthest edge.


RemoveScrollRestrictions ()

Cancels any scroll restrictions put in place by SetScrollRestrictions()

Returns

Nothing

RemoveZoomRestrictions ()

Cancels any zoom restrictions put in place by SetZoomRestrictions()

Returns

Nothing

SetLanguage (lang)

Arguments

lang (string) The language, according to the Dev: SM: MARC Language Codes which the map should be localized for. The degree of localization is dependent on the source data.

Returns

Nothing

SetTileZoom (newzoom)

Arguments

newzoom (float) A new zoom level to set the internal CAatMap object's level to. This should be a valid zoom level; see the Introduction for these zoom levels. The map is not updated, Init() will have to be called for this to take effect.

Returns

Nothing

SetPanJump (amount)

Controls how much of the map is panned when clicking on the arrows on the sides of the map.

Arguments

amount (float) The amount that the map must jump when the pan arrows are pressed. 1.0 is the entire map. Default is 0.75 (3/4 of the map).

Returns

Nothing


SetScrollRestrictions (x1, y1, x2, y2)

This will constrain the scrolling of the map to a certain specified area. Should the map be out of these bounds via another API call, or other circumstances, when the restriction is in place, the map will not be moved to be within these bounds, instead the map will only be able to be scrolled one way - in a direction to get it in the bounds of the restriction.

Arguments

x1, y1 (float) Top-left coordinate of the area to restrict to.
x2, y2 (float) Bottom-Right coordinate of the area to restrict to.

Returns

Nothing

SetZoomRestrictions (minz, maxz)

This will constrain the zooming of the map to a certain range. Should the map be out of these bounds via another API call, or other circumstances, when the restriction is in place, the map will not be zoomed to be within these bounds, instead the map will only be able to be zoomed one way - in a direction to get it in the bounds of the restriction. Both values must be specified in Zoom_Levels values.

Arguments

minz (float) The minimum zoom level.
maxz (float) The maximum zoom level

Returns

Nothing

SetX (newx)

Arguments

newx (float) A new X coordinate to set the internal CAatMap object's X coordinate to. The map is not updated, Init() will have to be called for this to take effect.

Returns

Nothing

SetY (newy)

Arguments

newy (float) A new Y coordinate to set the internal CAatMap object's Y coordinate to. The map is not updated, Init() will have to be called for this to take effect.

Returns

Nothing

ZoomBounds (x1, y1, x2, y2)

Updates the internal CAatMap variables to fit in the specified area of the map. The map itself is not updated, Init() will need to be called to reflect the update. The map might be zoomed out a little more than the exact bounds of the specified area, to fit in with one of CAatMap's zoom levels.

Arguments

x1, y1 (float) Top-left coordinate of the area which needs to be viewed.
x2, y2 (float) Bottom-Right coordinate of the area which needs to be viewed.

Returns

Nothing

Methods - On-Map Elements and Controls

SetCreditTextPosition (pos)

Arguments

pos (int) 0: The credits will appear on the bottom-left
1: The credits will appear on the bottom-right

Returns

Nothing

SetCreditLoglPosition (pos)

Arguments

pos (int) 0: The branding logo will appear on the bottom-left
1: The branding logo will appear on the bottom-right

Returns

Nothing

SetHandCursor (newcurs)

This cursor will be used in normal hover mode, as the user moves the mouse around the map.

Arguments

newcurs (String): A URL starting with http:// or a CSS cursor style (crosshair, pointer, etc). Pass an empty string to revert to the API's default cursor.

Returns

Nothing

SetGrabCursor (newcurs)

This cursor will be used when the user presses the left mouse button to move the map. Arguments

newcurs (String): A URL starting with http:// or a CSS cursor style (crosshair, pointer, etc). Pass an empty string to revert to the API's default cursor.

Returns

Nothing


SetHotkeys (active)

Arguments

active (Boolean, default) true: The hotkeys (arrow keys, pgup, pgdn) will be active
false: The hotkeys will be disabled for this control

Returns

Nothing

SetModeButtons (visible)

Arguments

visible (boolean) true: The Map/Hybrid/Sat tabs will be drawn on the map
false: The Map/Hybrid/Sat tabs will not be drawn on the map

Returns

Nothing

SetMouse (active)

Arguments

active (boolean, default) true: The mouse controls (drag, click, doubleclick) and touch control (drag, pinch-zoom) will be active on this map
false: The mouse controls and touch control (drag, pinch-zoom) will have no effect on this map

Returns

Nothing

SetNavigate (visible)

Arguments

visible (boolean) true: All the navigation items will be drawn
false: None of the navigation items will be drawn – this includes the zoom slider, arrows at the side of the map, as well as all tabs around the map area. The copyright notice will be the only item to appear on the map, for legal reasons.

Returns

Nothing

SetPointsButtons (visible)

Arguments

visible (boolean) true: The Points/Numbers tabs will be drawn on the map
false: The Points/Numbers tabs will not be drawn on the map

Returns

Nothing

SetScaleBar (visible)

Arguments

visible (boolean) true: The scale bar will be drawn at the bottom-left of the map
false: The scale bar will not be drawn at the bottom-left of the map

Returns

Nothing

SetShowProgress (active)

If this is active, then whenever the map control communicates with the server in the background, a moving progress indicator will be shown at the top-right of the window to notify the user something is happening. This option is OFF by default as it may interfere with other on-screen elements on complex sites.

Arguments

active (boolean) true: The progress indicator will be shown
(default) false: No progress indicator will be shown

Returns

Nothing

SetWheelActive(active)

Enables or disables the mouse scroll wheel for zooming.

Arguments

active (boolean) (default) true: The mouse scroll wheel is active and will cause the map to zoom in and out
(default) false: The mouse scroll wheel will not zoom in and out.

Returns

Nothing


SetZoomRectangleAutoDisengage (enable)

If this is enabled, then when the map is put into drag-to-zoom mode, and the user zooms in on the map, it is automatically reset to drag-to-pan mode.

Arguments

enable (boolean) true: Enable automatic disengage of drag-to-zoom
(default) false: Drag-to-zoom will not automatically be disengaged

Returns

Nothing

Methods - Layer Manipulation

GetLayer (id)

Finds a given layer within the CAatMap object

Arguments

id (string) The ID of the layer that was specified at layer creation

Returns

(CAatBitmapLayer or CAatPointLayer) The layer corresponding to the one specified by id, or null if no layer was found with the specified ID.

See Also

CAatMap::CreateLayer

RemoveLayer (id)

Removes a given layer within the CAatMap object. The layer is deleted, but the map is not refreshed. The CAatMap::Init() function must be called separately to update the onscreen map

Arguments

id (string) The ID of the layer specified at layer creation

Returns

(boolean) true: Layer was found and deleted

false: Layer was not found

See Also

CAatMap::CreateLayer

CAatPointLayer Object

Introduction

A CAatPointLayer contains one or more points. This layer is added to an active CAatMap object with the CAatMap::AddLayer function, after which point the CAatPointLayer::AddPoint function can be called to add the points to the CAatPointLayer layer.

Working Example

Dependant Objects

CAatpoint

The base point type.

Methods - Point Set up / Manipulation

AddPoint (x, y, caption, id)

Adds a point to the layer. Only the very bare minimum properties of the point are set with this function, one would almost always want to use the CAatPoint methods to further enrich the look and functionality of the point.

Arguments

x (float) X Coordinate of the new point
y (float) Y Coordinate of the new point
caption (string) Default caption for this new point

If you wish to embed an <a> link in the label, ensure it has an ID starting with genlink_


id (string) Optional: Unique identifier for the point, only needed should you plan on accessing the point using it later.

Returns

(CAatPoint) The newly added point

DeletePoint (id)

Arguments

id (string) The unique identifier of the point to delete, as specified in AddPoint.

Returns

(boolean) true: Point was found and deleted

false: Point was not found in the layer

RemoveAllPoints ()

Removes all the points in the layer

Returns

None

SetDefaultAnchor (anchorx, anchory)

Sets the default anchor which all points added subsequently on this layer will use, unless overridden.

Arguments

anchorx (string) Horizonal alignment of the elements in the point
left: Elements are aligned with left side on the specified X coordinate of the point
center: Centers of the elements are aligned on the specified X coordinate of the point
right: Right edges of the elements are aligned to the specified X coordinate of the point
anchory (string) Vertical alignment of the elements in the point
top: Elements are aligned with top edge on the specified Y coordinate of the point
center: Centers of the elements are aligned on the specified Y coordinate of the point
bottom: B ottom edges of the elements are aligned to the specified Y coordinate of the point

Returns

Nothing

See Also

CAatPoint::SetIconAnchor, CAatPoint::SetLabelAnchor

Methods - Utility Methods

GetBounds ()

Calculates a bounding rectangle that will contain all the points in the layer

Returns

(array of floats): the array contains 4 elements, (x_topleft, y_topleft, x_bottomright, y_bottomright).

IsPoint (id)

Arguments

id (string) Unique identifier of a point, as specified when the point was added with AddPoint()

Returns

(boolean) true: The point was found in the layer
false: The point was not found in the layer

FindPoint (id)

Arguments

id (string) Unique identifier of a point, as specified when the point was added with AddPoint()

Returns

(CAatPoint) The point with a matching unique identifier id, or null if the point was not found.

CAatPoint Object

Methods

SetCallback (cb_func)

Sets the function that will be called when the point is clicked on.

Arguments

cb_func (function) A javascript function that will be called when the point is clicked. A single parameter is passed to this, which is the point which was clicked on. From here, one can use the "id" property of the point that was passed in to create it, to ascertain which point was clicked on.

The callback will have 2 parameters:

  • cb_point = Point that was clicked on
  • cb_button = Button that was pressed. 0=left 1=right

Returns

Nothing

SetHoverCallback (cb_func)

Sets the function that will be called when the point hovered over (icon or bubble area).

Arguments

cb_func (function) A javascript function that will be called when the point is hovered over (mouse entry or exit). Two parameters are passed to this: the point which was clicked on, and a hover_in parameter which is true if the mouse has entered the area, false if it is leaving. From here, one can use the "id" property of the point that was passed in to create it, to ascertain which point was clicked on.

Returns

Nothing

SetIconSize (newx, newy)

Sets the size of the icon which will be used. This is necessary to ensure accurate rendering and placement of the point.

Arguments

newx (integer) Size, in pixels, of the width of the icon to be used for this point
newy (integer) Size, in pixels, of the height of the icon to be used for this point

Returns

Nothing

See Also

SetIcon

SetManualShift(shiftx, shifty)

Sets the offset of the icon and label by shiftx, shifty pixels.

Arguments

shiftx (integer) Offset, in pixels, that the point and label will be shifted when rendered
shifty (integer) Offset, in pixels, that the point and label will be shifted when rendered

Returns

Nothing

SetVisible (min, max)

Controls the zoom levels between which the icon is visible.

Arguments

min (float) Minimum zoom level to show this point at
max (float) Maximum zoom level to show this point at

Returns

Nothing

See Also

"About Zoom Levels" in the CAatMap section

SetClickBehaviour (behaviour)

Although you can override the behavior of the point click, the API provides the most common behaviours you might need.

Arguments

behavior (string) New behaviour of this point
"toggle_all_label": Clicking on either the label area or the image icon will toggle between just displaying the icon and the icon and label together
"toggle_icon_label": Clicking on only the icon will toggle between displaying the icon and the icon and label together. This should be used should your popup label contain any hotspots.


"hover_toggle_icon_biglabel": Hovering over the icon will cause the popup to show. Moving out the icon will make it go away.

Returns

Nothing

SetRawLabel (newtext)

Sets a piece of raw HTML to render in the label area. This overrides the pop-up bubbles.

Arguments

newtext (string) The HTML to render in the label. It will be contained in a DIV. This HTML fragment must start with an HTML tag.

If you wish to embed an <a> link in the label, ensure it has an ID starting with genlink_

Returns

Nothing

SetStyle (style)

Arguments

style (string) The display style of this point
"label": The label an corresponding icon will both be shown
"icon": Only the icon will be shown

Returns

Nothing

SetTooltip (tip)

Arguments

tip (string) The string which will be displayed in a standard tooltip when then cursor hovers over the icon of the point.

Returns

Nothing

SetIcon (icon)

Arguments

icon (string) The URL of the icon which will represent this point. It is suggested that a png or gif file is used, as the API will honour transparent backgrounds and attempt to make the PNG files work in IE6, where there are issues with PNG files and transparent images.

Returns

Nothing

SetIconAnchor (anchorx, anchory)

Arguments

anchorx (string) How the icon image will be aligned to the coordinates specified for this point
"left": The left edge of the image will be aligned to the coordinate
"center": The center of the image will be aligned to the coordinate
"right": The right edge of the image will be aligned to the coordinate
anchory (string) Controls how the icon is aligned vertically
"top": The top edge of the icon is aligned to the coordinate
"center": The center of the image is aligned to the coordinate
"bottom": The bottom edge of the icon sits on the coordinate

Returns

Nothing

SetLabelAnchor (anchorx, anchory)

Arguments

anchorx (string) How the pop-up label will be aligned to the coordinates specified for this point
"left": The left edge of the label will be aligned to the coordinate
"center": The center of the label will be aligned to the coordinate
"right": The right edge of the label will be aligned to the coordinate

"iconcenter": The center of the icon will be aligned to the coordinate

anchory (string) Controls how the label is aligned vertically
"top": The top edge of the label is aligned to the coordinate
"center": The center of the label is aligned to the coordinate
"bottom": The bottom edge of the label sits on the coordinate

"iconcenter": The center of the icon will be aligned to the coordinate

Returns

Nothing

SetVisibilityMode (vismode)

Arguments

vismode (string) How the label responds when part of it is off the screen
"movemap": (default) The map will pan to bring the label in to view
"movebubble": (only when the Rawlabel property is set) The position of the bubble will change to ensure it's in the screen

Show()

The point is shown on the CAatPointLayer. This will only take affect after the next map.Init()

Arguments

None

Returns

Nothing


Hide()

The point is hidden on the CAatPointLayer. This will only take affect after the next map.Init()

Arguments

None

Returns

Nothing

CAatBitmapLayer Object

Introduction

Working Example

Dependant Objects

Properties

Methods

Miscellaneous Utility Functions

DecodePolylineArray(encoded, usexy)

Decode an encoded polyline - as returned by the routing API calls.

Arguments

encoded (string) The encoded string
usexy (boolean) If set to "true", the data will be returned in x,y format instead of y,x.

Returns

The coordinates encoded in "encoded" will be decoded into an array [y1,x1,y2,x2, ... yn,xn] (or x/y swapped around if usexy specified).


EncodePolylineArray(points)

Encode an encoded polyline - as returned by the routing API calls.

Arguments

encoded (points) The points to be encoded. These must be objects, each with a .x and .y member.

Returns

The coordinates pass in "points" will be encoded into polyline format and returned.