.. _config-pgsqlmapcontextconfig-label:

=======================
 PGSQLMapContextConfig
=======================

The PGSQLMapContextConfig config driver use the 
:ref:`concepts-mapcontext-configuration-model-label` to store the GeoPrisma
configuration inside a PostgreSQL database.

Please, be sure to have read these topics before continuing :
 * :ref:`concepts-mapcontext-label`
 * :ref:`concepts-application-label`
 * :ref:`concepts-mapcontext-configuration-model-label`


Geoprisma setting
------------------
To tell GeoPrisma to use this config :

.. code-block:: php
    
    <?php

    org_geoprisma_SettingImpl::setConfig('org_geoprisma_config_PGSQLMapContextConfig');

    ?>

Driver extra parameters (mandatory)
------------------------------------

Connection to the database
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This driver needs the connection informations to the PostgreSQL database :

.. code-block:: php
    
    <?php

    $szConnection = 'host=localhost dbname=mcconfig user=demo password=demo port=5432';
    org_geoprisma_config_PGSQLMapContextConfig::setConnectionString($szConnection);

    ?>

MapContext + Application ) OR ( Session )
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This driver also needs to know which  :ref:`concepts-mapcontext-label` and 
which :ref:`concepts-application-label` to use.  You can either manually
define a *MapContext* + *Application* pair using the following 'set' methods.

Using their **id** stored in the DB :

.. code-block:: php
    
    <?php

    org_geoprisma_config_PGSQLMapContextConfig::setCurrentMapContext(1);
    org_geoprisma_config_PGSQLMapContextConfig::setCurrentApplication(1);

    ?>

or their **name** :

.. code-block:: php

    <?php

    org_geoprisma_config_PGSQLMapContextConfig::setCurrentMapContextName("MyMapContext");
    org_geoprisma_config_PGSQLMapContextConfig::setCurrentApplicationName("MyApplication");

    ?>

Alternatively, you can specify a :ref:`concepts-session-label` instead.

Using its **id** :

.. code-block:: php

    <?php

    org_geoprisma_config_PGSQLMapContextConfig::setCurrentSession(1);

    ?>

or its **name** :

.. code-block:: php

    <?php

    org_geoprisma_config_PGSQLMapContextConfig::setCurrentSessionName("MySession");

    ?>


Driver extra parameters (optional)
-----------------------------------

Database structure methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. warning:: Please, note that the following methods refer to the name of the
             features inside GeoPrisma, but are only used as a way to determine
             how the table name are constructed.  If you wish to change them, 
             you must also change the according tables and fields in the 
             database to fit your changes.  Using these method won't change the
             names of the tables and fields in the database, just how to call
             them.

You can change the name of the features of GeoPrisma.  This is useful if you
want to change the database table names and the field names only.  Each feature
has its own method.  See in this example (with fictive new names) :

.. code-block:: php

    <?php

    org_geoprisma_config_PGSQLMapContextConfig::setServiceFeatureName("server");
    org_geoprisma_config_PGSQLMapContextConfig::setDataStoreFeatureName("data");
    org_geoprisma_config_PGSQLMapContextConfig::setResourceFeatureName("layer");
    org_geoprisma_config_PGSQLMapContextConfig::setFieldFeatureName("property");
    org_geoprisma_config_PGSQLMapContextConfig::setMapContextFeatureName("layerlist");
    org_geoprisma_config_PGSQLMapContextConfig::setWidgetFeatureName("tool");
    org_geoprisma_config_PGSQLMapContextConfig::setApplicationFeatureName("toollist");
    org_geoprisma_config_PGSQLMapContextConfig::setSessionFeatureName("ui");

    ?>

You can also change set a prefix to your database table names (defaults to 
"mcconfig\_") :

.. code-block:: php

    <?php

    org_geoprisma_config_PGSQLMapContextConfig::setTablePrefix("myPrefix");

    ?>

Finally, you can also change the option table suffix (defaults to "option") :

.. code-block:: php

    <?php

    org_geoprisma_config_PGSQLMapContextConfig::setOptionTableSuffix("_options");

    ?>

.. _config-pgsqlmapcontextconfig-using-legacy-widgets-label:

Using legacy widgets
~~~~~~~~~~~~~~~~~~~~~

By default, the PGSQLMapContextConfig config driver creates 
:ref:`widgets-mappanel-label` and :ref:`widgets-layer-label` widgets and
support the :ref:`widgets-geoextux-layertreebuilder-label` widget as the layer
tree.  For backward compatibility purpose, the legacy :ref:`widgets-map-label`
and :ref:`widget-mapfishlayertree-label` can be used instead by setting the
following config parameter :

.. code-block:: php

    <?php

    org_geoprisma_config_PGSQLMapContextConfig::useLegacyWidgets(true);

    ?>

.. note:: When using the legacy widgets, please note that the resource options
          must be set accordingly to fit the :ref:`widgets-map-label` options
          for the map and layer nodes.


Database table names
---------------------

The table names follow these construction rules :

 +----------+-----------------------+-----------------------------------+
 | *type*   | *construction rule*   | *full table name example*         |
 +==========+=======================+===================================+
 | feature  | Prefix +              | mcconfig_resource                 |
 | table    | Feature name          |                                   |
 +----------+-----------------------+-----------------------------------+
 | option   | Prefix +              | mcconfig_resourceoption           |
 | table    | Feature name +        |                                   |
 |          | Option suffix         |                                   |
 +----------+-----------------------+-----------------------------------+
 | relation | Prefix +              | mcconfig_mapcontextresource       |
 | table    | Master feature name + |                                   |
 |          | Slave feature name    |                                   |
 +----------+-----------------------+-----------------------------------+
 | relation | Prefix +              | mcconfig_mapcontextresourceoption |
 | option   | Master feature name + |                                   |
 | table    | Slave feature name +  |                                   |
 |          | Option suffix         |                                   |
 +----------+-----------------------+-----------------------------------+


