Write a Mapbender module
From MapbenderWiki
This is a tutorial for Mapbender 2.7 and newer (note: this equals trunk at the moment, July 2009).
Contents |
Preface
In Mapbender, modules (or: application elements) are contained within applications (GUIs). You can configure a module in the edit application elements dialogue. In general, modules consist of a DOM element, JavaScript file(s) that add behaviour to the DOM element, and configurations in Element vars.
Since version 2.7, Mapbender uses the JQuery library to add behaviour to its application elements specified in the administration dialogue. This concept has been described in Testbaudson's blog.
This tutorial tells you how to write the JavaScript that adds behaviour to your DOM elements.
use existing jQuery plugins
You can specify the filename and path to your plugin in the edit application elements dialogue under "module". Files listed here are only included once per application.
However you also have to create a JavaScript file that executes your plugin.
Mapbender.events.init.register(function () {
$(selector).plugin(parameters);
});
Read more about the init event here.
create new, dynamic jQuery plugins (see map.php)
In the JavaScript file specified in the edit application elements dialogue, you only need to write the content of your jQuery plugin.
Note: Your application element must have a corresponding DOM element
(HTML tag in edit application elements dialogue). The jQuery
plugin only applies behaviour for DOM elements.
The plugin itself is located in map.php and looks something like this
$.fn.element_id = function (options) {
return this.each(function () {
// your JS file will be included here
});
}
This means, that the jQuery plugin and the DOM element have the same name, the plugin is created dynamically. map.php also applies the plugins to the corresponding DOM element by the following line
$('#$e_id').$e_id(options);
which is executed for each module.
Note: For backwards compatibibility, you need to add your element to the
constant MODULES_NOT_RELYING_ON_GLOBALS in the file core/system.php.
Only elements listed here will use the new syntax for now!
An exception is made for files in the http/plugins folder. They don't have to
be added to the constant.
Your JavaScript file
Element properties
The element properties like id, target etc. are passed to your code in a JavaScript object called options. You can address a property like this
options.id options.target options.top options.left options.width options.height options.src options.$target // NEW: all targets in a jQuery object
This list might be expanded in the future.
Note: There is no longer the need to use PHP scripts to retrieve the JavaScript element vars.
However, PHP or CSS element vars still need to be added manually!
JavaScript Element variables
The JavaScript Element vars are also passed to your code in the variable called options. You can address an Element var via
options.element_var_name
Note: Make sure your element vars are not named like the element properties listed above!
You can set default values for mandatory element vars like this
if (options.element_var_name === undefined) {
options.element_var_name = default_value;
}
Scope
As the code you produce will end up in a jQuery plugin, the variable this always refers to the DOM element specified in the edit application elements dialogue. You no longer have to retrieve the DOM node via
document.getElementById('$e_id')
You can also convert this to a jQuery object by adding
var $this = $(this);
at the top of your script. Then you are able to use all the wonderful jQuery functionality like event binding (even within other constructors)
$this.click(function () {
// this still refers to the DOM element
alert(this.id)
})
Note: There are no more global variables! Variables are either private (= accessible within the object context),
or public (= part of the module's API). Instantiate a variable with either var or this.name.
If you want to let other module access functionality of your module, you need to supply an API functionality,
see below.
The attributes field of the edit application elements dialogue no longer holds the event handlers!
Documentation
Read here about how to document your module.
