Create a new Plugin/Widget

This section illustrates how to create a new simple plugin for MapStore.

Prerequisites

All the steps described below are intended to be executed against the MapStore source code.

The source code is located into the folder $TRAINING_ROOT/src and can be accessed through

$TRAINING_ROOT\src\SKShell.bat

MapStore Plugin development

In order to develop a plugin for MapStore, few easy steps have to be performed

• Create a new JavaScript file inside the folder mapstore/mapcomposer/app/static/externals/gxp/src/script/plugins

• Include the path of the newly created file into the file mapstore/mapcomposer/buildjs.cfg in order to link the dependency to the build

• Include the plugin in one or both MapStore configuration files at the following paths:

  • mapstore/mapcomposer/app/staic/config/mapStoreConfig.js ; If you need the plugin to be available from MapComposer
  • mapstore/mapcomposer/app/staic/config/viewerConfig.js ; if you need the plugin available from MapViewer

In the next section we will see a step by step process to add a new plugin to MapStore.

The full code of the example plugin is available at:

HelloMapStore.js

HelloMapStore Plugin

• Create the HelloMapStore.js file at mapstore/mapcomposer/app/static/externals/gxp/src/script/plugins/HelloMapStore.js

 /**
  * @requires plugins/Tool.js
  */

 /** api: (define)
  *  module = gxp.plugins
  *  class = HelloMapStore
  */

 /** api: (extends)
  *  plugins/Tool.js
  */
 Ext.namespace("gxp.plugins");

 /** api: constructor
  *  .. class:: HelloMapStore(config)
  *
  *    Plugin for adding a new group on layer tree.
  */
 gxp.plugins.HelloMapStore = Ext.extend(gxp.plugins.Tool, {

     /** api: ptype = gxp_addgroup */
     ptype: "gxp_hellomapstore",
     /**
      * api: method[addActions]
      */
     addOutput: function() {
         var apptarget = this.target;

         var out = gxp.plugins.HelloMapStore.superclass.addOutput.apply(this, [{
             text:'hello',
             disabled: false,
             handler: function() {
                 Ext.Msg.show({
                     title : "hello",
                     msg : "Hello Mapstore!!"
                 });
             },
             scope: this
         }]);

         return out;
     }

 });
 Ext.preg(gxp.plugins.HelloMapStore.prototype.ptype, gxp.plugins.HelloMapStore);

Note

The comment @requires plugins/Tool.js allows the testing tools to include the plugins dependencies in the correct order.

• Add the plugin to the build procedure configuration files.

  The new plugin must be available among the application dependencies. In order to do that, you must include the file path into mapstore/mapcomposer/buildjs.cfg

  Note

  If it’s a gxp plugin type, after the building phase all the separated files will be compressed into a unique gxp.js file.

  To add your own plugin, just write the path of the new JavaScript file into the “include” list of the buildjs.cfg file

 [gxp.js]
 root = app/static/externals/gxp/src/script
 license = license-app.js

 include =
     util.js
     menu/LayerMenu.js
     widgets/LayerUploadPanel.js
     ...
     plugins/RemoveOverlays.js
     ...
     plugins/HelloMapStore.js
     locale/en.js
     locale/fr.js

• Add the plugin to the map.

  It is possible to add a plugin to the application in several ways. The easiest one is through a specific entry “customTools” of the main configuration file viewerConfig.js

...
"customTools":[
 ...
   {
     "ptype": "gxp_hellomapstore",
     "outputTarget":"paneltbar"
   }
   ...
]
...

The properties to add to the list are explained here below:

1. ptype; specifies the type of the component. It is registered inside the component JavaScript file and definition. It must be present as element of the component code.
2. outputTarget; represent the reference of the component which will be the container of the new plugin, the panelbar in the example above.

Test the Plugin

Once the steps above have been completed:

• Run the command $TRAINING_ROOT/src/SKShell.bat.

  A command shell window should pop-up as depicted in the figure below

  

• Go to the mapstore folder and run the following command

ant

• Wait until the build has been successfully completed

  

• Be sure that:

  1. The Tomcat instance1 is running
  2. The Tomcat instance2 is not running (otherwise you will experience a TCP port clash)

• Go to the mapstore folder and run the following command

ant debug

• Once you see the message below

  

  Access to MapStore (http://localhost:8081/?config=viewerConfig)

  

  Note

  Notice the hello button into the top ToolBar.

• Click on the new hello button to interact with the newly created plugin