deegree iGeoPortal -

Standard Edition v2.2

Change log

1. Introduction

deegree is a Java Framework offering the main building blocks for Spatial Data Infrastructures (SDIs). Its entire architecture is developed using standards of the Open Geospatial Consortium (OGC) and ISO Technical Committee 211 – Geographic information / Geoinformatics (ISO/TC 211). deegree encompasses OGC Web Services as well as clients. deegree is Free Software protected by the GNU Lesser General Public License (GNU LGPL) and is accessible at http://www.deegree.org.

deegree2 is the new release of deegree supporting a number of features that deegree1 was not able to handle. This documentation describes setup and configuration of the new deegree iGeoPortal standard edition, a client imple­mentation of OGC's Web Map Service Implementation Specification 1.1.1 using OGC's Web Map Context documents for configuration.

deegree iGeoPortal is the web-based portal framework of deegree. It offers visualization of geodata through a standard web browser like Mozilla, Firefox or MSIE. The demo download that accompanies this document includes the standard functionality of iGeoPortal. This is basically a „Web-GIS“ using WMS servers as map source.

Additional modules not configured in this download package enable the user to search for and download data or digitize online and insert the result including its properties via transactional WFS into a database backend like Postgresql/Postgis, and navigate the displayed map using an OGC Gazetteer (WFS-G). Each user is able to store the current state of the portal in an OGC Web Map Context document that can be loaded again later to restore the portals state. If assigned to deegree users and a right management system (iGeoSecurity) the portal can limit this and other functions to authorized users and enable personalized configuration. A component for accessing OGC catalogue services for ISO 19115/19119 metadata is also under development.

The demo portal is preconfigured to work with a remote deegree2.2 demo Web Map Service (WMS), but there is no limitation on using other OGC WMS, for example UMN MapServer or other, (proprietary) servers that can be installed on remote machines. iGeoPortal is not limited to be used with just one WMS. You can combine several WMSs in one predefined context as well as load additional WMSs 'on the fly'. Additionally a simple search module based on a deegree2.2 demo WFS-G (Web Feature Service – Gazetteer enabled) is implemented.

To get an overview about deegree WMS and other deegree components that may be used within the context of iGeoPortal please have a look at the respective documentation. This document will deal only with the administration of iGeoPortal.

Besides iGeoPortal, deegree comprises a number of additional services and clients. A complete list of deegree components can be found at:

http://www.lat-lon.de → Products

Downloads of packaged deegree components can be found at:

http://www.deegree.org → Download

The web services of deegree are realized as Java modules controlled by one central servlet (the “dispatcher”). This servlet has to be deployed to the respective web server/servlet engine. Most of the common web servers support servlet technology, thus making deegree a universal product. The Apache-Tomcat 5.5 Servlet-Engine is recommended due to its widespread use and its status as an open-source product.

2. Download / Installation

   1. Prerequisites

For deegree2 iGeoPortal to run you need:

• Java (JRE or JSDK) version 1.5.x

• Tomcat 5.5.x

For installation of these components refer to the corresponding documentation at java.sun.com and tomcat.apache.org.

2. deegree iGeoPortal release

deegree iGeoPortal can be downloaded from http://www.deegree.org. The release is packed as a WAR-archive (igeoportal-std.war). Simply put this file into your $TOMCAT_HOME$/webapps directory and (re-)start Tomcat. The installation of iGeoPortal is already done with this, as long as you run tomcat on port 8080 and it is accessible via 'localhost'. The package comes preconfigured with a remote deegree2.2 demo WMS, why there is no further configuration needed to get it up an running.

Note: It is also possible to extract the WAR archive (which is nothing but a renamed .zip file) into another place of your computer and direct Tomcat to this place. Because of this possibility, in the remainder of this document, the directory you extracted the files to is referred to as $iGeoPortal_home$ (=$TOMCAT_HOME$/webapps/igeoportal-std in the standard case).

The example uses a deegree WMS but this is not required. Each WMS compliant to OGC WMS 1.1.0 – 1.1.1 specifications can be used as well.

3. Testing the installation

After deploying the application to tomcat, the portal can be started by entering:

http://localhost[:port]/igeoportal-std

Figure 1: Welcome page of deegree iGeoPortal

Clicking the link [goto] nested in the page will lead you to the iGeoPortal itself. If everything went fine you should then see the following page (start context configuration wmc_start_utah.xml):

Figure 2: initial page when starting deegree iGeoPortal

3. Basic Configuration

The central configuration files of deegree iGeoPortal are XML documents that are valid against the XML-schema defined in OGC's Web Map Context specification 1.0.0. This schema defines two sections that are allowed to contain any well formed XML fragments. These sections (extensions in WMC syntax) are used by iGeoPortal to define layout and additional data access methods. Nevertheless a deegree iGeoPortal context document is a compliant WMC document and iGeoPortal is able to read and use WMC documents from other vendors.

As stated above, an OGC WMC document is divided into several parts. Apart from the mandatory or optional parts of the WMC specification it is possible to use elements called <Extension> to define vendor specific elements/behaviors. The content of the the <Extension> element is defined as <xs:any> so the only restriction is that it has to be a well formed XML fragment.

