×
Namespaces

Variants
Actions
(Difference between revisions)

HERE Maps API - How to create a Tooltip

From Nokia Developer Wiki
Jump to: navigation, search
jasfox (Talk | contribs)
(Jasfox -)
jasfox (Talk | contribs)
m (Jasfox - corrected link)
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Draft]]
+
[[Category:Nokia Maps]][[Category:Code Examples]][[Category:JavaScript]]
{{UnderConstruction|timestamp=20120301150325 }}
+
{{Abstract|This article explains how to use CSS styling to create an '''tooltip'''. It is an example of the use of the {{Icode|mouseover}} and {{Icode|mouseout}} events. }}
 
+
{{Abstract|This article explains how to use CSS styling to create an ''Tooltip''. It is an example of the use of the ''mouseover'' and ''mouseout'' events. }}
+
  
 
== Introduction ==
 
== Introduction ==
 +
A '''tooltip''' is a GUI element that appears when the cursor hovers over an associated point of interest. It usually contains some text with more information about the  item concerned, typically a short descriptive label. This leaves the screen uncluttered by hiding these summaries unless the point of interest has focus. It is impossible to click on a tooltip, since the tooltip will disappear as soon as its associated point of interest loses focus. A more common clickable alternative to the tooltip is the {{Icode|InfoBubble}}, which is part of the standard API. Since tooltips are only used on a subset of mapping applications, they do not come as standard as part of the Nokia Maps API, if tooltip functionality is required in an application, it is a simple matter to add tooltips to map markers with a few lines of code.
  
 +
== Coded Example  ==
 +
In HTML, a '''tooltip''' is simply an extra {{Icode|<div>}} element, which is dynamically styled to appear or disappear as associated markers gain or lose focus.
  
 +
=== 1) Inject an extra DIV into the DOM ===
 +
Assume the web page holds a map in the following {{Icode|<div>}} element
 +
<code javascript>
 +
<div id="mapContainer"></div>
 +
</code>
 +
After setting up the map in the usual manner, we need to inject an additional {{Icode|&lt;div&gt;}} into the DOM - this will eventually hold the text of the '''tooltip'''.
 +
<code javascript>
 +
var node = document.createElement("div");
 +
node.className = 'nm_bubble_content';
 +
node.id = 'nm_tooltip';
 +
document.getElementById("mapContainer").appendChild(node);
 +
</code>
  
 +
The {{Icode|&lt;div&gt;}} element above has been given a unique {{Icode|id}}, and therefore can be styled directly  using CSS:
 +
<code css>
 +
#nm_tooltip{
 +
      position: absolute;
 +
      color:blue;
 +
      background:white;
 +
      border: 1px solid black;
 +
      padding-left: 1em;
 +
      padding-right: 1em;
 +
      display: none;
 +
      min-width: 120px;      
 +
}
 +
</code>
 +
The three important CSS attributes here are  {{Icode|background}}, {{Icode|color}} and  {{Icode|display}}.  A fixed {{Icode|background}} colour needs to be set so that the tooltip itself is displayed over the map, {{Icode|color}} will need to contrast with the  {{Icode|background}} of course. The {{Icode|display}} '''must''' initially be set to {{Icode|none}} so that the tooltip  {{Icode|&lt;div&gt;}} element is initially invisible. The other CSS style attributes such as {{Icode|padding}} and {{Icode|border}} can be altered as you see fit. It is also possible to style the {{Icode|&lt;div&gt;}}  using its style class.
  
 +
=== 2) Add an "onHover" effect by handling mouseover and mouseout events. ===
 +
We want to display the tooltip {{Icode|&lt;div&gt;}} whenever a map object which has an associated {{Icode|$tooltip}} attribute gains focus. In order to avoid writing multiple event listeners, we will add a listener to the map itself, and check which object has triggered the event within the listener function. Hiding and displaying the tooltip is only the relevant for objects with a  {{Icode|$tooltip}} attribute, and the presence of this can be determined  through using a {{Icode|undefined}} check
 +
The tooltip is displayed by setting its {{Icode|style}} to {{Icode|display:block}}.
 +
