.. _widget-basics-label:

=============================
 Basic knowledge
=============================

This topics covers the basic knowledge of widgets, like what files are used by
a widget, what functions are commonly used, etc.

Be sure to have read and understood the following topic before moving on :
:ref:`concepts-widget-label`


.. _widget-basics-global-label:

Global view
-----------------------------

* All widgets are in the *[your_geoprisma_root_directory]*/src/client/widgets
  directory.
* There is a
  :ref:`widget-basics-sample-widget-label`
  from which you can copy the files to
  start from.  It's in the *sample* directory of the widgets directory.
* Widgets can also be placed in a more complex structure of
  :ref:`widget-basics-sub-directories-label`
  .
* **Widget names are case sensitive**.  Lowercases values must stay in
  lowercase in all files.
* Only the widgets linked to the *Resources* the user has access to are
  included.  For the purpose of simplification, these widgets will be called
  *included widgets* in this topic.
* All widgets have the 3 following xsl templates (functions) :

  * :ref:`widget-basics-printWidgetSource-label`
  * :ref:`widget-basics-printWidgetExecution-label`
  * :ref:`widget-basics-drawWidgets-label`

* The 
  :ref:`concepts-globals-xslt-label`
  file have some very useful functions you can use in your widget.


.. _widget-basics-sample-widget-label:

Sample widget
----------------
Here's the file structure of the *sample* widget.

  .. code-block:: xml

     [your_geoprisma_root_directory]/src/client/widgets/sample :
       MySampleClass.js
       Sample.css
       Sample.js
       sample.php
       Sample.rst
       Sample.xslt


.. _widget-basics-sub-directories-label:

Sub-directories
----------------
Widgets are not limited to a single directory structure.  You can create an
infinite architecture of sub-directories in which to put your widgets.  This 
comes in handy when similar widgets have to share common files of classes or 
simply to group them.  For examples, here's the structure of the *editfeature*
directory from the *widgets* directory :

  .. code-block:: xml

     editfeature
       ./create
         ./Create.js
         ./create.php
         ./Create.txt
         ./Create.xslt
       ./delete
         ./DeleteFeature.js
         ./delete.php
         ./Delete.xslt
         ./Delete.js
         ./Delete.txt
       ./update
         ./Update.js
         ./update.php
         ./Update.txt
         ./Update.xslt
       ./EditFeature.js

In the *config*, widgets using a sub-directories structure are defined a bit
differently.  They must have their whole path as *type*, with slashes '/'
replaces by '_', like this :

  .. code-block:: xml

     <editfeature_create>
       <name>MyEditFeatureCreateWidget</name>
       <options>
         <geometrytype>LineString</geometrytype>
         <featurepanel>MyFeaturePanelWidget</featurepanel>
        </options>
     </editfeature_create>


.. _widget-basics-printWidgetSource-label:

printWidgetSource
------------------

* Called only **once per included widget type**.
* Called by the *printAllWidgetSources* function in the *template* file.
* Main purposes :

  * Include *once* the files required by the widget, like javascript and
    stylesheet (css) files.
  * Create javascript variables common to all widgets of this
    type.  For example, an javascript array variable could be defined in
    this function as a container for all the widgets of this type.


.. _widget-basics-printWidgetExecution-label:

printWidgetExecution
---------------------

* Called **once per included widget**.
* Called by the *printAllWidgetExecutions* function in the *template* file.
* Main purposes :

  * Create the objects used by each widget of this type.  In more details,
    if you want to have multiple *widget* (of the same type) in your
    application, the code in this section is parsed X times ( where X is the
    number of *included widgets* in the application).


.. _widget-basics-drawWidgets-label:

drawWidget / drawWidgets
-------------------------
Here, you have a choice of using either one or even both, it's
completely up to you.  The *drawWidgets* method is much more 
user-friendly though.  Nevertheless, we'll see both methods and what they
do and imply.

* Theses functions are called in the *template* file.
* Main purposes : determine *where to put* the actual widgets in the *ui*.

.. centered:: **drawWidget**

Designed to draw **one** widget only, by giving the *widget's name*
from the config as the argument.  This requires to manually loop through
the widgets in the *template* file.  Here's an example :

  .. rubric:: drawWidget function from the *Widget.xslt* file :

  .. code-block:: xml

     <xsl:template name="sample:drawWidget">
       <xsl:param name="pWidgetName" />
         objGPWidget<xsl:value-of select="$pWidgetName" />
     </xsl:template>

  .. rubric:: drawWidget call from the *Template.xslt* file :

  .. code-block:: xml

     <xsl:for-each select="/geoprisma/widgets/widget[./type = 'sample']">
       oWestPanel.items.push(
       <xsl:call-template name="sample:drawWidget">
         <xsl:with-param name="pWidgetName" select="./name" />
       </xsl:call-template>);
     </xsl:for-each>

.. centered:: **drawWidgets**

Designed to draw **all** widgets of a given type.  To be able to do so,
each *widget* must be added (done in the printWidgetExecution) to some
kind of *container* (defined in the printWidgetSource).  This method is
easier to use in the *template* file.  Here's an example :

  .. rubric:: drawWidgets function from the *Widget.xslt* file :

  .. code-block:: xml

     <xsl:template name="sample:drawWidgets">
       <xsl:param name="pContainer" />

       <xsl:variable name="WidgetType">
         <xsl:text>sample</xsl:text>
       </xsl:variable>

       if (typeof(objGPWidget<xsl:value-of select="$WidgetType" />Container) != 'undefined' &amp;&amp; typeof(<xsl:value-of select="$pContainer" />) != 'undefined')
       {
           if(<xsl:value-of select="$pContainer" />['ctype']){
               <xsl:value-of select="$pContainer" />.add(
                   objGPWidget<xsl:value-of select="$WidgetType" />Container
               );
           } else {
               <xsl:value-of select="$pContainer" />.items.push(
                   objGPWidget<xsl:value-of select="$WidgetType" />Container
               )
           }
       }
     </xsl:template>


  .. rubric:: drawWidgets call from the *Template.xslt* file :

  .. code-block:: xml

     <xsl:call-template name="shortcut:drawWidgets">
       <xsl:with-param name="pContainer">
         <xsl:text>oWestPanel</xsl:text>
       </xsl:with-param>
     </xsl:call-template>


See the existing widgets to know more about theses methods.