Mapspace API Reference

Adding tooltips

Tooltips are based on a plug-in for JQuery called Popper.js that is included in Mapspace API:

To add support for tooltips we must use the new Mapspace.control.Tooltip.

Let's see it through an example. This is the function that creates a button with a tooltip:

Mapspace.strings[Mapspace.Languages.EN_GB]['myButton-tooltip#title'] = 'Executes a process';
Mapspace.strings[Mapspace.Languages.ES_ES]['myButton-tooltip#title'] = 'Ejecuta un proceso';

var button = new Mapspace.control.Button({
	target: 'container',
	label: 'Execute',
	tooltip: new Mapspace.control.Tooltip({
		globalizationKey: 'myButton-tooltip',
		placement: Mapspace.control.TooltipPlacement.RIGHT,
		boundary: Mapspace.control.TooltipBoundary.WINDOW
	}),
	handler: function() {
		console.log('Clicking in the button');
	}
});

AS you can see the options to construct a Button contain a tooltip option that is an instance of Mapspace.control.Tooltip. The tooltip object behaves like a control. It has its own globalizationKey value to deal with translations, and you can customize it with options. Check the Mapspace.control.TooltipOptions typedef to learn the options you can pass it. The main options to remember here are:

  • title: Default title value if globalizationKey attribute isn't present. If a function is given, it will be called with its this reference set to the element that the tooltip is attached to. Default is undefined meaning that the values will be taken from the globalizationKey and translation.
  • globalizationKey: A key for searching translation of strings. If this is provided and also a title, this takes precedence. If we pass a value we must ensure that the key is registered in the Mapspace.strings object.
  • placement: How to position the tooltip - auto | top | bottom | left | right. When auto is specified, it will dynamically reorient the tooltip. When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The this context is set to the tooltip instance. Default is 'top'.
  • html: Allow HTML in the tooltip. If true, HTML tags in the tooltip's title will be rendered in the tooltip. If false, jQuery's text method will be used to insert content into the DOM. Use text if you're worried about XSS attacks. Default is false.
  • boundary: Overflow constraint boundary of the tooltip. Accepts the values of 'viewport', 'window', 'scrollParent', or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's preventOverflow docs. Default is 'scrollParent'.

As you can see the control only needs to take care of the translations for its own strings and not for the translation of the tooltip. The tooltip is translated through the use of a globalizationKey. We need to ensure that Mapspace.strings global object contains entries for the given globalizationKey. For a tooltip, the text of the tooltip is set through the title as in the previous example:

Mapspace.strings[Mapspace.Languages.EN_GB]['myButton-tooltip#title'] = 'Executes a process';
Mapspace.strings[Mapspace.Languages.ES_ES]['myButton-tooltip#title'] = 'Ejecuta un proceso';

Each entry in the Mapspace.strings global object must follow a name pattern like globalizationKey#subkey where subkey is a given name for each string in the control to be translatable. For example, for a tooltip, the text in the tooltip corresponds with the subkey title and the label of the button is translated using the subkey label.

It is possible to use HTML texts in tooltips, as follows:

Mapspace.strings[Mapspace.Languages.EN_GB]['myButton-tooltip#title'] =
	'<em>Execute a process</em>' +
	'<br>' + 
	'<ol>' +
		'<li>Click once in this button.</li>' +
		'<li>Wait a few seconds.</li>' +
		'<li>The process will be completed!</li>' +
	'</ol>';
Mapspace.strings[Mapspace.Languages.ES_ES]['myButton-tooltip#title'] = 
	'<em>Ejecuta un proceso</em>' +
	'<br>' + 
	'<ol>' +
		'<li>Haz clic una vez en este control.</li>' +
		'<li>Espera unos segundos.</li>' +
		'<li>Proceso completado!</li>' +
	'</ol>';