.. _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
MyEditFeatureCreateWidget
LineString
MyFeaturePanelWidget
.. _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
objGPWidget
.. rubric:: drawWidget call from the *Template.xslt* file :
.. code-block:: xml
oWestPanel.items.push(
);
.. 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
sample
if (typeof(objGPWidgetContainer) != 'undefined' && typeof() != 'undefined')
{
if(['ctype']){
.add(
objGPWidgetContainer
);
} else {
.items.push(
objGPWidgetContainer
)
}
}
.. rubric:: drawWidgets call from the *Template.xslt* file :
.. code-block:: xml
oWestPanel
See the existing widgets to know more about theses methods.