Documentation

Requirements

To use the mapApp object, your project needs to meet the following requirements:

• the svg root element needs to have a viewBox attribute set (e.g. viewBox="0 0 1024 768")
• you need to link to the following scripts in your SVG header to use the mapApp object: mapApp.js, helper_functions.js; please note, that not all of the functions in these files are needed. The depencies to functions in the file "helper_functions.js" are listed below.
• you need to include the global variable "myMapApp" of type "mapApp" into one of your js files, (e.g. var myMapApp = new mapApp(false,undefined);)
• to use the tooltips, you need to create an empty <g/> element in an appropriate position of your document's DOM (e.g. <g id="tooltips" />)
• it is recommended to place a background rectangle behind your SVG application to receive events on the root element level

Features

• client to viewBox coordinate transformation
• bridges the missing .getScreenCTM() method in ASV3
• provides tooltip functionality (multiline tooltips; tooltips from child elements initialized from the parent element; tooltips from attributes in a foreign namespace; tooltips follow or don't follow the mouse; tooltips may update the content during mousemove)
• the mapApp object can serve as a container to hold additional project specific properties that need to be made available globally. The mapApp object needs to be made global.

Dependencies on external functions

1. mapApp.js:
   • all of the objects and functions in this file are necessary
2. helper_functions.js:
   • all the global variables at the top of the file
   • function getTransformToRootElement(node) provided by Kevin Lindsey

Constructor

The following constructor function creates the mapApp object:

var myMapApp = new mapApp(adjustVBonWindowResize,resizeCallbackFunction);

The instance myMapApp should be made global in your ECMAScript file and should be named myMapApp in order to make it accessible to all functions or objects in your SVG web application. Most examples on carto.net assume that this object is present. The instance should be initialized by the onload event attribute.

Example:

myMapApp = new mapApp(true,svgResized);
		

The arguments are the following:

1. adjustVBonWindowResize (Boolean):
   Determines whether the mapApp object should update the viewBox always to the window.innerWidth and window.innerHeight values after the SVG viewing area was resized
2. resizeCallbackFunction (function):
   an optional callback function that is called after each resize. Note that this function is not called during mapApp initialization, it is called the first time the user resizes the SVG viewing area

Properties

• .navigator:
  holds a string about the SVG UA in use. Potential values are: Batik, Adobe, Mozilla, Opera, Safari, MSIE - for historical/compatibility reasons all webkit based browsers (e.g. Google Chrome) are reported as "Safari"
• .tooltipsEnabled:
  holds a boolean value that indicates whether tooltips are enabled in this application or not. Default is false. This value is automatically set to true after tooltips have been initialized. (see below)
• .innerWidth:
  the number of pixels of the width of the UA's window (also called viewPort width). Wrapper around different methods to get the viewPort in pixels
• .innerHeight:
  the number of pixels of the height of the UA's window (also called viewPort height). Wrapper around different methods to get the viewPort in pixels
• .Windows:
  an initially empty array that can later contain references to carto.net Window objects
• .checkBoxes:
  an initially empty array that can later contain references to carto.net checkbox objects
• .tabgroups:
  an initially empty array that can later contain references to carto.net tabgroup objects
• .textboxes:
  an initially empty array that can later contain references to carto.net textbox objects
• .buttons:
  an initially empty array that can later contain references to carto.net button objects
• .selectionLists:
  an initially empty array that can later contain references to carto.net selectionList objects
• .comboboxes:
  an initially empty array that can later contain references to carto.net combobox objects
• .sliders:
  an initially empty array that can later contain references to carto.net slider objects
• .scrollbars:
  an initially empty array that can later contain references to carto.net scrollBar objects
• .colourPickers:
  an initially empty array that can later contain references to carto.net colourPicker objects
• .htmlAreas:
  an initially empty array that can later contain references to carto.net htmlArea objects
• .tables:
  an initially empty array that can later contain references to carto.net table objects

Methods

• .calcCoord(evt,ctmNode):
  converts the coordinates of the evt object to the coordinate system where the event happened or to the given ctmNode. It takes the viewBox and all nested transformations to the evt or ctmNode into account. The first parameter is the evt object that contains the properties evt.clientX and evt.clientY. The optional second parameter is a node reference pointing to an existing SVG element in the DOM. This is useful in cases where the user wants to transform the coordinates not to the hierarchy where the evt happened but to a different position in the DOM hierarchy (e.g. used for the tooltip functionality within this object). The return value is of type svgPoint. Coordinates can be extracted by using the properties .x and .y of this svgPoint return object.
• .adjustViewBox():
  sets the viewBox of the svg root element to the values of this.innerWidth and this.innerHeight. Useful for resetting GUI elements after window was resized
• .initTooltips(groupId,tooltipTextAttribs,tooltipRectAttribs,xOffset,yOffset,padding):
  initializes the tooltip functionality in this mapApp instance by creating the necessary text and rectangle nodes. The parameters are as follows: groupId of type string indicating the unique id of the group in the DOM where the tooltip geometry will be added (note that this group should be typically at the end of the DOM, to ensure that tooltips are displayed on top of other elements); tooltipTextAttribs of type Array of literals containing all presentation attributes of the tooltip text (should at least contain the attrib "font-size"); tooltipRectAttribs of type Array of literals containing all presentation attributes of the tooltip rectangle displayed below the tooltip text (should generally contain fill and/or stroke attributes); xOffset of type number describing the horizontal offset from the mouse cursor in viewBox coordinates; yOffset of type number describing the vertical offset from the mouse cursor in viewBox coordinates; padding of type number describing the padding in viewBox coordinates to create the margins around the tooltiptext bounding box

  Example:

  //tooltip styles
  var tooltipTextStyles = {"font-family":"Arial,Helvetica","fill":"dimgray","font-size":12};
  var tooltipRectStyles = {"fill":"white","stroke":"dimgray"};
  myMapApp.initTooltips("toolTip",tooltipTextStyles,tooltipRectStyles,10,20,3);

• .addTooltip(tooltipNode,tooltipTextvalue,followmouse,checkForUpdates,targetOrCurrentTarget,childAttrib):
  adds the necessary mouse events and tooltip attributes in the attrib namespace to the element where the tooltip should be displayed. The tooltip text can either be provided as a parameter in this method or the value can be read from the attrib attrib:tooltip="This is a tooltip". The arguments are the following: tooltipNode of type string containing the unique id to the element in the DOM where the tooltip should be added; tooltipTextvalue of type string describing the value of the tooltip text (you can use undefined if the value is already specified in a tooltip attribute); followmouse of type boolean indicating whether the tooltip should follow the mouse (true) or not (false) if the user moves the mouse over a bigger object; checkForUpdates of type boolean indicating whether the tooltip display method should look for updated attrib:tooltip="This is a tooltip" values or not (this is necessary if one wants to constantly or purposely update the content of the tooltip text if the user moves the mouse, e.g. for displaying coordinates or lenght of a line); targetOrCurrentTarget of type string containing the values "currentTarget" (useful in most cases: the tooltip attribute is read from the element where the mouse event occured) or "target" (useful if the tooltip mouse events happen on a parent group but the values are specified in tooltip attributes of the children of the parent node); childAttrib of type string indicating the name of the attrib containing the tooltip text to be displayed (note that this attribute name needs to be in the namespace attrib as defined in the variable attribNS of the file; this is useful if one wants to display different tooltip texts based on non-graphical GIS attributes (e.g. population, name, etc.)) helper_functions.js

  Examples:

  myMapApp.addTooltip("yellowRect",undefined,false,false,"currentTarget",undefined);
  myMapApp.addTooltip("salmonRect",undefined,true,false,"currentTarget",undefined);
  myMapApp.addTooltip("dimgrayRect",undefined,true,true,"currentTarget",undefined);
  myMapApp.addTooltip("kantone",undefined,true,false,"target","name");
  

• .enableTooltips():
  enables the tooltips if they had been disabled. This effects globally the whole application.
• .disableTooltips():
  disables the tooltips. This effects globally the whole application.

Version history

• 0.99 (2003-xx): initial version (original creation date can't be reconstructed)
• 1.0 (2005-06-01): initial documented version, tooltip functionality was added to the mapApp object
• 1.1 (2005-06-15): added properties this.innerWidth, this.innerHeight (wrapper around different behaviour of viewers), added method ".adjustViewBox()" to adjust the viewBox to the this.innerWidth and this.innerHeight of the UA's window
• 1.2 (2006-10-06): added two new constructor parameter "adjustVBonWindowResize" and "resizeCallbackFunction". If the first parameter is set to true, the viewBox of this mapApp will always adjust itself to the innerWidth and innerHeight of the browser window or frame containing the SVG application; the "resizeCallbackFunction" can be of type "function", later potentially also of type "object". This function is called every time the mapApp was resized (browser/UA window was resized). It isn't called the first time when the mapApp was initialized; added a new way to detect resize events in Firefox which didn't implement the SVGResize event so far; added several empty array to hold references to carto.net GUI widgets
• 1.2.1 (2007-01-09): fixed an issue in the method .updateTooltip() for cases where an element did not have a tooltip text, attribute or an empty string. Now, the tooltip disappears for these elements instead of triggering a javascript error.
• 1.2.2 (2007-04-03): improved the navigator detection to correctly handle Webkit/Safari; added this.htmlAreas and this.tables as new arrays to hold GUI component references
• 1.2.3 (2011-10-02): improved the navigator detection to correctly handle MSIE

Credits

• Kevin Lindsey for providing his ViewBox object
• Michel Hirtzler for ideas from his examples
• Simon Shutter for pointing out the problem with the error in case an element did not have the tooltip attribute
• other people on the svg-developers list