.. _widget-how-to-create:

=============================
 How to create a new widget
=============================

Can't find a certain feature you want ?  You think that feature should be
included ?  You just saw a cool new tool in an external library ?  Then, you can
easily create and contribute it !

Simply follow this procedure when creating a new widget.  This won't tell you
exactly *what* to do, but *how* to do it.


1) Plan your widget
--------------------
List the things your widget should do.  Look for similar functionnalities in
existing web-mapping application to work from.


2) Inform the developers
-------------------------
Use the
`Developers mailing list <http://lists.osgeo.org/mailman/listinfo/geoprisma-dev>`_ 
to let the developers know of your intentions.


3) Create a ticket
-------------------
Create a new ticket in
`TRAC <http://trac.osgeo.org/geoprisma/>`_ 
with complete details of the new features the widget should have.


4) Directory
-------------
Create a new directory for you widget (must be in lowercase).  That same
name will always be use thereafter so choose it wisely.  You can also create a
:ref:`widget-basics-sub-directories-label`
structure.


5) Copy required files
-----------------------
Copy all files from the
:ref:`widget-basics-sample-widget-label`
to your new widget directory.  Change their name respecting the case, for
example :

* sample.php -> yourwidget.php
* Sample.xslt -> YourWidget.xslt

You might have copied the hidded svn folder too.  Simply remove it if you did.

.. _widget-how-to-create-php-file:

6) *.php* file (mandatory)
---------------------------
Edit the php file.  Here's what you need to change :

:class name:   Change the class name to your widget name (case sensitive)
:class action: Set the widget action.  Possible values are :
  
  * create
  * read
  * update
  * delete

:type:
  Set the widget type, which is the name of the widget in lowercase.  If you
  use the :ref:`widget-basics-sub-directories-label` structure, use the
  complete name (with '_').

.. seealso::

   :ref:`concepts-action-label`


7) *.xslt* file (mandatory)
----------------------------
Make the following changes in YourWidget.xslt
	

:Namespace definition:
  Define the namespace of your widget.  Example :

  .. code-block:: xml

     xmlns:yourwidget="http://opensafemap.org/yourwidget"
     
:Apply the namespaces to templates:
  Set the namespace of your widget to all templates (functions) in this file.
  Example :

  .. code-block:: xml

     <xsl:template name="yourwidget:printWidgetSource">


:Included JS and CSS (optional):
  In the printWidgetSource template, you define the external js/css files
  your widget includes.  Change the 

  .. code-block:: xml

     <xsl:text>...</xsl:text>

  portion for each external script/link your widget needs.  Example (script) :

  .. code-block:: xml

     <script>
       <xsl:attribute name="src" >
         <xsl:value-of select="$g_widgets_url"/>
         <xsl:text>/yourwidget/YourWidget.js</xsl:text>
       </xsl:attribute>    
     </script>

  Example (link) :

  .. code-block:: xml

     <link rel="stylesheet" type="text/css" >
       <xsl:attribute name="href" >
         <xsl:value-of select="$g_widgets_url"/>
         <xsl:text>/yourwidget/YourWidget.css</xsl:text>
       </xsl:attribute>
     </link>


8) *Globals.xslt* file (mandatory)
-----------------------------------
The global file is located in the
*[your_geoprisma_dir]*/src/client/templates/inc directory.

:Namespace definition:
  Add a namespace for your widget.  Example :

  .. code-block:: xml

     xmlns:yourwidget="http://opensafemap.org/yourwidget"

:Extension prefix:
  Add the extension prefix of your widget to the 

  .. code-block:: xml

     extension-element-prefixes


:printAllWidgetSources:
  Locate this template and the following lines to it :

  .. code-block:: xml

     <xsl:when test="$WidgetType='yourwidget'">
       <xsl:call-template name="yourwidget:printWidgetSource"/>
     </xsl:when>

:printAllWidgetExecutions:
  Locate this template add the following lines to it :


  .. code-block:: xml

     <xsl:when test="$WidgetType='yourwidget'">
       <xsl:call-template name="yourwidget:printWidgetExecution">
         <xsl:with-param name="pWidgetName" select="$WidgetName" />
         <xsl:with-param name="pMapName" select="$pMapName" />
       </xsl:call-template>
    </xsl:when>


9) *.js* file(s) (optional)
----------------------------

* Skip this task if your widget doesn't require any *.js* file.
* The *YourWidgetName.js* file should be used for *namespace* definition only,
  but it is not mandatory to do so.
* Create as much *MyWidgetClass.js* as you need, one file per class.  This is
  not mandatory too, it's just a sugestion of doing so.
* All theses files must be included in your *.xslt* file, in the 
  *printWidgetSource* template.


10) *.css* file (optional)
---------------------------

If your widget needs any specific styling, put it in the *.css* file, else 
simply remove it.



11) Create one or more samples (mandatory)
-------------------------------------------
Create a new sample demonstrating the use of your widget.  If your widget has
many options, create a sample directory with many sub-directories of your widget
with the use of those different options.

.. seealso:: 

   :ref:`how-to-make-a-new-sample-label`


12) *Template.xslt* file (mandatory)
-------------------------------------
Edit your sample's
:ref:`create-your-own-geoprisma-project-template-label`
.

13) *Config* (mandatory)
-------------------------
Edit your sample's
:ref:`config-drivers-label`
.  Use the *yoursample.xml* file to do so.

14) *.rst* file (mandatory)
----------------------------
Document your widget.

.. seealso::

   http://sphinx.pocoo.org/