.. _config-pgsqlmapcontextconfig-resource-options-label:

Resource options
-----------------

As explained in this topic
(:ref:`concepts-mapcontext-configuration-model-label`), *Widgets* are linked to
*Resources* if it has the *Resource* option required by the *Widget*.

Learn more about *Resource options* in the following topics :

.. toctree::
    :maxdepth: 2
    
    resourceoptions


Field options
--------------

:ref:`config-pgsqlmapcontextconfig-resource-options-label` can be used as a way
to link *Widgets* to *Resources* and so do *Field options*.  

Learn more about *Field options* in the following topics :

.. toctree::
    :maxdepth: 2
    
    fieldoptions


OpenLayers.Layer object creation logic
---------------------------------------

Since the *Map* widget no longer exists in the 
:ref:`concepts-mapcontext-configuration-model-label`, there are no longer
*Layer* tags to define the *OpenLayers.Layer* objects to create.  Instead, the
*Resource options* are used when creating *OpenLayers.Layer* object as options.

.. seealso:: :ref:`config-resource-options-other-label`

However, *OpenLayers.Layer* objects are not always created and added to the
*Map* for a specific *Resource*.  For each of its *DataStores*, we first check
its *Service type*, then we check the according rule before adding a layer
object.  Here's how it works :

 +----------------+-----------------------------------------------------------+
 | *service type* | *creation rule*                                           |
 +================+===========================================================+
 | GYMO           | always added                                              |
 +----------------+-----------------------------------------------------------+
 | Tilecache      | always added                                              |
 +----------------+-----------------------------------------------------------+
 | WMS            | only added if there is no TileCache or TMS layer already  |
 |                | added (of the same resource)                              |
 +----------------+-----------------------------------------------------------+
 | FeatureServer  | only added if a *Widget* (using the 'featureserver'       |
 | (vector)       | servicetype) needs the layer to work with it OR if it's   |
 |                | the only *DataStore* available, i.e. if no widget need    |
 |                | a featureserver layer but it's the only *DataStore*       |
 |                | available for the resource, a layer will be added.        |
 +----------------+-----------------------------------------------------------+
 | WFS (vector)   | Same rules as FeatureServer                               |
 +----------------+-----------------------------------------------------------+
 | TMS            | always added                                              |
 +----------------+-----------------------------------------------------------+

.. note:: The above creation rules apply only for this config driver.

.. note:: To know wheter or not a *Widget* needs a layer to interact with, we
          use the *Widget* **needLayer** method defined inside its .php file.


Config_secur.xml
-----------------

This driver also creates a config_secur.xml file as the other config driver do.
That way, the same templating system (*XSLT*) is preserved.  Some new nodes were
added, such as *Resource options* and *Resource fields*, but they don't break
anything with the original configs.


Automatic widget generation by the config
------------------------------------------

Main widgets
~~~~~~~~~~~~~

With the PGSQLMapContextConfigDriver, some widgets are automatically created.
They are not in the configuration (in the database).  These widgets are
responsible for creating the base components of the client application, such as
the OpenLayers.Map, OpenLayers.Layer and GeoExt.MapPanel objects.

By default, these widgets are created :

* :ref:`widgets-mappanel-label`
* :ref:`widgets-layer-label`

When :ref:`config-pgsqlmapcontextconfig-using-legacy-widgets-label`, these
widgets are created instead :

* :ref:`widgets-map-label`

.. note:: Both methods use the MapContext and Resource options to create the
          according widgets.


Widget cloning
~~~~~~~~~~~~~~~

*Widgets* that need to be linked to be linked to *Resources* are binded together
by this driver.  However, if the *Widget* wouldn't normally support more than
one *Resource*, it needs to be cloned first.  This is automatically done by the
driver, you don't need to worry about it unless you wish to develop a new
widget.  The best and easiest approach is always to allow a *Widget* to support
any number of *Resources*.

To know if a *Widget* needs to be cloned before being linked to a *Resource*,
look for the  *Widget* **mustClone** method.

.. note:: If **mustClone** isn't defined inside a widget's *.php file*, then
           consider it doesn't need to be cloned since the method returns 
           **false** by default.

.. seealso:: :ref:`widget-how-to-create-php-file`


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

In the *.xslt* template file, the call to the *printWidgetExecution* method is
made.  It requires the name of the *map* node.  Since this driver dynamically
creates the map name and because it can change, we find it dynamically as well.

The following method works since only one *<map>* node is created in the 
config_secur.xml :

.. code-block:: xml

        <!-- Check if one map node exists -->
        <xsl:variable name="bOneMap">
          <xsl:value-of select="count(/geoprisma/widgets/widget[./type = 'map']) = 1"></xsl:value-of>
        </xsl:variable>

        <xsl:choose>
          <xsl:when test="$bOneMap = 'true'">
            <xsl:variable name="pstrMapName">
              <xsl:value-of select="/geoprisma/widgets/widget[./type = 'map']/name"></xsl:value-of>
            </xsl:variable>

            <!-- Call printAllWidgetExecutions with map name as parameter -->
            <xsl:call-template name="printAllWidgetExecutions" >
              <xsl:with-param name="pMapName">
                <xsl:value-of select="$pstrMapName"></xsl:value-of>
              </xsl:with-param>
            </xsl:call-template>
          </xsl:when>

          <!-- Error, no ore more than one map node found -->
	  <xsl:otherwise>
            <center>
              <br /><br />
              <h1>Error : No or more than one maps detected.</h1>
            </center>
          </xsl:otherwise>
        </xsl:choose>