Supplying API functionality in your modules

From MapbenderWiki

This is a tutorial for Mapbender 2.7 and newer (note: this equals trunk at the moment, July 2009).

Contents 1 Create an API object 1.1 Simple approach 1.2 Advanced approach 2 Add your API object to Mapbender 2.1 jQuery style (access via DOM, recommended) 2.2 access via object (deprecated) 3 Documentation

Create an API object

Simple approach

If you want to supply API functionality for your module, create an object with all the methods and attributes you want to supply. You can add a simple object like this

var myApiObject = {
   apiFunction: function () {
      // this refers to the element's DOM node
      alert(this.id);
   }
};

Other modules will be able to access your method via the API.

Advanced approach

For more sophisticated modules, you need to use a constructor function to create an object, because you might want to use inheritance or private methods

// this is the constructor, you can also pass the options to it
var MyApiConstructor = function (options) {
   // a public method
   this.apiFunction = function () {
   };

   // a private method
   var notAnApiFunction = function () {
   };
};

Other modules will be able to access your method via the API. However, the private method is inaccessible.

Be aware that this within another constructor no longer necessarily references to your DOM element. I advise creating a $this variable as described in the Write a Mapbender module tutorial.

Add your API object to Mapbender

jQuery style (access via DOM, recommended)

Again you can use the mapbender plugin to set the API object.

$this.mapbender(myApiObject);

If you have used the advanced approach, make sure to instantiate an API object with the new operator!

$this.mapbender(new MyApiConstructor(params));

access via object (deprecated)

Add your object to the Mapbender.modules array

Mapbender.modules[options.id] = $.extend(myApiObject, Mapbender.modules[options.id]);

or create a new API object form your constructor

Mapbender.modules[options.id] = $.extend(new MyApiConstructor(params), Mapbender.modules[options.id]);

Documentation

Read here about how to document your module.