deegree iGeoPortal uses these elements mainly for definition of the graphical structure of the portal and definition of access paths to resources required by the portal. A detailed description of the content of all elements defined by the OGC can be found within the WMC specification that can be downloaded from the OGC pages (see https://portal.opengeospatial.org/files/?artifact_id=3841). Therefore only those elements will be explained in this documentation which are crucial for deegree iGeoPortal.

1. Basic Structure of Map Context Files

The root element of each map context configuration file is <ViewContext>. It contains the required namespace definitions and two child elements, <General> and <LayerList>.

<?xml version="1.0" encoding="UTF-8"?>

<ViewContext xmlns="http://www.opengis.net/context"

xmlns:sld="http://www.opengis.net/sld" xmlns:xlink="http://www.w3.org/1999/xlink"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

version="1.0.0" id="String">

<General>

...

<!-- described in chapter 3.2 -->

...

</General>

<LayerList>

...

<!-- described in chapter 3.3 -->

...

</LayerList>

</ViewContext>

The contents of these elements will be described in detail in the following paragraphs.

2. General definitions

The element <General> contains definitions of map size, map extent and of vendor and content description. In detail these are:

• size of the map window in pixel (<Window>),

• geographic extent of the map including coordinate reference system to be used (<BoundingBox>)

• name of the map/portal context (<Title>),

• optional list of keywords describing the map/portal context (<KeywordList>),

• optional description of the map/portal context(<DescriptionURL>),

• contact information (<ContactInformation>)

• several extensions (<Extension>) made by deegree that will be explained in the next few sections.

<General>

<!-- specifies the map size and must correspond to the module MapView definded further below. The <BoundingBox ...> sets the used CRS and the initial extend (used for button View full extent). BBox must have the same proportion as the <Window ...> settings. -->

<Window width="500" height="500" />

<BoundingBox SRS="EPSG:26912" minx="117300" miny="4049850" maxx="767300" maxy="4699850" />

<Title>deegree iGeoPortal</Title>

<KeywordList>

<Keyword>deegree</Keyword>

<Keyword>iGeoPortal</Keyword>

<Keyword>SDI</Keyword>

<Keyword>GDI</Keyword>

<Keyword>lat/lon</Keyword>

<Keyword>utah</Keyword>

</KeywordList>

<DescriptionURL format="text/html">

<OnlineResource xlink:type="simple" xlink:href="http://www.deegree.org" />

</DescriptionURL>

<ContactInformation>

<ContactPersonPrimary>

<ContactPerson>Andreas Poth</ContactPerson>

<ContactOrganization>lat/lon</ContactOrganization>

</ContactPersonPrimary>

<ContactPosition>developer</ContactPosition>

<ContactAddress>

<AddressType>postal</AddressType>

<Address>Aennchenstr. 19</Address>

<City>Bonn</City>

<StateOrProvince>NRW</StateOrProvince>

<PostCode>53177</PostCode>

<Country>Germany</Country>

</ContactAddress>

<ContactVoiceTelephone>++49 228 184960</ContactVoiceTelephone>

<ContactElectronicMailAddress>poth@lat-lon.de</ContactElectronicMailAddress>

</ContactInformation>

<Extension xmlns:deegree="http://www.deegree.org/context">

<deegree:IOSettings>

...

<!-- described in chapter 3.2.1 -->

...

</deegree:IOSettings>

<deegree:Frontend scope="JSP">

...

<!-- described in chapter 3.2.2 -->

...

</deegree:Frontend>

<deegree:MapParameter>

...

<!-- described in chapter 3.2.3 -->

...

</deegree:MapParameter>

</Extension>

</General>

1. Extension – IOSettings

The element <IOSettings> describes some directories, where iGeoPortal stores files such as print files. If you change the configuration of one of the demo context files or define one of your own, you should keep in mind that only the definition of <PrintDirectory> and <TempDirectory> is mandatory. If some or all of the other directory definitions are missing, deegree will use the <TempDirectory> instead. Depending on the used functionalities of a portal instance it may not be necessary to publish all directories to the web. In this case a directory can be located outside the web context or below the WEB-INF directory. To access the directories content a web application must be defined in <deegree:Access> instead of the path to the directory.

The iGeoPortal demo uses the following reduced IOSettings. Because no modules for data download and user defined styles (SLD) are offered at the moment, corresponding directory definitions would not make sense.

<Extension xmlns:deegree="http://www.deegree.org/context">

<deegree:IOSettings>

<deegree:TempDirectory>

<deegree:Name>./../../../tmp</deegree:Name>

<deegree:Access>

<OnlineResource xlink:type="simple"
xlink:href="http://localhost:8080/igeoportal-std?"/>

</deegree:Access>

</deegree:TempDirectory>

<deegree:PrintDirectory>

<deegree:Name>./../../../print</deegree:Name>

<deegree:Access>

<OnlineResource xlink:type="simple"
xlink:href="http://localhost:8080/igeoportal-std/print?"/>

</deegree:Access>

</deegree:PrintDirectory>

<!--

<deegree:DownloadDirectory>

<deegree:Name>../../../print</deegree:Name>

<deegree:Access>

<OnlineResource xlink:type="simple"
xlink:href="http://localhost:8080/igeoportal-std/"/>

</deegree:Access>

</deegree:DownloadDirectory>

<deegree:SLDDirectory>

<deegree:Name>../../../</deegree:Name>

<deegree:Access>

<OnlineResource xlink:type="simple"
xlink:href="http://localhost:8080/igeoportal-std"/>

</deegree:Access>

</deegree:SLDDirectory>

-->

</deegree:IOSettings>

...

</Extension>

2. Extension – Frontend

The element defined within the <Extension> element associated to layout is the <Frontend> element. It is used to define the graphical user interface, as well as other system-specific parameters, not seen by the end-user. A short overview is given here, the details will follow below.

<deegree:Frontend scope="JSP">

<deegree:Controller>...</deegree:Controller>

<deegree:Style>...</deegree:Style>

<deegree:Header>...</deegree:Header>

<deegree:Footer>...</deegree:Footer>

<deegree:CommonJS>...</deegree:CommonJS>

<deegree:North hidden="false">...</deegree:North>

<deegree:East hidden="false">...</deegree:East>

<deegree:West hidden="false">...</deegree:West>

<deegree:South hidden="false">...</deegree:South>

<deegree:Center hidden="false">...</deegree:Center>

</deegree:Frontend>

The idea of iGeoPortal is to encapsulate different functionalities in separate modules. These modules work as independent as possible from each other and they all use the same interface. So e.g. the map, its legend, or the layer list are all realized by separate modules. Each module can be located anywhere in the portals predefined layout frames. Except for map view and (the invisible) map model the registration of modules is optional. So it's your decision which functions to offer users of the map context instance (consider: each map context can define its own collection of available modules!).

Figure 3: area definitions of iGeoPortal

All modules are dynamically located on the portal's skin based on their settings. To enable the administrator of a portal to influence the portals layout deegree defines seven areas. A module can be assigned to five of these areas (North, East, South, West, Center); the other two areas (Header, Footer) are designed for taking links to simple HTML-content (static or dynamic). Usually they will be used for corporate identity, menus, external links etc.

The Controller will receive all portal driven events (zoomin, pan, print etc.) and delegates them to the responsible modules.

<deegree:Frontend scope="JSP">

<deegree:Controller>./modules/controller/controller.jsp</deegree:Controller>

<deegree:Style>./css/deegree.css</deegree:Style>

<deegree:Header>header.html</deegree:Header>

<deegree:Footer>footer.html</deegree:Footer>

<deegree:CommonJS>

<deegree:Name>event.js</deegree:Name>

<deegree:Name>envelope.js</deegree:Name>

<deegree:Name>geotransform.js</deegree:Name>

<deegree:Name>pushbutton.js</deegree:Name>

<deegree:Name>togglebutton.js</deegree:Name>

<deegree:Name>layergroup.js</deegree:Name>

<deegree:Name>htmllayer.js</deegree:Name>

<deegree:Name>layerutils.js</deegree:Name>

<deegree:Name>rpc.js</deegree:Name>

<deegree:Name>recentertolayer.js</deegree:Name>

</deegree:CommonJS>

...

</deegree:Frontend>

The Controller definition is followed by setting the central stylesheet document which controls the portals layout. Definitions made here can be overwritten by CSS definitions made in an HTML-page assigned to a loaded module. Behind this the optional content of the header and footer section will be defined (notice: contents of header and footer does not have to be a static HTML-page). Definition of 'common' JavaScript files used by more than one module is optional too but it strongly recommended. If a JavaScript or HTML file is defined without absolute or relative path settings, the file must be located in $iGeoPortal_home$ directory. Relative path settings use this directory as the starting point.

After this the definition of the used areas (each area is allowed to be empty) and the modules contained in the areas follows. The following example demonstrates how the module 'MenuBarTop' is assigned to the 'North' area.

<deegree:North hidden="false">

<deegree:Module hidden="false" type="content" width="990" height="22"

scrolling="no">

<deegree:Name>MenuBarTop</deegree:Name>

<deegree:Content>menubartop.html</deegree:Content>

<deegree:ModuleJS>menubar.js</deegree:ModuleJS>

</deegree:Module>

</deegree:North>

Each area may include the optional attribute 'hidden' to define if an area should be visible when the context is loaded into the portal. This may be useful if an area's content just is intended to be visible in some situations (support for hidden-attribute is not completely implemented yet). Its default value is 'false'.

At the example above within the 'North' area the 'MenuBarTop' module is embedded. Even if the example shows just one module within an area there is no limit to the numbers of modules that can be registered to an area (if you register too many modules you may get a somehow strange portal layout). If more than one module is registered to an area deegree tries to arrange the modules considering their real size, preferred size (width, height attributes) and available space. Modules within 'North' and 'South' area will be arranged horizontally, modules within 'West', 'Center' and 'East' will be arranged vertically.

Five attributes can be assigned to each module registered to an area. But just one of them (the type) is mandatory:

• hidden: defines whether a module should be visible when the context is loaded (default = false)

• type: defines the type of the module, (content | toolbar); no default

• width: preferred module width (may be modified by deegree)

• height: preferred module height (may be modified by deegree)

• scrolling: defines whether scrollbars should appear if a module exceeds available space (auto | no | yes; default = auto)

As sub-element of a <Module> element its name (<Name>), resource of its content (<Content>) and a JavaScript file will be set. The last contains a JavaScript object having the identical name as the module it is assigned to (this is mandatory, see below) (MenuBarTop in the example above). If the content (e.g. a static HTML page) already contains a JavaScript object with the same name as the module <ModuleJS> can be left out.

For each module a parameter definition may be given. Each parameter (name/value) will be passed to the constructor of the JavaScript object assigned to a module. If a module receives more than one parameter the parameter definition must be in the same order the JavaScript object constructor expects it.

...

<deegree:Module hidden="false" type="content" height="70" width="180">

<deegree:Name>GazetteerSwitch</deegree:Name>

<deegree:Content>gazetteerswitch.html</deegree:Content>

<deegree:ModuleJS>gazetteerswitch.js</deegree:ModuleJS>

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>targetIntFrame</deegree:Name>

<deegree:Value>'Street'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>sourceModules</deegree:Name>

<deegree:Value>'Streets|gazetteerb.html;

descricts|gazetteera.html;'</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

</deegree:Module>

...

All modules available for the demo of deegree iGeoPortal Std. Ed. are described in chapter 4.

3. Extension – MapParameter

Below the frontend description (list of available modules) the parameters of deegree:MapParameters describe the behaviour of the map in general. The section defines the format of the GetFeatureInfo request, the factor for zooming in or out, the factor for paning the map and the minimum and maximum scale that is permitted for the map view in general.

<deegree:MapParameter>

<deegree:OfferedInfoFormats>

<deegree:Format>application/vnd.ogc.gml</deegree:Format>

<deegree:Format selected="true">text/html</deegree:Format>

</deegree:OfferedInfoFormats>

<deegree:OfferedZoomFactor>

<deegree:Factor selected="true">25</deegree:Factor>

</deegree:OfferedZoomFactor>

<deegree:OfferedPanFactor>

<deegree:Factor selected="true">15</deegree:Factor>

</deegree:OfferedPanFactor>

<deegree:MinScale>1</deegree:MinScale>

<deegree:MaxScale>100000</deegree:MaxScale>

</deegree:MapParameter>

Note: These values are currently not evaluated! Changing the values does not result in a changed behaviour of the portal. Hope for future releases.

3. LayerList

After the general definition of the layout and the registered functions of the portal follows the definition of the available layers and their resources, according to OGC Web Map Context (WMC) Specification. All WMC specific information is encapsulated within the <LayerList> element. One <LayerList> contains any amount of <Layer>-elements. The sequence of the layers describes the sequence of visible layers. Beneath all kinds of elements of WMC specification, every layer is extended by the <Extension>-element where you can define any other characteristics. deegree iGeoPortal uses some extensions for describing the data resources.

A <Layer>-Element has the following syntax:

<Layer queryable="1" hidden="1">

<!-- service="OGC:WMS" version="1.1.1"principally iGeoportal is also capable of requesting WFS; this feaure is not usable yet. The title="deegree2.2 Demo WMS" must be unique for every requested WMS, in case you configure more than one WMS xlink:href specifies the online resource of the service -->

<Server service="OGC:WMS" version="1.1.1" title="deegree2.2 Demo WMS">

<OnlineResource xlink:type="simple"

xlink:href="http://demo.deegree.org/deegree-wms/services?" />

</Server>

<!--<Name> must the WMS name -->

<Name>Springs</Name>

<!-- Title can be chosen freely and should be human readable -->

<Title>Springs</Title>

<!-- Specifies the requested CRS to the WMS. Should be identical to the Web Map Context (WMC) configuration -->

<SRS>EPSG:26912</SRS>

<FormatList>

<!-- sets the requested image format. Must be offered by WMS -->

<Format current="1">image/png</Format>

</FormatList>

<StyleList>

<Style current="1">

<!-- set the style to be used. Must be offered by WMS -->

<Name>default</Name>

<Title>default</Title>

</Style>

</StyleList>

<Extension xmlns:deegree="http://www.deegree.org/context">

<deegree:ScaleHint min="0" max="1800000000"/>

</Extension>

</Layer>

Each element contains two attributes for determining if a GetFeatureInfo-Request is possible queryable="1" or if the layer is visible at start-up hidden="1". The first element <Server> describes which Web Service delivers a specific layer. Via three attributes, its service type, -version and -title are set. Theoretically, WFS and WCS Services could be requested here. At the moment, neither the WMC specification nor deegree implements them, so only OGC:WMS instances can be referred to. The <Server>-element contains the OnlineResource with the URL of a WMS and its according layer. The title="WMS title" needs to be unique for every implemented (WMS)- Service.

After defining the WMS, there are some definitions that are pretty similar to the ones of a Capabilities Document of a WMS. It is important to mention, that the statements are identical to the Capabilities or respectively subsets of them. For instance, the layer's name in the WMC document has to be identical to the WMS Capabilities document's layer name. The title can be different. The requested SRS for each layer of the portal has to be supported by the WMS. The same applies to the image format and style definition. Not all available formats, SRS and styles have to be defined.

deegree specific informations for <Layer> are stored within an element named <Extension>. For example deegree iGeoPortal stores informations for data access, authentication mechanism and valid scale range of a layer here.

<Extension xmlns:deegree="http://www.deegree.org/context">

<deegree:DataService>

<Server service="OGC:WFS" version="1.1.1" title="deegree WFS">

<OnlineResource xlink:type="simple"
xlink:href="http://127.0.0.1:8080/deegreewfs/wfs"/>

</Server>

<deegree:GeometryType>Polygon</deegree:GeometryType>

</deegree:DataService>

<deegree:ScaleHint min="0" max="1800000000"/>

<deegree:UseAuthentication>none</deegree:UseAuthentication>

</Extension>

Via the element <DataService> the portal servers knows, where it can get the original vector data for downloading.¹ If no DataService for a layer is defined, downloads are not possible.

Additionally the scale range for visualizing a layer can be defined. They correspond to the <ScaleHint> information of the WMS Capabilities and are optional. If a <ScaleHint> is defined and the current map view is out of that scale range, the according layer in the layerlist is greyed out. The <ScaleHint>, according to WMS specification, is defined as ' the ground distance in metres of the southwest to northeast diagonal of the middle pixel of the map.

To give deegree a hint if authentication information is to be used when accessing capabilities of a OWS the optional element <UseAuthentication> can be defined. The default value is 'none' which means that no authentication information will be used when accessing a OWS. To force authentication usage, either 'user/password' or 'sessionID' can be used. Using 'user/password' iGeoPortal adds the parameters USER and PASSWORD to requests against the OWS offering the requested layer; using sessionID a parameter named SESSIONID will be added.

When using 'user/password' or 'sessionID' you have to ensure, that:

1. a user's authentication is available for the client which loads a WMC

2. the OWS assigned with a layer is able to handle password authentication information

3. each layer within a WMC assigned to the same OWS must define the same value for <UseAuthentication> element.

4. Available Modules

There are numerous modules available with iGeoPortal Standard Edition. In the demo releases on line at http://demo.deegree.org the start web map context is set to "Utah" (wmc_start_utah.xml), with the possibility to switch to "Salt Lake City" (wmc_saltlake.xml). From "Salt Lake City" you can switch back to "Utah" or to a third web map context called "Playground". These three contexts provide different features of iGeoPortal Standard Edition. You will find most of the newer modules in the "Playground" context (wmc_testPlayground.xml).

Some features activated in the on line demo will not work out of the box for your downloaded and privately set up iGeoPortal. This holds true for those modules that need to be configured to your own requirements. You will find a comment in the description to these modules.

1. MenuBarTop/MenuBarBottom

Description: menu bar containing links to functions of the portal and internal or external HTML-pages. Both modules are simple in their construction. It isn't a problem to extend or limit the pre-defined link list.

Init-parameters: none

2. ContextSwitcher

Description: As described above the map context document is the basis for functions and modules visible in an iGeoPortal instance. The portal itself offers a 'container' where any valid map context document can be processed and visualized. ContextSwitcher represents a module that enables loading of other contexts during runtime and switching content of a portal instance. This enables offering different views or themes within one instance of iGeoPortal. All context documents that should be available for switching between must be stored in directory $iGeoPortal_home$/WEB-INF/conf/igeoportal.

The module is realised as an HTML-page with a combo box that is filled by the assigned JavaScript object evaluating the passed init-parameters.

Init-parameters:

<deegree:Module hidden="false" type="content" width="150" height="50">

<deegree:Name>ContextSwitcher</deegree:Name>

<deegree:Content>contextswitcher.html</deegree:Content>

<deegree:ModuleJS>contextswitcher.js</deegree:ModuleJS>

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>label</deegree:Name>

<deegree:Value>'Theme selection:'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>listOfContexts</deegree:Name>

<!-- If you want to test digitizerModule, gazetteerClient, securityEnabledPortal, pdf printing or legend view switch to second <deegree:Value> entry.

-->

<deegree:Value>'Utah|wmc_start_utah.xml;Salt Lake City|
wmc_saltlake.xml'</deegree:Value>

<!-- <deegree:Value>'Utah|wmc_start_utah.xml;Salt Lake City|
wmc_saltlake.xml;Playground|wmc_testPlayground.xml;
TestDynamicLegend|wmc_testDynLegend.xml;TestPdfPrint|
wmc_testPdfPrint.xml;TestCustomTab|wmc_testCustomTab.xml;
TestLegendView|wmc_testLegend.xml;TestFullScreen|
wmc_testFullScreen.xml;TestDigitizer|wmc_testDigitizer.xml;TestGaz|
wmc_testGazClient.xml;TestSecurity|
wmc_testSecurity.xml'</deegree:Value> -->

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>size</deegree:Name>

<deegree:Value>1</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>bgcolor</deegree:Name>

<deegree:Value>'#cccccc'</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

</deegree:Module>

Four init-parameters are passed to the module. By using the 'label' we can define the headline above the combo box. Parameter 'listOfContexts' contains a comma separated list of available context documents. Each list entry consists of two parts. The first part is the context name as displayed in the combo box. The second, separated by a '|' character, is the name of the context document file as stored in $iGeoPortal_home$/WEB-INF/conf/igeoportal directory. The third init-parameter defines the size of the HTML select element displaying the list of available contexts. A value of '1' results in the display of a combo box. A value > 1 will force displaying a HTML list. The last parameter enables definition of the modules background color.

3. DefaultContentSwitch

Description: deegree iGeoPortal arranges all modules assigned to an area considering their size, the preferred size and available space automatically. Especially if a large number of modules should be registered to a portal/context available space may be exceeded. For this case iGeoPortal offers the DefaultContentSwitch module. It represents a module that enables loading more than one module inside one portal area and switching its content during runtime. One can switch to the needed module through list boxes, menu items, tab panes or whatever a ContentSwitcher offers. The DefaultContentSwitcher available with the demo iGeoPortal uses a combo box for switching between layer list and legend view.

To enable switching between different modules these modules have to be registered first as described above within a portal area. The provider/administrator of a module must ensure that only one of these modules is set to visible (hidden='false') all others have to be invisible (hidden='true'). After this the DefaultContentSwitcher will be 'informed' through its init-parameters between which modules switching has to be enabled.

Init-parameters:

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>targetFrame</deegree:Name>

<deegree:Value>'LayerListView'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>sourceModules</deegree:Name>

<deegree:Value>

'LayerListView|layerlistview.html;Legend|legend.html'

</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

The first parameter contains the name of the module that will be visible when loading the context. The second parameter contains a comma separated list of modules, between which switching will be possible. Each entry of the list contains two parts. The first part is the name of the module as displayed in the switchers combo box. The second is the name of content document assigned to a module.

4. CustomTabSwitch

Description: The CustomTabSwitch is a variation of the above Default­ContentSwitch. It also enables you to switch between layer list and legend view, but it uses tab panes instead of a combo box.

To test this functionality, please refer to the Web Map Context wmc_testCustomTab.xml.

Init-parameters: this module has the same init-parameters as the DefaultContentSwitch.

<deegree:Module hidden="false" type="content" height="25" width="175">

<deegree:Name>CustomTabSwitch</deegree:Name>

<deegree:Content>customtabswitch.html</deegree:Content>

<deegree:ModuleJS>customtabswitch.js</deegree:ModuleJS>

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>targetFrame</deegree:Name>

<!-- value must correspond to first entry in
sourceModules value -->

<deegree:Value>'LayerListView'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>sourceModules</deegree:Name>

<!-- order of entries in list is important. first entry
must be the visible module (targetFrame) -->

<deegree:Value>
'LayerListView|layerlistview.html;Legend|legend.html'
</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

</deegree:Module>

The targetFrame contains the name of the module that will be visible when loading the context. The second parameter contains a comma separated list of modules, between which switching will be possible. The order of entries in this list is important. The first entry in the list must match the module that is chosen as initial module in targetFrame.

5. Legend

Description: The 'Legend' module is able to visualise the legend of the associated map. It calls the GetLegendGraphic-Function of an appropriate Web Map Service offering that optional function. The parameters used are mostly for controlling the layout.

Init Parameters:

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>label</deegree:Name>

<deegree:Value>'Legend'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>bgcolor</deegree:Name>

<deegree:Value>'#cccccc'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>layerlist</deegree:Name>

<deegree:Value>this.layerList</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>width</deegree:Name>

<deegree:Value>20</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>height</deegree:Name>

<deegree:Value>20</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

The parameter 'label' is for labeling the entire legend graphic; with 'bgcolor' the background color is defined. Initially the key 'layerlist' should not be changed; it is a reference to an internal list of map layers of the portal. It makes sense to change the key, if an instance of the portal contains more than one map in order to generate a separate legend for each map. With the parameter 'width' and 'height' you can define the size of the legend symbols (!), not the entire legend graphic itself.

6. Dynamic Legend

Description: This module is a variation of the standard legend module. Instead of simply creating a GetLegendGraphic request and sending this request to the WMS of the respective layer, its functionality is more complex:

If a layer definition in the map contexts LayerList (see chapter 3.3) provides a layer name, and a style definition including the style name and a legend URL, then this URL is used to retrieve the legend image.

If no legend URL is set in the map context, then it is checked whether the WMS capabilities document contains a URL for this layer and style.

If no legend URL can be retrieved from the capabilities document, but the WMS can answer GetLegendGraphics requests, such a request will be sent and the response will be used to display the legend.

If the WMS does not provide GetLegendGraphics requests, or if no legend URL is available for the respective layer, no legend will be displayed. Instead, the image defined as 'missingLegend' (see below) will be shown.

Please refer to wmc_testDynLegend.xml for testing this module.

Init parameter in wmc:

The only parameter needed in the module configuration is the 'label' used for labeling the entire legend graphic.

<deegree:Module hidden="true" type="content" width="250" height="460">

<deegree:Name>Legend</deegree:Name>

<deegree:Content>legend_dyn.jsp</deegree:Content>

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>label</deegree:Name>

<deegree:Value>'Legend'</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

</deegree:Module>

Since this module carries out many more tasks than the simple Legend module (chapter 4.5), it needs to call the server side to generate the legend. It is therefore necessary to add an event handler to the controller.xml as described in chapter 7.2.

Init parameter in controller.xml:

The configuration parameters for the drawLegend event are described inline.

<event name="mapClient:drawLegend"
class="org.deegree.portal.standard.wms.control.DynLegendListener"
next="legend_dyn.jsp" alternativeNext="container.jsp">

<parameter>

<!-- left space to edge of legend -->

<name>leftMargin</name>

<value>0</value>

</parameter>

<parameter>

<!-- right space to edge of legend -->

<name>rightMargin</name>

<value>0</value>

</parameter>

<parameter>

<!-- top space to edge of legend -->

<name>topMargin</name>

<value>10</value>

</parameter>

<parameter>

<!-- bottom space to edge of legend -->

<name>bottomMargin</name>

<value>10</value>

</parameter>

<parameter>

<!-- printing the layer titles? true (yes) or false (no) -->

<name>useLayerTitle</name>

<value>true</value>

</parameter>

<parameter>

<!-- just for GetLegendGraphicRequests:
if a legend is smaller than eg. 50px the layer title will
be printed into the legend image -->

<name>maxNNLegendSize</name>

<value>50</value>

</parameter>

<parameter>

<!-- separating the legend images from each other
by an image -->

<name>separator</name>

<value>images/legendSeparator.gif</value>

</parameter>

<parameter>

<!-- image displayed if no legend can be found -->

<name>missingImage</name>

<value>images/missingLegend.gif</value>

</parameter>

<!-- for iGeoSecurity only: list of servers which need to be
accessed through an owsproxy to get a LegendGraphic -->
<parameter>

<name>users</name>

<!-- the value *must* be adjusted to your system -->

<value>
http://demo.deegree.org/deegree-wms/services;username;password|
http://deegree.org/owsproxy/proxy;username;password
</value>

</parameter>

</event>

The last parameter ('users') only needs to be set in GDI-environments using iGeoSecurity (see respective documentation for details). If only iGeoPortal is running, and no server is accessed via owsproxy, this parameter must be omitted.

If one or more servers need to be accessed through an owsproxy, the parameter 'users' needs to be set. The 'value' contains a list separated by | (pipe), where each entry consists of server-address;username;password. Username and password are the admin's login values for the respective owsproxy.

7. LayerListView

Description: The module 'LayerListView' is pretty similar to the 'Legend'-module. It describes also a list of the layers of a map but unlike the legend module it can be changed during runtime: layers can be shifted in their sequence and can be switched on or off. Besides, it is possible to define layers which can be queried by a GetFeatureInfo-request.

There are two implementations of 'LayerListView' available. The first (available through JavaScript file layerlistview.js) enables selecting one and only one layer for being target for GetFeatureInfo request (example context wmc_start_utah.xml). The other implementation (available through JavaScript file layerlistview_allfi.js) will always select all layers that are visible and queryable for GetFeatureInfo requests (example context wmc_saltlake.xml).

Init parameters:

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>name</deegree:Name>

<deegree:Value>'layerlistview'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>layerlist</deegree:Name>

<deegree:Value>this.layerList</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>label</deegree:Name>

<deegree:Value>'Wuppertal'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>bgcolor</deegree:Name>

<deegree:Value>'#c1d3ed'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>fgcolor</deegree:Name>

<deegree:Value>'#4D96DE'</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

The name, given first, is used for clear identification of the module; 'layerlist', 'label' and 'bgcolor' are used identically as for the module 'legend' above. Since the list of layer is generated dynamically, the font color for the list has to be set.

8. MapOverview

Description: The 'MapOverview' module provides an overview map at a set display resolution for the area of the entire context. MapOverview can be provided by a map server dynamically or simply by a georeferenced map graphic. Besides a JavaScript-object having the same name as the module, another JavaScript file is required (wz_jsgraphics_box.js) that is used for painting the current box describing the current extent of visible map.

Init parameter:

<deegree:Module hidden="false" type="content" width="150" height="150"
scrolling="no">

<deegree:Name>MapOverview</deegree:Name>

<deegree:Content>mapoverview.html</deegree:Content>

<deegree:ModuleJS>mapoverview.js</deegree:ModuleJS>

<deegree:ModuleJS>wz_jsgraphics_box.js</deegree:ModuleJS>

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>src</deegree:Name>

<deegree:Value>'./images/overview.gif'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>minx</deegree:Name>

<deegree:Value>2570000</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>miny</deegree:Name>

<deegree:Value>5668000</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>maxx</deegree:Name>

<deegree:Value>2593000</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>maxy</deegree:Name>

<deegree:Value>5691000</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>foregroundColor</deegree:Name>

<deegree:Value>'#ff0000'</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>width</deegree:Name>

<deegree:Value>150</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>height</deegree:Name>

<deegree:Value>150</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

</deegree:Module>

The parameter 'src' describes the source of the map overview presentation. A reference to a file as well as a GetMap-Request referring to a specific Web Map Service is permitted. The parameters 'minx', 'miny', 'maxx' and 'maxy' define the bounding box of the map overview. 'foregroundColor' controls the color of the painted box showing the extent of the actual mapview. 'width' and 'height' determine the size of the map overview in pixels.

9. Toolbar

Description: Above the map window is a tool bar for navigating the map in different ways: ZoomIn, ZoomOut, ZoomToLayer, go back to initial bounding box, recenter the map, drag the map. Also buttons for adding additional WMS to the portal and for creating a print pre-view are available. The amount, sequence and position of the visible buttons as well as their tool tips are controlled by the init parameters. Button parameter name

Init parameters:

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>refresh|refresh map</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>fullextent|zoom to full extent</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>movetoprevious|move to previous map</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>movetonext|next to previous map</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>zoomin|zoomin by mouse click or mouse drag</deegree:Name>

<deegree:Value>ToggleButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>zoomout|zoomout by mouse click</deegree:Name>

<deegree:Value>ToggleButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>zoom2layer|zoomtolayer by mouse click</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>
featureinfo|get info to a object within the map
</deegree:Name>

<deegree:Value>ToggleButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>recenter|recenter the map by mouse click</deegree:Name>

<deegree:Value>ToggleButton</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>
move|drag the map by mouse with pressed mouse button
</deegree:Name>

<deegree:Value>ToggleButton</deegree:Value>

</deegree:Parameter>

<deegree:Name>addwms|add additonal WMS to the map</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<!-- for printing choose EITHER "plain print" OR "pdf print" method -->

<!-- PLAIN PRINT -->

<deegree:Parameter>

<deegree:Name>print|generate print view</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<!-- PDF PRINT -->

<deegree:Parameter>

<deegree:Name>pdfprint|generate pdf</deegree:Name>

<deegree:Value>PushButton</deegree:Value>

</deegree:Parameter>

<!-- please delete the printing method that is not used -->

<deegree:Parameter>

<deegree:Name>selected</deegree:Name>

<deegree:Value>zoomin</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>bgcolor</deegree:Name>

<deegree:Value>'#e0e9f9'</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

Apart from the last two parameters – one controls the tool that is activated after initialising the portal (selected); the other one defines the background color of the tool bar – all others are defining a whole set of useful buttons. There are two kinds of buttons: 'PushButton' and 'ToggleButton'. The first returns to its initial condition after being pressed (similar to the Ok-button in a dialog); 'ToggleButton' stays switched on (or off) after clicking and activates a certain tool.

ToggleButtons are 'ZoomIn', 'ZoomOut', 'featureinfo' and 'recenter'; and PushButtons are 'refresh', 'home', 'fullextent', 'zoom2layer', 'addwms', 'download' and 'print'.

All init parameters, linked to an action/button, have a name consisting of two elements which are divided by '|'. The first one describes the name of the function for the according button. Currently deegree iGeoPortal comprises the following functions:

• refresh: Refresh Map if content has changed

• fullextent: Zoom to full extend

• home: Go to initial state of a map context

• movetoprevious: move to previous map

• movetonext: move to next map

• zoomIn

• zoomOut

• zoom2layer: zoom to the default bbox of the selected layer (4.9.1)

• featureinfo: Query Feature by click

• move: drag map by mouse click

• recenter: Recenter Map to click point

• addwms: Add other Web Map Services (4.9.2)

• print: Print current extent of Map (4.9.3)

• pdfprint: Print current extent of Map using iReport (4.9.4)

• fullScreen: Switch to a predefined version of the current context with reduced functionality but a much larger Map (4.9.5)

The functions zoom2layer, addWMS, print and pdfprint are configured using separate HTML-files described in the following sub-sections.

The layout of the buttons is defined by two graphic files that have to fulfil the naming convention and have to be placed in the appropriate directory $iGeoPortal_home$/images:

$componentname$.gif and $componentname$_a.gif

Example:

• zoomin.gif and zoomin_a.gif

• addwms.gif and addwms_a.gif

The first file represents the button in inactivate state; the second in its activated one. The file names are case sensitive! In order to change the layout of the buttons, you just have to exchange these 2 graphic files.

1. Zoom2Layer

The function zoom2Layer depends on the two files recentertolayer.html and recentertolayer.js in $iGeoPortal_home$ on the client side and the class org.deegree.portal.standard.wms.control.RecenterToLayerListener on the server side. In order to use this function a single layer has to be selected from the layer list (by clicking the layer name).

The mechanism is as follows: if the selected layer has a LatLonBBox (WMS Capabilities), but no ScaleHint, then the zoom goes to LatLonBBox. If the layer has both LatLonBBox and ScaleHint, it is first checked, if the scale hint reduces the size of the bounding box. If so, the reduced bbox is taken for zoom in. Otherwise, the original LatLonBBox is used to zoom in.

2. AddWMS

Via mouse click on 'addWMS', a dialog is opened for adding additional WMS instances: Either by typing the entire URL or by selecting a preconfigured entry. A list of preconfigured WMS instances can be predefined by the administrator in $iGeoPortal_home$/addwms.html.

...

<td width="30">&nbsp;</td>

<td width="90">known WMS: </td>

<td width="*">

<select id="knownwms" onchange="change()">

<option value="http://">select ...</option>

<option value="http://demo.deegree.org/deegree-wms/services">deegree demo WMS</option>

<option value="http://localhost:8080/deegree-wms/services">local deegree WMS</option>

</select>

</td>

...

By editing the select-block of the HTML document, the administrator is able to manipulate the preconfigured services.

3. Printing

By activating the print-button, the portal generates a representation of the actual map extent in a higher resolution to get high quality printings. By manipulating the parameters in $iGeoPortal_home$/printviewopener.html, the administrator can adapt size and quality of the printouts.

iGeoPortal communicates with the according server components via Remote Procedure Calls (RPCs). They contain the name of the function and potential parameters. In printviewopener.html you can find the JavaScript-function 'getRPCValues()' that provides the appropriate RPC for creating the print preview.

...

var s = "<?xml version='1.0' encoding='UTF-8'?><methodCall>" +

"<methodName>mapView:print</methodName><params>" +

"<param><value><struct>" +

"<member><name>paperFormat</name><value><string>A4</string></value></member>" +

"<member><name>resolution</name><value><string>150</string></value></member>" +

"<member><name>orientation</name><value><string>hoch</string></value></member>"+

"<member><name>format</name><value><string>jpeg</string></value></member>" +

"</struct></value></param>" +

...

The print preview is opened in a new window. Its contents may be adapted by changing the file $iGeoPortal_home$/printview.jsp. The map view is displayed with a lower resolution on screen than what is used for printing. The scaling might be adjusted by changing the style values for img.map width.

<style type="text/css">

@media print {

img.map {

width: 600; /* might need to be adjusted */

}

}

</style>

4. PFDPrinting

Description: This new module will be described soon. Please refer to wmc_testPdfPrint.xml or wmc_testPlayground.xml for testing.

5. FullScreen

Description: This new module will be described soon. Please refer to wmc_testFullScreen.xml or wmc_testPlayground.xml for testing.

10. MapView

Description: The module 'MapView' contains the central map view of the portal. Attention: Some JavaScript files are linked to this module.

<deegree:ModuleJS>mapview.js</deegree:ModuleJS>

<deegree:ModuleJS>mapcontroller.js</deegree:ModuleJS>

<deegree:ModuleJS>mapmodel.js</deegree:ModuleJS>

<deegree:ModuleJS>wmsrequestfactory.js</deegree:ModuleJS>

<deegree:ModuleJS>wmslayer.js</deegree:ModuleJS>

The module is responsible for the representation of the map as well as for the acceptance of map oriented mouse events. GetMap-, GetFeatureInfo- and GetLegend- requests for the active layer are also created by this module.

Init parameter:

<deegree:ParameterList>

<deegree:Parameter>

<deegree:Name>model</deegree:Name>

<deegree:Value>this.mapModel</deegree:Value>

</deegree:Parameter>

<deegree:Parameter>

<deegree:Name>border</deegree:Name>

<deegree:Value>0</deegree:Value>

</deegree:Parameter>

</deegree:ParameterList>

Merely two parameters are transferred to the module: The first one associates a JavaScript-Object with the module describing the model of the map view (with layer, size, etc.). Basically, it is possible to manage more than one map, where each one is connected with a different map model. The second parameter 'border' could define the thickness of a border painted around the map, but currently this is not implemented yet.

11. Digitizer

With iGeoPortal you are not only able to visualize, navigate and evaluate spatial data, you are also able to digitize own data online and transfer it via WFS-T (e.g. deegree WFS) into a data backend like PostgreSQL/POSTGIS. The digitized data will even be validated to avoid corrupt data insert (e.g. self intersects of polygons will not be accepted; error massage when digitizing polygons in clockwise direction instead of counter clockwise direction, ...).

You find a little appetizer map context with iGeoPortal demo. To see it in action you can either switch to "Salt Lake City" and then to the "Playground" context or you can edit the "Utah" context (wmc_start_utah.xml) in the module context switcher and comment out the element with only 2 contexts (default) and uncomment the one with the many test map contexts. See chapter 4.2 for details.

Afterwards you can switch to either Playground or TestDigitizer context and play around a bit.

In the on line demo, you can digitize a feature, do the WFS insert transaction and view the inserted feature in the map.

With your own installation from the deegree download pages the behaviour is different: by default, the WFS transaction will be aborted. If you would like to test the digitizing module completely, you need to (1) configure a WFS for the digitized features and (2) also adapt a few things in the digitizer module itself.

1. Setting up the WFS feature type

Description: This part will be described soon. Check the WFS documentation for general information on WFS installation and configuration.

2. Adapting the digitizer module

Each map context containing the module configuration for digitizer module, needs to be adapted to your local needs. The WFS address needs to be set to your WFS instance. See the above chapter for details.

All other configuration parameters of the digitizer module will be explained in more detail, soon. Some short hints can be found in the module configuration of the web map contexts.

Furthermore, you need to activate sending the insert-request to the WFS. The file modules/digitizer/digitizer_window.jsp contains a function sendRequest(), where a few changes need to be made. Just search for "TODO", and follow the instructions.

You would probably also want to increase the zoom factor of the digitizer map. Please search for "TODO" in the file modules/digitizer/digitizermodule.js and, again, follow the instructions.

Please note: as long as you don't have a properly configured WFS up and running, including the configuration of your feature type for digitizing, you will run into an error message when testing this module.

12. GazetteerClient

Another available module is the gazetteer client module. It is integrated in the web map context for playing around (wmc_testPlayground.xml) as well as in the wmc_testGazClient.xml context. This module is no out-of-the-box module. It needs special adjustments for each group of feature types within a Gazetteer-WFS, depending on what you wish to search for and how you like to display the results. Therefore, each gazetteer client module is different.

A more detailed documentation for the integrated example will be available within this document soon.

13. CSW-Client

Description: The CSW-Client module enables a user of iGeoPortal to send queries to an OGC-compliant Catalogue Service and to save the results in Web Map Context files. The module supports catalogues implementing the CS-W 2.0 ISO 19115/19119 Application profile in version 0.9.3. This module is “optional” in that it is not part of usual web map portals.

As this module implements some complex functionality its configuration is also more complex than for the average iGeoPortal module. First, the module has to be referred to, the layout of the portal has to be adjusted and finally the module itself has to be configured. All of these steps will be described in the following sections.

The iGeoPortal demo package includes a web map context configured for CS-W usage. When using this sample context it is only necessary to adjust the parameters defined in section 4.13.1. If you are interested in how the CSW-Client module can be integrated in an existing iGeoPortal instance, consider reading section 4.13.2.

The required .html, .jsp and .js files are located at $iGeoPortal_home$/modules/csw. XSLT-transformation scripts are located at $iGeoPortal _home$/WEB-INF/conf/igeoportal/csw.

For this demo of iGeoPortal v2.2 the CSW-client is not out the box configured.

1. Configuration of Web Map Context

   1. Parameter maxRecords

The parameter maxRecords defines how many hits of a query to a CSW-Service are processed. Using this parameter, the length of the resulting list of a query can be influenced.

<deegree:Parameter>

<!-- only this parameter is optional. default is 10. -->

<deegree:Name>maxRecords</deegree:Name>

<deegree:Value>10</deegree:Value>

</deegree:Parameter>

The parameter is optional. The default value is 10, which matches the default value of the corresponding OGC specification. If the parameter is omitted, the default value ist used. If a different value is provided, it will be used instead.

2. Parameter Profiles

This is in fact a group of parameters using the same prefix (“Profiles.”). At least one parameter with this prefix is mandatory. Allowed suffixes are “ISO 19115” and “OGCCORE”, although only “ISO 19115” is currently supported by iGeoPortal.

<deegree:Parameter>

<deegree:Name>Profiles.ISO19115</deegree:Name>

<deegree:Value>

'brief|metaList2html.xsl;full|metaContent2html.xsl'

</deegree:Value>

</deegree:Parameter>

The value of the parameter includes a list of value pairs consisting of an identifier, a separation marker ( „|“ ) and the name of an XSL-transformation file.

The identifier refers to the ElementSetName parameter of a GetRecords request to a CS-W. Allowed values are „brief“, „summary“ and „full“, although „summary“ is not supported so far.

The identifier “brief” refers to a transformation file (metaList2html.xsl) that creates a list of results from a GetRecordsResponse. The identifier “full” refers to a transformation file (metaContent2html.xsl) that transforms a full metadata record set from the results of a complete query (GetRecordByIdResponse).

Details of the transformation files are described in sections 4.13.2.5 and 4.13.1.9.

3. Parameter Catalogues

The parameter “Catalogues” defines which CSW-instance should be queried by the iGeoPortal CSW-Client module. It is mandatory to provide at least one catalogue service.

<deegree:Parameter>

<deegree:Name>Catalogues</deegree:Name>

<deegree:Value>

'CATA1|http://localhost:8085/deegree/services;
TEST|http://localhost:8085/deegree/test/catalogue'

</deegree:Value>

</deegree:Parameter>

The parameter value includes a list of pairs of identifiers (name of the catalogue service) delimited by the corresponding URL using “|”.

4. Parameter Protocols

This parameter defines with which protocol the catalogues can be accessed. Allowed values are “POST” and “SOAP”. If both values are provided for a catalogue, “SOAP” is used.

The parameter “Protocols” is mandatory, it must be declared in the configuration for each catalogue defined by the “Catalogues“-parameter (section 4.13.1.3).

<deegree:Parameter>

<deegree:Name>Protocols</deegree:Name>

<deegree:Value>'CATA1|POST;TEST|POST,SOAP'</deegree:Value>

</deegree:Parameter>

The parameter value contains a list of value pairs separated by semicolons. The value pairs consist of an identifier (name of the catalogue) followed by a delimiter (“|”) and a comma separated list of supported protocols.

5. Parameter Formats

The parameter “Formats” defines which catalogue understand and supports which format. Possible formats are „ISO 19115“, „ISO 19119“ and „OGCCORE“.

The parameter is mandatory, at least one format type must be provided for each catalogue defined by „Catalogues“ (section 4.13.1.3).

<deegree:Parameter>

<deegree:Name>Formats</deegree:Name>

<deegree:Value>'CATA1|ISO19115;TEST|ISO19119'</deegree:Value>

</deegree:Parameter>

The parameter value consists of a list of value-pairs separated by semicolons. The value pairs consist of an identifier (name of the catalogue) followed by a delimiter (“|”) and a comma separated list of possible formats.

6. Parameter mapContextTemplate

The parameter “mapContextTemplate” defines which file is used as template of user specific Web Map Context documents. The file is located inside $iGeoPortal_home$ at the location defined by this parameter. This parameter is mandatory.

<deegree:Parameter>

<deegree:Name>mapContextTemplate</deegree:Name>

<deegree:Value>

'WEB-INF/conf/igeoportal/users/mapContextTemplate.xml'

</deegree:Value>

</deegree:Parameter>

It is recommended to use a copy of an existing Web Map Context file and deleting the content of its <LayerList> element (see following example).

<?xml version="1.0" encoding="UTF-8"?>

<ViewContext xmlns="http://www.opengis.net/context"
xmlns:sld="http://www.opengis.net/sld"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="1.0.0" id="String">

<General>

...

<!-- the same as always -->

...

</General>

<LayerList>

<!-- empty space for new user layers -->

</LayerList>

</ViewContext>

In case a user that is logged onto the system has (at least) one metadata set added to his shopping cart, he is allowed to save the list of layers and display it in the portal (if all chosen datasets are accessible via WMS). All of these datasets are added to the declared template and saved in the directory of the user.

7. Parameter namespaceBindings

The parameter „namespaceBindings“ is mandatory. It defines a list (semicolon separated) of all namespaces that are needed by the CSW client module.

<deegree:Parameter>

<deegree:Name>namespaceBindings</deegree:Name>

<deegree:Value>

'xmlns:csw=http://www.opengis.net/cat/csw;xmlns:iso19115=http://schemas.opengis.net/iso19115full;xmlns:iso19115brief=http://schemas.opengis.net/iso19115brief;xmlns:iso19119=http://schemas.opengis.net/iso19119;xmlns:smXML=http://metadata.dgiwg.org/smXML'

</deegree:Value>

</deegree:Parameter>

The list always includes the definition of xmlns:csw, as well as the namespaces of the used schemas ( ISO 19115 / OGCCORE ).

8. Parameter XpathTo***

In this section a number of parameters are described that include a declaration of an XPath to a specific part of a csw:GetRecordResponse. These path expressions depend on the used schema (ISO 19115, ISO 19119, OGCCORE) and therefore it may be necessary to adjust them.

The path to be supplied is the end part of the metadata element.

<!-- The parameter value to be specified is represented by [thisPartOnly]
in the following line:

/csw:GetRecordsResponse/csw:SearchResults/[MetadataElement]/[thisPartOnly]
-->

For ISO 19115 this means that the path to the FileIdentifier does not need to be referenced by using

/csw:GetRecordsResponse/csw:SearchResults/smXML:MD_Metadata/iso19115brief:fileIdentifier/smXML:CharacterString

but that the beginning part can be omitted. Only iso19115brief:fileIdentifier/smXML:CharacterString has to be supplied.

This behavior applies to all XPathTo*** parameters.

Inside the XPath expressions, all usual possibilities are allowed. An example can be seen for XPathToServiceAddress.

The parameter XPathToDataId defines the path to the unique identifier of the data metadataset.

<deegree:Parameter>

<deegree:Name>XPathToDataId</deegree:Name>

<deegree:Value>

'iso19115brief:fileIdentifier/smXML:CharacterString'

</deegree:Value>

</deegree:Parameter>

The parameter XPathToDataTitle defines the path to the title of the data metadataset, if the query is executed using ElementSetName=“brief“.

<deegree:Parameter>

<deegree:Name>XPathToDataTitle</deegree:Name>

<deegree:Value>

'iso19115brief:identificationInfo/smXML:MD_DataIdentification/smXML:citation/smXML:CI_Citation/smXML:title/smXML:CharacterString'

</deegree:Value>

</deegree:Parameter>

The parameter XPathToDataTitleFull defines the path to the title of the data metadataset, if the query is executed using ElementSetName=“full“.

<deegree:Parameter>

<deegree:Name>XPathToDataTitleFull</deegree:Name>

<deegree:Value>

'iso19115:identificationInfo/smXML:MD_DataIdentification/smXML:citation/smXML:CI_Citation/smXML:title/smXML:CharacterString'

</deegree:Value>

</deegree:Parameter>

The parameter XPathToServiceId supplies the path to the unique identifier of the service metadataset.

<deegree:Parameter>

<deegree:Name>XPathToServiceId</deegree:Name>

<deegree:Value>

'smXML:fileIdentifier/smXML:CharacterString'

</deegree:Value>

</deegree:Parameter>

The parameter XPathToServiceTitle supplies the path to the title of the service, that allows access to the dataset.

<deegree:Parameter>

<deegree:Name>XPathToServiceTitle</deegree:Name>

<deegree:Value>

'smXML:identificationInfo/iso19119:CSW_ServiceIdentification/smXML:citation/smXML:CI_Citation/smXML:title/smXML:CharacterString'

</deegree:Value>

</deegree:Parameter>

The Parameter XPathToServiceOperatesOnTitle supplies the path to the title of the data metadataset, that the current dataset of the service metadata refers to.

<deegree:Parameter>

<deegree:Name>XPathToServiceOperatesOnTitle</deegree:Name>

<deegree:Value>

'smXML:identificationInfo/iso19119:CSW_ServiceIdentification/iso19119:operatesOn/smXML:MD_DataIdentification/smXML:citation/smXML:CI_Citation/smXML:title/smXML:CharacterString'

</deegree:Value>

</deegree:Parameter>

The parameter XPathToServiceAddress supplies the path to the service address at which the Capabilities of the service can be queried, that supplies the title, which is read from XpathToServiceOperatesOnTitle.

<deegree:Parameter>

<deegree:Name>XPathToServiceAddress</deegree:Name>

<deegree:Value>

'smXML:identificationInfo/iso19119:CSW_ServiceIdentification/iso19119:operationMetadata[iso19119:SV_OperationMetadata/iso19119:operationName/smXML:CharacterString="GetCapabilities"]/iso19119:SV_OperationMetadata/iso19119:connectPoint/smXML:CI_OnlineResource/smXML:linkage/smXML:URL'

</deegree:Value>

</deegree:Parameter>

The parameter XPathToServiceType supplies the path to the service type of the service, that has the Title XPathToServiceTitle.

<deegree:Parameter>

<deegree:Name>XPathToServiceType</deegree:Name>

<deegree:Value>

</deegree:Value>

'smXML:identificationInfo/iso19119:CSW_ServiceIdentification/iso19119:serviceType/smXML:CharacterString'

</deegree:Parameter>

The parameter XPathToServiceTypeVersion supplies the path to the version of the service type.

<deegree:Parameter>

<deegree:Name>XPathToServiceTypeVersion</deegree:Name>

<deegree:Value>

'smXML:identificationInfo/iso19119:CSW_ServiceIdentification/iso19119:serviceTypeVersion/smXML:CharacterString'

</deegree:Value>

</deegree:Parameter>

9. Configuration of transformation files

The transformation files are used to transform the xml-encoded files of the CSW into HTML. Furthermore, they define the subset of the metadata that is displayed in the portal. In the CSW client module of the Web Map Context (e.g. wmc_testCswClient.xml) the used transformation files are defined using the parameter Profiles.* (see section 4.13.1.2). The structure of the files should not be changed, as usually only adjustment of the HTML contents are necessary.

10. Transformation of result sets

The file metaList2html.xsl lists the results of a query.

The first template is executed in case the CSW sends an error message:

<xsl:template match="ogc:ServiceExceptionReport">

<table class="except">

<tr>

<td class="key">Error</td>

<td class="val">

<xsl:value-of select="./ogc:ServiceException"/>

</td>

</tr>

</table>

</xsl:template>

The following template should be left unchanged:

<xsl:template match="csw:GetRecordsResponse">

<xsl:apply-templates select="csw:SearchResults"/>

</xsl:template>

In this template another template (<xsl:template match="csw:SearchResults">) is included, that can be adjusted. The corresponding part are displayed here in detail.

The complete page is built using a table of three rows. The first row shows the heading, the second adds the list of query results, while the third adds buttons for navigating through the result set.

The following segment declares the heading on top of the query results.

<tr>

<td class="key" colspan="2">

Catalogue <xsl:value-of select="$CATALOG"/> hat insgesamt
<xsl:value-of select="$HITS"/> Ergebnisse.

</td>

</tr>

All further rows of the table will only be displayed if the result set is greater than 0. First, a list of all hits is defined (<ul>).

<tr>

<td class="val" colspan="2">

<ul><xsl:apply-templates select="iso19115brief:MD_Metadata"/></ul>

</td>

</tr>

If the file should not be used for processing ISO 19115 queries, but for OGCCORE, the name of the node to select has to be adjusted.

Following is a row with the buttons for navigating the result set. The left cell includes the graphics file for going backward, the right one for going forwards.

<tr>

<td width="50%" align="right">

<xsl:choose>

<xsl:when test="$STARTPOS > 0">

<a href="{$previousPage}">

<img src="./images/csw_previous.gif" border="0" alt="prevpage"/>

</a>

</xsl:when>

<xsl:otherwise>

<xsl:text disable-output-escaping="yes">&amp;nbsp;</xsl:text>

</xsl:otherwise>

</xsl:choose>

</td>

<td width="50%" align="left">

<xsl:choose>

<xsl:when test="($STARTPOS + $recReturned) &lt; $HITS">

<a href="{$nextPage}">

<img src="./images/csw_next.gif" border="0" alt="nextpage" />

</a>

</xsl:when>

<xsl:otherwise>

<xsl:text disable-output-escaping="yes">&amp;nbsp;</xsl:text>

</xsl:otherwise>

</xsl:choose>

</td>

</tr>

The graphics files can be replaced by text or other graphics.

The last template in the file fills the list of found hits. At the beginning, a number of variables is declared, that is then used for the list entry and the corresponding reference. Basically, adjustments to this template are limited to the style of the list entry and the reference (in bold).

<xsl:template match="iso19115brief:MD_Metadata">

<xsl:variable name="ident">

<xsl:value-of select="./iso19115brief:fileIdentifier/smXML:CharacterString"/>

</xsl:variable>

<xsl:variable name="title">

<xsl:value-of select="./iso19115brief:identificationInfo/smXML:MD_DataIdentification/smXML:citation/smXML:CI_Citation/smXML:title/smXML:CharacterString"/>

</xsl:variable>

<xsl:variable name="minx">

<xsl:value-of select="./iso19115brief:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:westBoundLongitude/smXML:approximateLongitude"/>

</xsl:variable>

<xsl:variable name="maxx">

<xsl:value-of select="./iso19115brief:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:eastBoundLongitude/smXML:approximateLongitude"/>

</xsl:variable>

<xsl:variable name="miny">

<xsl:value-of select="./iso19115brief:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:southBoundLatitude/smXML:approximateLatitude"/>

</xsl:variable>

<xsl:variable name="maxy">

<xsl:value-of select="./iso19115brief:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:northBoundLatitude/smXML:approximateLatitude"/>

</xsl:variable>

<xsl:variable name="args" select="concat( $quote, $ident, $quote, ', ', $quote, $CATALOG, $quote, ', ', $minx, ', ', $miny, ', ', $maxx, ', ', $maxy, ', ', $quote, 'showMetadataOverview', $quote )" />

<xsl:variable name="href" select="concat( 'javascript:getMetadata( ', $args, ' )' )"/>

<li>

<a href="{$href}"><xsl:value-of select="$ident"/></a>

</li>

</xsl:template>

Additional adjustments would only be necessary if the structure of the ISO 19115 should be changed or if it is intended to use OGCCORE queries. In the latter case, this should be done in a separate file.

11. Transformation of a single result

The file metaContent2html.xsl is defined in the Web Map Context for display of a single result (see section 4.13.2.5). The distinction between overview and detailed display is done by inclusion of two additional files.

<xsl:include href="file:///absolute/path/to/$iGeoPortal_home$/WEB-INF/conf/igeoportal/metaOverview2html.xsl"/>

<xsl:include href="file:///absolute/path/to/$iGeoPortal_home$/WEB-INF/conf/igeoportal/metaDetails2html.xsl"/>

A distinction is made between different headings and contents by using the parameter <xsl:param name="METAVERSION"/>.

<xsl:template match="csw:GetRecordByIdResponse">

<table align="center">

<tr>

<td>

<xsl:if test="$METAVERSION = 'overview'">

<p class="title">searchResult item overview</p>

</xsl:if>

<xsl:if test="$METAVERSION = 'detailed'">

<p class="title">searchResult item details</p>

</xsl:if>

</td>

</tr>

<tr>

<td>

<xsl:if test="$METAVERSION = 'overview'">

<xsl:call-template name="OV_MD_Metadata"/>

</xsl:if>

<xsl:if test="$METAVERSION = 'detailed'">

<xsl:call-template name="DE_MD_Metadata"/>

</xsl:if>

</td>

</tr>

</table>

</xsl:template>

The templates marked in bold are read from the included files and have to be adjusted if needed.

The file metaOverview2html.xsl defines which information will be displayed in the metadata overview. It is possible to adjust these values by editing the template (possibly defining additional variables).

<!-- variables -->

<xsl:variable name="ServLength">

<xsl:value-of select="string-length($SERVICECATALOGS)"/>

</xsl:variable>

<xsl:variable name="ident">

<xsl:value-of select="./iso19115:MD_Metadata/iso19115:fileIdentifier/smXML:CharacterString"/>

</xsl:variable>

<xsl:variable name="title">

<xsl:value-of select="./iso19115:MD_Metadata/iso19115:identificationInfo/smXML:MD_DataIdentification/smXML:citation/smXML:CI_Citation/smXML:title/smXML:CharacterString"/>

</xsl:variable>

<xsl:variable name="minx">

<xsl:value-of select="./iso19115:MD_Metadata/iso19115:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:westBoundLongitude/smXML:approximateLongitude"/>

</xsl:variable>

<xsl:variable name="maxx">

<xsl:value-of select="./iso19115:MD_Metadata/iso19115:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:eastBoundLongitude/smXML:approximateLongitude"/>

</xsl:variable>

<xsl:variable name="miny">

<xsl:value-of select="./iso19115:MD_Metadata/iso19115:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:southBoundLatitude/smXML:approximateLatitude"/>

</xsl:variable>

<xsl:variable name="maxy">

<xsl:value-of select="./iso19115:MD_Metadata/iso19115:identificationInfo/smXML:MD_DataIdentification/smXML:extent/smXML:EX_Extent/smXML:geographicElement/smXML:EX_GeographicBoundingBox/smXML:northBoundLatitude/smXML:approximateLatitude"/>

</xsl:variable>

<xsl:variable name="topicCategory"><!-- this variable is optional -->

<xsl:value-of select="./iso19115:MD_Metadata/iso19115:identificationInfo/smXML:MD_DataIdentification/smXML:topicCategory/smXML:MD_TopicCategoryCode"/>

</xsl:variable>

<xsl:variable name="quote">

<xsl:text disable-output-escaping="yes">'</xsl:text>

</xsl:variable>

<xsl:variable name="args" select="concat( $quote, $ident, $quote, ', ', $quote, $title, $quote, ', ', $quote, $CATALOG, $quote, ', ', $minx, ', ', $miny, ', ', $maxx, ', ', $maxy, ', ', $quote, $SERVICECATALOGS, $quote )" />

<xsl:variable name="shoppingRef" select="concat( 'javascript:addToShoppingCart( ', $args, ' );' )"/>

Besides „topicCategory“ all of the listed variables are needed for program execution. If the ISO 19115 schema is changed it might be necessary to adjust the paths. Additional variables can be used to extend the overview table.

<!-- contents -->

<table class="md">

<tr>

<td class="key">TopicCategory</td>

<td class="val"><xsl:value-of select="$topicCategory"/></td>

</tr>

<tr>

<td class="key">Identifier</td>

<td class="val"><xsl:value-of select="$ident"/></td>

</tr>

<tr>

<td class="key">Title</td>

<td class="val"><xsl:value-of select="$title"/></td>

</tr>

<tr>

<td class="key">ServiceCatalogues</td>

<xsl:choose>