.. module:: mapstore.createplugin
   :synopsis: MapStore Plugin development.

.. _mapstore.createplugin:

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 :file:`$TRAINING_ROOT/src` and can be accessed through 

.. code-block:: ruby
   :linenos:
  
   $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 :file:`mapstore/mapcomposer/app/static/externals/gxp/src/script/plugins`
  * Include the path of the newly created file into the file :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:
     * :file:`mapstore/mapcomposer/app/staic/config/mapStoreConfig.js` ; If you need the plugin to be available from MapComposer
     * :file:`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 <http://demo.geo-solutions.it/share/comunebz/print/HelloMapStore.js>`__

HelloMapStore Plugin
^^^^^^^^^^^^^^^^^^^^

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

.. code-block:: ruby
   :linenos:

    /**
     * @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 :file:`@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 :file:`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 :file:`buildjs.cfg` file

 .. code-block:: ruby
   :emphasize-lines: 12
   :linenos:
   
    [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 :file:`viewerConfig.js`

 .. code-block:: ruby
   :emphasize-lines: 4,5,6,7
   :linenos:

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

 The properties to add to the list are explained here below:
  #. **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.
  #. **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 :file:`$TRAINING_ROOT/src/SKShell.bat`.

  A command shell window should pop-up as depicted in the figure below
  
  .. figure:: img/sdk_shell.png


* Go to the :file:`mapstore` folder and run the following command

 .. code-block:: ruby
   :linenos:
   
   ant

* Wait until the build has been successfully completed

  .. figure:: img/sdk_shell_1.png


* Be sure that:

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

* Go to the :file:`mapstore` folder and run the following command

 .. code-block:: ruby
   :linenos:
   
   ant debug

* Once you see the message below

  .. figure:: img/sdk_shell_2.png


  Access to `MapStore <http://localhost:8081/?config=viewerConfig>`__ (:file:`http://localhost:8081/?config=viewerConfig`)

  .. figure:: img/hello_mapstore.png

  
  .. note:: Notice the *hello* button into the top ToolBar.  

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

  .. figure:: img/hello_mapstore_1.png