<code javascript>
 +
map.addListener("mouseover", function(evt) {
 +
if (( evt.target.$tooltip === undefined) == false){
 +
document.getElementById("nm_tooltip").style.display ='block';
 +
..etc...
 +
}
 +
});
 +
</code>
 +
Similarly the  tooltip {{Icode|&lt;div&gt;}}  can be hidden whenever an object with a  {{Icode|$tooltip}} attribute loses focus. Optionally a third listener for {{Icode|click}} events could be added here to hide the tooltip if an {{Icode|InfoBubble}} is displayed for example.
 +
<code javascript>
 +
map.addListener("mouseout", function(evt) {
 +
if (( evt.target.$tooltip === undefined) == false){
 +
document.getElementById("nm_tooltip").style.display ='none';
 +
}
 +
});
 +
</code>
  
== Summary ==
+
If the map is ''draggable'', and the tooltip is displayed whilst doing this, the '''tooltip''' will also need to move as the map is moved. This can be achieved by re-firing the marker's {{Icode|mouseover}} event
 +
<code javascript>
 +
map.addListener("drag", function(evt) {
 +
if (document.getElementById("nm_tooltip").style.display == 'block'){
 +
    map.dispatch( new nokia.maps.dom.Event({type: "mouseover", target: map.getObjectAt(evt.displayX, evt.displayY)}));
 +
}
 +
});
 +
</code>
  
 +
===  3) Add a function to move the tooltip to the correct location and add the relevant text. ===
 +
Further styling is required on the tooltip  {{Icode|&lt;div&gt;}} to move it around the map. The bounding box of a marker can be obtained using the {{Icode|target.getDisplayBoundingBoxl()}} method and extracting the x and y coordinates. The x co-ordinate is further offset by half of the width of the  {{Icode|&lt;div&gt;}} so that the centre of the tooltip is aligned with the marker. The text is added by setting the {{Icode|innerHTML}} attribute. Note that it is inefficient to keep traversing the DOM, so a temporary variable is assigned to the DOM node holding the tooltip {{Icode|&lt;div&gt;}}, to avoid searching for it more than once.
  
 +
<code javascript>
 +
map.addListener("mouseover", function(evt) {
 +
if (( evt.target.$tooltip === undefined) == false){
 +
var tooltip = document.getElementById("nm_tooltip");
 +
var target = evt.target;
 +
tooltip.innerHTML =  target.$tooltip;
 +
tooltip.style.display ='block';
 +
tooltip.style.left = target.getDisplayBoundingBox(map).getCenter().x - (tooltip.offsetWidth/2);
 +
tooltip.style.top =  target.getDisplayBoundingBox(map).bottomRight.y + 1;
 +
}
 +
);
 +
</code>
  
''Add categories below. Remove Category:Draft when the page is complete or near complete''
+
===  4) Define a Marker with a  tooltip and add it to the map ===
 +
Having made all the necessary preparations,  a {{Icode|StandardMarker}} can be added in the usual way. The additional {{Icode|$tooltip}} attribute will contain the associated tooltip  text.
 +
<code javascript>
 +
var brandenburgerTorMarker = new nokia.maps.map.StandardMarker(
 +
new nokia.maps.geo.Coordinate(52.516237, 13.377686),
 +
{$tooltip : "Brandenburger Tor"}
 +
);
 +
</code>
 +
Because the tooltip text is displayed within an HTML  {{Icode|&lt;div&gt;}} element, it  is also able to accept formatted HTML as shown:
 +
<code javascript>
 +
var  fernsehturmTooltip = '<div>' +
 +
'<h2>Tooltip with HTML content</h2>' +
 +
'<img width=120 height=90 src=' +
 +
'"http://upload.wikimedia.org/wikipedia/commons/' +
 +
'8/84/Berlin-fernsehturm.JPG" ' +
 +
'alt=""/><br/><b>Fernsehturm, Berlin</b>' +
 +
    '</div>';
 +
