.. _concepts-label: =========================== Architecture and Concepts =========================== In this section, you'll learn more about the terms and words commonly used in GeoPrisma. You'll also see some diagrams that explains the architecture of GeoPrisma. Global view =========== .. _concepts-resource-label: Resource ======== A Resource is associated to a unique set of data, but it can have many different Web Services serving it in different ways. For example, a Resources named GMap_Roads could have its data served by many different kind of servers. Here's an example of what this looks like (with an example of use of the service in question) : * WMS server (to make GetMap requests, GetFeatureInfo queries, etc.) * FeatureServer server (to get vector features in GeoJSON, etc.) * TileCache (to have a faster layer in the UI) The Access Control on Resources is managed by the ACL. The definition of DataStores and Widgets a Resource is linked to is defined in the Configuration file. .. _concepts-datastore-label: DataStore ========= It's the equivalent of a layer of a server, i.e. a LAYER of a mapfile (MapServer), or a layer in a configuration file (FeatureServer, TileCache), etc. DataStores are linked to a single Service. They are defined in the Configuration file. .. _concepts-service-label: Service ======= A Service is a GeoSpacial Web Server, like WMS. Here's a list of the current Services available in GeoPrisma : * WMS * FeatureServer * TileCache * MapServer * GYMO (Google, Yahoo, Microsoft, OpenStreetMap) * Widget (customized to work with a single widget) * MapFishPrint * File * WFS * HTTPRequest * WPS * TMS Here's the XML representation of a Service : .. code-block:: xml S_WMS_DEV4G_GMAP wms http://dev4g.mapgears.com/mswms_gmap? 1.3.0 .. warning:: Please note that the above example is a representation, not the actual way of defining a Service when using a XML config driver. When doing so, the tag should be replaced by in order to be correct, like the following : .. code-block:: xml S_WMS_DEV4G_GMAP http://dev4g.mapgears.com/mswms_gmap? 1.3.0 **Mandatory** service properties : * **name** (must be unique, will be used as a reference inside DataStore objects) * **type** (in the XMLConfig drivers, the type is defined as the node name of a service. See in above example). Here's the list of possible values : * wms * tilecache * featureserver * gymo * widget * mapfishprint * file * wfs * httprequest * wps * tms * **source** (the URL of the service. Since 1.6.0, variable substitution can be used in the URL; all placeholders taking the form ${GP_MY_VAR} (where MY_VAR can be any alphanumerical string, including underscores) will be replaced with the value coming from a PHP session variable with the same name, i.e. GP_MY_VAR. Note that the GP_ prefix is mandatory, otherwise the placeholder will not be substituted.) * **provider** (only for *gymo* services, can either defined as a property or an option) * **apikey** (only for *gymo* services, can either defined as a property or an option) A service can have the following options : * **version** (for example, if set to a *wms* service, it will define the version to use when querying for features (GetFeatureInfo) or maps (GetMap).) * **info_format** (for example, if set a *wms* service, it will define the info_format parameter to use when querying for features (GetFeatureInfo).) * **staticCache** (boolean), only used by TileCache services. When set to *true*, the requests made to the services will be made to the cache directory directly instead of accessing it with WMS. The *source* property of the service **must** point to the according cache directory instead of theà tilecache .cgi or .py script. * **provider** (only for *gymo* services, can either defined as a property or an option) * **apikey** (only for *gymo* services, can either defined as a property or an option) * **csvOutputFormat** (boolean) for *wfs* services. Must be set to true if it supports *outputFormat=text/csv* WFS requests. * **utf8Decode** (boolean) for *wfs* services. Setting this to true will convert the result returned in iso-latin-1. Only used when csvOutputFormat is set to true. * **vendor** (string) for *wms* services. Value is the name of the software used as the service, i.e. **mapserver**, **geoserver**, etc. * **csvNewlineReplaceChar** (string) for *wfs* services. The value setted in it will replace the newline character "\n" in quoted string of the csv exported. It's a bypass for MS Excel that does not support newline characters while importing data from csv. Only used when csvOutputFormat is set to true. * **csvSeperatorChar** (char) for *wfs* services while replacing newline charaters. Set this to the separator character used in the server configuration to create csv. It's needed to parse the csv file to replace the newline characters. Only used when csvNewlineReplaceChar is set. Default is set to ",". * **legendTitles** (boolean) Defaults to false. Only used by the MapFishPrint service and by the :ref:`widget-geoextprintform-label` widget. Please, visit the link for more details. .. _concepts-action-label: Action ====== An Action in GeoPrisma is one of the four basic functions : * Create * Read * Update * Delete In GeoPrisma, Widgets perform Actions on the Resource it's linked to. Actions are managed by the ACL. .. _concepts-role-label: Role ==== A Role is a group of users that share the same tasks. It could be compared to a general job, like Secretary. Roles are managed by the ACL. .. _concepts-permission-label: Permission ========== A Permission defines an Action authorized to a Role on one particular Resource. It consist on the following triplet : one Resource, one Role and one Action. Permissions are managed by the ACL. Here's a small example : We have 9 Resources defined in our Configuration file. We want to have 5 persons to have full access to Oil tankers routes (they are Oil tanker's dispatchers, that's their job). So we want a map with Oceans and Countries in read only, and the Oil tankers routes Resource in full access to be able to edit the routes at will. Oil rafineries locations are also granted read and update access. The Role has access to no other Resources than thoses. Here's how this example may look like : .. image:: permissions.* :align: center Here's a more readable way to display the Permissions for the Oil tanker dispatcher Role : .. image:: permissions-more-readable.* :align: center .. _concepts-user-label: User ==== A User in GeoPrisma is refered to the UserName of an external security application. GeoPrisma has *no integrated user management* security application. .. _concepts-widget-label: Widget ====== A widget is a feature of the UI application. All GeoPrisma widgets have 2 main properties : * Action. Can be read, create, update or delete * ServiceType : (WMS, FeatureServer, TileCache, etc..) Each widget can be associated to one or more Resources. The Resource has to have the according service defined by the Widget ServiceType to be able to use the widget properly. For example : A QueryOnClick widget that has Action:read and ServiceType:WMS could be added to a Resource if that Resource has a WMS Service configured and would be added to the UI if the User is member of a Role has the read Permission to the related Resource. .. _concepts-ui-label: UI == That's the User Interface. It get automatically generated with the widgets defined in the Resources the Role you're currently using has access to. It uses the GeoExt, MapFish and OpenLayers API to do so. .. _concepts-acl-label: ACL === ACL stands for Access Control List. It's the application responsible of managing the Permissions, Actions, Roles and Resources in GeoPrisma. .. _concepts-config-label: Config ====== The config holds the list of objects that GeoPrisma needs to build the UI and to resolved queries that go throught to the :ref:`concepts-proxy-label`. The actual 'objects' it holds depends on the type of config you set up GeoPrisma with. Here's the objects used in the :ref:`xmlconfig-driver-label` config : * :ref:`concepts-service-label` * :ref:`concepts-datastore-label` * :ref:`concepts-resource-label` * :ref:`concepts-widget-label` * :ref:`concepts-layout-label` Here's the objects used in the :ref:`xmlworkspaceconfig-driver-label` config : * :ref:`concepts-service-label` * :ref:`concepts-datastore-label` * :ref:`concepts-resource-label` * :ref:`concepts-widget-label` * :ref:`concepts-layout-label` * Workspace Here's the objects used in the :ref:`config-pgsqlmapcontextconfig-label` config : * :ref:`concepts-service-label` * :ref:`concepts-datastore-label` * :ref:`concepts-resource-label` * :ref:`concepts-widget-label` * :ref:`concepts-mapcontext-label` * :ref:`concepts-application-label` * :ref:`concepts-session-label` .. _concepts-proxy-label: Proxy ===== The 'Proxy' of GeoPrisma is the only point of entry for any queries made. For example, if we would want to make a WMS 'GetMap' query to a WMS :ref:`concepts-service-label` that is defined in the :ref:`concepts-config-label`, it must be made through the Proxy. Its main purpose is to look at the query currently being made and see that the currently connected :ref:`concepts-role-label` has the right to access the :ref:`concepts-resource-label` asked in the query by looking in the :ref:`concepts-acl-label`. If the user has the required :ref:`concepts-permission-label`, the query is completed else denied. There are currently 3 different kinds of proxy in GeoPrisma : * :ref:`proxy-serviceproxy-label` * :ref:`proxy-widgetproxy-label` * :ref:`proxy-configproxy-label` .. _concepts-layout-label: Layout ====== A "Layout" is a config object used to determine the :ref:`concepts-template-label` and the :ref:`concepts-drawmode-label` in order to create the :ref:`concepts-ui-label`. .. _concepts-template-label: Template ======== A Template is a XSLT file used as a UI skeleton. It has a list supported widgets and where to draw them. It uses the ExtJS API. .. _concepts-globals-xslt-label: Globals.xslt ============ It the main *.xslt* file of GeoPrisma, which is locatate in *[your_geoprimsa_root_directory]*/src/client/templates/inc/Globals.xslt. It contains : * the *printAllWidgetSources* xsl:template responsible of calling each included widget type *printWidgetSource* xsl:template. * the *printAllWidgetExecutions* xsl:template responsible of calling each included widget *printWidgetExecution* xsl:template * some useful xsl:templates for the config navigation that is very useful to the widget *.xslt* files. .. _concepts-drawmode-label: DrawMode ======== The name of the javascript library used to manipulate the dom, create gui objets, interfaces, etc. Here's the list of current *DrawMode* used by GeoPrisma : * extjs .. _concepts-mapcontext-label: MapContext ========== A *MapContext* is basically a list of :ref:`concepts-resource-label` inside a specific geospatial context, resulting in a map. It can have all options supported by the :ref:`widgets-map-label` widget. It replaces the *Map* widget inside the :ref:`concepts-mapcontext-configuration-model-label` Here's an XML representation of a *MapContext* : .. code-block:: xml MC_DEFAULT R_OSM R_GMAP_BASE R_GMAP_PARK R_GMAP_PROV R_GMAP_FEDL R_GMAP_RAIL R_GMAP_ROAD R_GMAP_POPP EPSG:4326 -23,-14,13,34 .. _concepts-application-label: Application =========== An *Application* consist of a list of :ref:`concepts-widget-label`, a specific :ref:`concepts-template-label` and a :ref:`concepts-drawmode-label`, resulting in a complete webmapping application, but without any data layer. Here's an XML representation of an *Application* : .. code-block:: xml AP_DEFAULT template.xslt extjs W_MapFishLayerTree W_ScaleWidget W_InitialView W_Shortcut W_ZoomSlider W_Query .. _concepts-session-label: Session ======= Combining a :ref:`concepts-mapcontext-label` with a :ref:`concepts-application-label` results in a complete webmapping application (with the *Application* defined widgets) using and having data layers in it (from the *MapContext* defined resources). This combinaison is called a *Session*. Here's an XML representation of a *Session* : .. code-block:: xml SS_DEFAULT MC_DEFAULT AP_DEFAULT .. _concepts-mapcontext-configuration-model-label: MapContext configuration model ============================== The *MapContextConfiguration* is a *GeoPrisma* :ref:`config-drivers-label` (configuration) model that uses :ref:`concepts-mapcontext-label` and :ref:`concepts-application-label` objects to create complete webmapping applications. A :ref:`concepts-session-label` can be optionnally used instead as well (combining both same objects). Compared to the original model, a :ref:`concepts-resource-label` defined with this one doesn't have embed widgets. Here's an example of a *Resource* defined in the original config : .. code-block:: xml R_GMAP_BASE DS_WMS_DEV4G_GMAP_BASE DS_TC_DEV4G_GMAP_BASE W_MapFishLayerTree W_ScaleWidget W_InitialView W_Shortcut W_ZoomSlider W_Query In the *MapContext configuration model* things are working differently. **Resources don't have Widgets**. Instead, they have **options that can be read by widgets** : .. code-block:: xml R_GMAP_PARK DS_WMS_DEV4G_GMAP_PARK /gmap/ true name If the *Resource* has the option required by the *Widget*, then they are both automatically **linked** together by the *Config* driver. For example, the *Shortcut* widget requires the "zoomField" resource option. The above *Resource* (inside the example) would be linked to the widget since it has the required option, resulting in having a "park shortcut widget" added to the *UI*. Naturally, the :ref:`acl-drivers-label` still has the same role to do. If the currently connected *User* has a *Role* that doesn't have the required permissions to access a specific *Resource* inside a *MapContext*, then it won't be part of the *UI* at all and the *Widget* wouldn't link anything. .. _concepts-resource-options-label: Resource options ================ *Resource options* are used inside the :ref:`concepts-mapcontext-configuration-model-label`. See the related article to know more : :ref:`config-pgsqlmapcontextconfig-label`. .. _concepts-accessfilter-label: AccessFilter ============ An AccessFilter consists of a user-custom condition to apply to all queries sent to a service for a specific resource in order to filter its returned content, which means it can be used : * as a way to get a sub-set of the result * to return a completly different result if the condition isn't met * etc. There are currently 2 types of filters supported : ISSET and BBOX. ISSET ----- This type of filter requires a specific variable to be set in order for the condition to be considered valid. If the condition is met, then you can use this variable in any request sent to the service for a resource. BBOX ---- This type of filter requires the BBOX parameter values set inside a request URL to be contained inside an other BBOX set as the condition in order to be met. A commonly used behavior to do if the condition isn't met is to return a blank image, for example when using a WMS GetMap request. .. note:: This type of filter doesn't currently give much powerful features, so it should be avoided. How to configure ---------------- An AccessFilter consists of an node with one or more conditions. Each is contained inside node, which is contained inside the configuration root node. Here's a complete example : .. code-block:: xml AF_URL_test BBOX##SESSION:user_bbox##IMG:http://127.0.0.1/samples/accessfilter/checkmark.png##IMG:http://127.0.0.1/samples/accessfilter/cross.png ISSET##SESSION:login_username##URLPARAM:user##URLPARAM:nouser Each can then be linked to a resource as such : .. code-block:: xml R_Province Provinces DS_Province_WMS AF_URL_test .. note:: Configuration examples used above use the XMLConfig driver, but it is also supported in all other drivers as well. Condition ---------- A condition value is separated in 4 parts, each separated by two **#** characters. Its content looks like this : .. code-block:: xml 1_type##2_input_type##3_action_if_met##4_action_if_not_met :1) Condition type: (String) Mandatory. The condition types are already explained in details (see above). Possible values are (case-sensitive) : * **ISSET** * **BBOX** :2) Input type: (String) Mandatory. Defines the value to use for the condition. Can be defined in two ways : * as a **plain string** to use as the condition value. .. note:: A condition is always considered met when using this method. * as a string separated in two parts using a semi-column '**:**' character. The left part defines the type of input, while the right part is used by the left part. Possible values are : * **SESSION** : PHP session parameter name to get the value for the input from. For example : .. code-block:: xml SESSION:login_user will use the following PHP variable as input value. If not set, then the condition is not met. .. code-block:: xml $_SESSION['login_user'] :3) Condition met action: (String) Mandatory. Defines the action to do when the condition is met. Value is defined as a string separated in two parts using a semi-column '**:**' character. The left portion defines the type of action, while the right part is used as value for the left part. The possible left values can be : * **URLPARAM** : Name of the parameter to add to the url of the request using input as value Example : .. code-block:: xml URLPARAM:user would append "user" to a request using the value defined in the "Input type" portion, as follow : .. code-block:: xml http://host.com/query?foo=bar&user=Paul * **IMG** : URL to an image to return instead of the query result Example : .. code-block:: xml IMG:http://host/path/to/image.png * **ACL** (no right portion required). Returns a "Not Authorized by ACL" exception instead of the query result. Should only be used a value for a "condition not met". :4) Condition not met action: (String) Optional. Defines the action to do when the condition is not met. The value follows the same input as the condition met. .. note:: All option values defined inside a condition are **case-sensitive**.