var fernsehturmMarker = new nokia.maps.map.StandardMarker(
 +
new nokia.maps.geo.Coordinate(52.520816, 13.409417),
 +
{$tooltip : fernsehturmTooltip}
 +
);
 +
</code>
 +
Obviously the injected HTML can then be further styled as required.
 +
== Summary ==
 +
The result of the [[Media:nm_tooltip.zip|Coded Example]] can be seen below, the cursor is hovering over the marker on the right.
  
 +
[[File:Tooltip.png]]
  
 
{{ArticleMetaData
 
{{ArticleMetaData
|sourcecode= [[Media:nm_tooltip.zip]]  
+
|sourcecode= [[Media:nm_tooltip.zip|Tooltip Example]]  
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
|devices= Google Chrome 16.0.912, Firefox 10.0.2, Internet Explorer 8
+
|devices= Google Chrome, Firefox, Internet Explorer, Opera
 
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Nokia Qt SDK 1.1]) -->
 
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Nokia Qt SDK 1.1]) -->
 
|platform= Web Browser
 
|platform= Web Browser
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
|dependencies=Nokia Maps 2.1.1
+
|dependencies=Nokia Maps 2.2.3
 
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
Line 41: Line 133:
 
}}
 
}}
 
{{SeeAlso|
 
{{SeeAlso|
*   [http://api.maps.nokia.com/ Nokia Maps API]
+
* [http://developer.here.net/javascript_api Nokia Maps API]
*  [http://api.maps.nokia.com/2.1.1/playground/?example&#61;infobubbles Adding an information bubble]
+
*  [http://developer.here.net/apiexplorer/examples/api-for-js/events/event-delegation.html Event Delegation Example]
*  [http://api.maps.nokia.com/2.1.1/playground/?example&#61;infobubblestandardmarker Opening an information bubble on click]
+
*  [http://developer.here.net/apiexplorer/examples/api-for-js/information-bubbles/marker-with-information-bubble.html Opening an information bubble on click]
*  [http://api.maps.nokia.com/2.1.1/playground/?example&#61;kmlfile Loading a KML file]
+
*  [[Nokia Maps API - How to create a tabbed Infobubble]]
 
}}
 
}}

Revision as of 18:37, 3 January 2013

This article explains how to use CSS styling to create an tooltip. It is an example of the use of the mouseover and mouseout events.

Contents

Introduction

A tooltip is a GUI element that appears when the cursor hovers over an associated point of interest. It usually contains some text with more information about the item concerned, typically a short descriptive label. This leaves the screen uncluttered by hiding these summaries unless the point of interest has focus. It is impossible to click on a tooltip, since the tooltip will disappear as soon as its associated point of interest loses focus. A more common clickable alternative to the tooltip is the InfoBubble, which is part of the standard API. Since tooltips are only used on a subset of mapping applications, they do not come as standard as part of the Nokia Maps API, if tooltip functionality is required in an application, it is a simple matter to add tooltips to map markers with a few lines of code.

Coded Example

In HTML, a tooltip is simply an extra <div> element, which is dynamically styled to appear or disappear as associated markers gain or lose focus.

1) Inject an extra DIV into the DOM

Assume the web page holds a map in the following <div> element

	<div id="mapContainer"></div>

After setting up the map in the usual manner, we need to inject an additional <div> into the DOM - this will eventually hold the text of the tooltip.

var node = document.createElement("div");
node.className = 'nm_bubble_content';
node.id = 'nm_tooltip';
document.getElementById("mapContainer").appendChild(node);

The <div> element above has been given a unique id, and therefore can be styled directly using CSS:

#nm_tooltip{
position: absolute;
color:blue;
background:white;
border: 1px solid black;
padding-left: 1em;
padding-right: 1em;
display: none;
min-width: 120px;
}

The three important CSS attributes here are background, color and display. A fixed background colour needs to be set so that the tooltip itself is displayed over the map, color will need to contrast with the background of course. The display must initially be set to none so that the tooltip <div> element is initially invisible. The other CSS style attributes such as padding and border can be altered as you see fit. It is also possible to style the <div> using its style class.

2) Add an "onHover" effect by handling mouseover and mouseout events.

We want to display the tooltip <div> whenever a map object which has an associated $tooltip attribute gains focus. In order to avoid writing multiple event listeners, we will add a listener to the map itself, and check which object has triggered the event within the listener function. Hiding and displaying the tooltip is only the relevant for objects with a $tooltip attribute, and the presence of this can be determined through using a undefined check The tooltip is displayed by setting its style to display:block.

map.addListener("mouseover", function(evt) {
if (( evt.target.$tooltip === undefined) == false){
document.getElementById("nm_tooltip").style.display ='block';
..etc...
}
});

Similarly the tooltip <div> can be hidden whenever an object with a $tooltip attribute loses focus. Optionally a third listener for click events could be added here to hide the tooltip if an InfoBubble is displayed for example.

map.addListener("mouseout", function(evt) {
if (( evt.target.$tooltip === undefined) == false){
document.getElementById("nm_tooltip").style.display ='none';
}
});

If the map is draggable, and the tooltip is displayed whilst doing this, the tooltip will also need to move as the map is moved. This can be achieved by re-firing the marker's mouseover event

map.addListener("drag", function(evt) {	 
if (document.getElementById("nm_tooltip").style.display == 'block'){
map.dispatch( new nokia.maps.dom.Event({type: "mouseover", target: map.getObjectAt(evt.displayX, evt.displayY)}));
}
});

3) Add a function to move the tooltip to the correct location and add the relevant text.

Further styling is required on the tooltip <div> to move it around the map. The bounding box of a marker can be obtained using the target.getDisplayBoundingBoxl() method and extracting the x and y coordinates. The x co-ordinate is further offset by half of the width of the <div> so that the centre of the tooltip is aligned with the marker. The text is added by setting the innerHTML attribute. Note that it is inefficient to keep traversing the DOM, so a temporary variable is assigned to the DOM node holding the tooltip <div>, to avoid searching for it more than once.

map.addListener("mouseover", function(evt) {
if (( evt.target.$tooltip === undefined) == false){
var tooltip = document.getElementById("nm_tooltip");
var target = evt.target;
tooltip.innerHTML = target.$tooltip;
tooltip.style.display ='block';
tooltip.style.left = target.getDisplayBoundingBox(map).getCenter().x - (tooltip.offsetWidth/2);
tooltip.style.top = target.getDisplayBoundingBox(map).bottomRight.y + 1;
}
);

4) Define a Marker with a tooltip and add it to the map

Having made all the necessary preparations, a StandardMarker can be added in the usual way. The additional $tooltip attribute will contain the associated tooltip text.

var brandenburgerTorMarker = new nokia.maps.map.StandardMarker(
new nokia.maps.geo.Coordinate(52.516237, 13.377686),
{$tooltip : "Brandenburger Tor"}
);

Because the tooltip text is displayed within an HTML <div> element, it is also able to accept formatted HTML as shown:

var  fernsehturmTooltip = '<div>' +
'<h2>Tooltip with HTML content</h2>' +
'<img width=120 height=90 src=' +
'"http://upload.wikimedia.org/wikipedia/commons/' +
'8/84/Berlin-fernsehturm.JPG" ' +
'alt=""/><br/><b>Fernsehturm, Berlin</b>' +
'</div>';
var fernsehturmMarker = new nokia.maps.map.StandardMarker(
new nokia.maps.geo.Coordinate(52.520816, 13.409417),
{$tooltip : fernsehturmTooltip}
);

Obviously the injected HTML can then be further styled as required.

Summary

The result of the Coded Example can be seen below, the cursor is hovering over the marker on the right.

Tooltip.png

Article Metadata
Code Example
Source file: Tooltip Example
Tested with
Devices(s): Google Chrome, Firefox, Internet Explorer, Opera
Compatibility
Platform(s): Web Browser
Dependencies: Nokia Maps 2.2.3
Article
Keywords: Nokia Maps, JavaScript, Tooltip, CSS
Created: jasfox (01 Mar 2012)
Last edited: jasfox (03 Jan 2013)
190 page views in the last 30 days.