This file is specified by the URL key=configvalue. It is best to locate this file on the BerkeleyMapper for faster performance. However, you may put this file on any server and insert a URL string as the value. Speak to the system administrator to put this file on the BerkeleyMapper.
Table of contents
i. A Note on Special Characters
Since data is passed using XML documents, embedded in databases, and sometimes coming from text documents, care should be taken in using special characters. It is reccomended to use the named entity references (see, for example http://home.earthlink.net/~bobbau/platforms/specialchars/). In addition, any & symbol should be entered as a named reference, even when used in identify named references.
As an example, suppose you wanted to use °C as a label. It would take the following form in your XML configuration file:
°C
1. Opening Tag
<berkeleymapper>
2. Metadata Section
<metadata>
| Element: | <name> |
| Attributes: | None |
| Repeatable: | No |
| Example: | <name>MVZ Map Configuration File</name> |
| Description: | Description of what this configuration file is for. |
| Element: | <mapwiki> |
| Attributes: | organization,email |
| Repeatable: | No |
| Example: | <mapwiki organization="Museum of Vertebrate Zoology" email="fredflintstone@aol.com" /> |
| Description: | Instruct mapwiki calls to fill in default organization and email. |
| Element: | <relatedinformation> |
| Attributes: | None |
| Repeatable: | No |
| Example: | <relatedinformation>http://mvz.berkeley.edu/</relatedinformation> |
| Description: | Link for more information on the group this mapping configuration applies to. |
| Element: | <abstract> |
| Attributes: | None |
| Repeatable: | No |
| Example: | <abstract>GIS configuration file for MVZ query interface</abstract> |
| Description: | A more in-depth description of what the purpose of this application does for the group. |
| Element: | <datumshift> |
| Attributes: | Value |
| Repeatable: | No |
| Example: | <datumshift value="true"></datumshift> |
| Description: | Attempt to perform datum transformations where possible so points display in WGS84. This currently only works with NAD27. The field darwin_horizontaldatum must contain text indicating source datum for this transformation to occur. |
| Element: | <mapkeyword> |
| Attributes: | keyword |
| Repeatable: | No |
| Example: | <mapkeyword keyword="specimens"></mapkeyword> |
| Description: | This specifies what we are mapping. By default is specimens but if you put another word here, it will refer to the points as this word. |
| Element: | <turnoffgooglelayers> |
| Attributes: | Value |
| Repeatable: | No |
| Example: | <turnoffgooglelayers value="true"></turnoffgooglelayers> |
| Description: | If this value is set, the application will ONLY use user-defined layers. This is only reccomended in cases where there is little or no Google data available, Example: islands in the South Pacific or other remote areas with no data, or only when looking at data that is zoomed in, like the UC Botanical Garden. NOTE: setting this option will disable certain features, such as zoom by box since BerkeleyMapper needs Google base layers for certain features to function. |
| Element: | <turnoffiframe> |
| Attributes: | iframe |
| Repeatable: | No |
| Example: | <turnoffiframe iframe="1"></turnoffiframe> |
| Description: | Default is to use iframes if browser allows it. If you don't like iframes in your application you can turn them off be setting the iframe value to 1. Setting to 0 or not putting this line it at all will allow iframes |
| Element: | <header> |
| Attributes: | location |
| Repeatable: | No |
| Example: | <header location="http://somewhere.my.header/"></header> |
| Description: | You can use an image or a file. |
| Element: | <footer> |
| Attributes: | location |
| Repeatable: | No |
| Example: | <footer location="http://somewhere.my.footer/"></footer> |
| Description: | You can use an image or a file. |
| Element: | <linkbackheader> |
| Attributes: | location |
| Repeatable: | No |
| Example: | <linkbackheader location="http://mvz.berkeley.edu/"></linkbackheader> |
| Description: | URL link to attach to header image. |
| Element: | <charset> |
| Attributes: | name |
| Repeatable: | No |
| Example: | <charset name="UTF-8"></charset> |
| Description: | Default charset is ISO-8859-1 (latin1). If you want another character set to be the default then specify it here. For a list of character set names you can pass in, visit: http://www.iana.org/assignments/character-sets |
| Element: | <units> |
| Attributes: | key |
| Repeatable: | No |
| Example: | <units key="km"></units> |
| Description: | Default units are mi (miles). Can specify km (kilometers) or acres using the example above to override this default and this will be used throughout the application. Both miles and kilometers will break down to meters and feet for distances less than 1/2 kilometer or 1/2 mile respectively. If you specify acres, then linear distances will use feet and miles and areas will be in acres. |
| Element: | <extent> |
| Attributes: | value |
| Repeatable: | No |
| Example: | <extent value="-122.240619692407 37.8719538523575 -122.234643165877 37.8759382033771"></extent> |
| Description: | Set the default extent to begin with for map application. value is in the form "xmin ymin xmax ymax" |
| Element: | <bmzoom> |
| Attributes: | value |
| Repeatable: | No |
| Example: | <bmzoom value="15" /> |
| Description: | Sets the starting Zoom scale for the map application. lowest value available is 1 (the entire earth) and highest value is 17 (as far as google normally goes, unless special layers are used). |
| Element: | <mingooglezoom> |
| Attributes: | value |
| Repeatable: | No |
| Example: | <mingooglezoom value="22" /> |
| Description: | Minimum Google Zoom scale for application. Use this in areas where you have an extremely detailed map and want to see greater detail than what is available normally (E.g. in the UC Botanical Garden). |
| Element: | <maxgooglezoom> |
| Attributes: | value |
| Repeatable: | No |
| Example: | <maxgooglezoom value="9" /> |
| Description: | Maximum Google Zoom for application. Sets a custom number for how far the application can zoom in. Use this in areas where no Google Map data is known to exist below this scale, E.g. French Polynesia has no data below zoom level 9 as of March, 2006. |
| Element: | <defaultscreensize> |
| Attributes: | value |
| Repeatable: | No |
| Example: | <defaultscreensize value="600" /> |
| Description: | Avalaible values are 800 (800x600), 600 (600x400), or 400 (400x300) |
| Element: | <disclaimer> |
| Attributes: | |
| Repeatable: | No |
| Example: | <disclaimer><![CDATA[Data records provided by ORNIS may be used by individual researchers or research groups, but they may not be repackaged, resold, or redistributed in any form without the express written consent of the original institution where those records are held. |
| Description: | This is a user-supplied disclaimer to display when users are downloading data. Make sure you use the CDATA syntax if you include HTML tags here. |
</metadata>
3. Settings Section
<settings>
| Element: | <setting> |
| Attributes: | name: see following list of names show: 0 (false) or 1 (true) |
| Repeatable: | Yes |
| Example: | <setting name="landsat" show="0"></setting> |
| Description: | This is where persistent settings go that form the shape of the application for the user. More dynamic settings should go into the URL string and you should consult the appropriate documentation for that. All settings default to true so it is safe to only specify settings you want to turn off. |
| List of names: | |
| screensize | (show the screensize drop down box) |
| landsat | (offer the landsat wms service as a background image option-- currently this layer has a 150 meter offset but the application does not allow a closer viewing than 1:65000 scale to obscure the error. JPL is working to rectify this.) |
| globe_bw | (black and white global elevation stored locally on server) |
| drg | (digital raster graphic from terraserver) |
| doq | (digital orthoquad from terraserver) |
| finerelief | (World relief image from CubeWerx) |
| slowcxn | (show checkbox to allow users to indicate if they are on a slow connection so images will be drawn in 8bit mode and background image option=auto will send less graphics) |
| maxerrorinmeters | (show the show precision symbols checkbox) |
| colorprecision | (show color by precision option in drop down list for color by) |
| coloryearcollected | (show color by year collected option in drop down list for color by) |
| label | (show label place names checkbox) |
| labelby | (show or not show drop down box to labelby feature) |
| opaque | (show the Dim Background Images checkbox) |
| units | (show the Distance & Area Measurements Drop-down box so user can pick their own units) |
| backgroundimage | (show or not show drop down list of background images) |
| embedscalebar | (show or not show embedscalebar checkbox. Note-- if you you don't want to see this at all then you will need to pass in URL parameter setting this to 0 as well since it defaults to on) |
</settings>
4. Record LinkBack Section
<recordlinkback>
| Element: | <linkback> |
| Attributes: | method: how to linkback linkurl: url to use text: text to display inside href tag fieldname: name of field key1: Concept Alias value1: Concept Name key2: ... value2: ... key5: value5 |
| Repeatable: | No |
| Example 1: | the linkurl attribute specifies a fully formed link(href tag) pointing to the concept element (see Concepts section, below) that stores this information, which comes from the tab delimited file.<linkback method="entireurl" linkurl="RelatedInformation" fieldname="Link Back"></linkback> |
| Example 2: | the linkurl attribute specifieds a URL root and key/value pairs are passed in from file. key/value pairs are specified as attributes (up to 5). The key points to the conceptalias and the value points to the concept name.<linkback method="root" linkurl="http://elib.cs.berkeley.edu/cgi-bin/mvz_query" text="View Details" fieldname="Link Back" key1="Coll_Object_id" value1="undefined_2"></linkback> |
| Example 3: | don't provide any linkback<linkback>method="none"</linkback> |
| Description: | This application allows users to pass in either fully formed href tags or partial tags with specified key/value pairs passed from tab delimited file. Data must come from the tab delimited file specified in the tabfile URL parameters. |
</recordlinkback>
5. Themes Section
<themes >
| Element: | <theme> |
| Attributes: | method: what theme ("coloryearcollected" "colorprecision" are the only values right now.) fieldname: The name of the field to map to containing data for the theme (year collected or precision in meters data) |
| Repeatable: | yes |
| Examples: | <theme method="coloryearcollected" fieldname="darwin:yearcollected" /> <theme method="colorprecision" fieldname="darwin:coordinateuncertaintyinmeters" /> |
| Description: | Themes allow users to specify content themes for visualizing the data. The application controls value ranges and colors, but the user can specify in this section what data should be used for a particular theme and by specifying it in this file, it means they choose to turn on that functionality. Themes require some custom coding so make a request to the programmer if you want an additional theme for your data. |
</themes>
6. Colors Section
<colors method="field" fieldname="" label="">
| Element: | <colors> |
| Attributes: | method: how colors are specified ("field" and "dynamicfield" are answers -- field requires color children whereas dynamic field searches in the contents of the fieldname specified, groups, and dynamically assigns colors) fieldname: The name of the field to map to label: Legend Label for point colors |
| Repeatable: | No |
| Example: | <colors method="field" fieldname="darwin:collectioncode" label="Key to Point Colors"> |
| Description: | You can use a field in your tab delimited input file to control the colors displayed on the map. This element tells us what field to use. The children which are repeatable map the values in this field to particular rgb values. |
| Element: | <color> |
| Attributes: | key: value to map to red: 0-255 green: 0-255 blue: 0-255 label: what this value means symbol: optional symbol type (1-tent, 2-star, 3-triangle, 4-square, 5-plus, 6-cross, 7-circle (default) size: 1-20 (1 is smallest) |
| Repeatable: | Yes |
| Example: | <color key="mamm" red="255" green="0" blue="0" label="Mammal Collection" /> |
| Description: | put in a color element for each value. |
| Element: | <dominantcolor> |
| Attributes: | webcolor |
| Repeatable: | No |
| Example: | <dominantcolor webcolor="ffcc33" /> |
| Description: | Web color for dominant color scheme |
| Element: | <subdominantcolor> |
| Attributes: | webcolor |
| Repeatable: | No |
| Example: | <subdominantcolor webcolor="ffcc33" /> |
| Description: | Web color for subdominant color scheme |
| Element: | <textdominantcolor> |
| Attributes: | webcolor |
| Repeatable: | No |
| Example: | <textdominantcolor webcolor="ffffff" /> |
| Description: | Web color for text dominant color scheme. Defaults to black if not set. |
| Element: | <rowselectcolor> |
| Attributes: | webcolor |
| Repeatable: | No |
| Example: | <rowselectcolor webcolor="ffff00" /> |
| Description: | Web color to use for row select color. Defaults to yell if not set. |
</colors>
7. Matching tab-delimited fields to Map schema
<concepts xmlns:darwin="http://digir.net/schema/conceptual/darwin/2003/1.0">
| Element: | <concept> |
| Attributes: | viewlist: 0 means do not show this field in query results. 1 means to show it. colorlist: 0 means do not add this as an option under 'Color By'. 1 means add this as an option to 'Color By', so the user can display unique colors for each unique value in this field. datatype: name of concept in mapfile schema or specification of new datatype. alias: Your name for this field which will also appear on column headings of query results. order: any number to designate what order this should be displayed in results table. |
| Repeatable: | No |
| Example: | See following file: |
| Description: | This section defines names of server-side-fields, aliases, and whether we want to view it. If there are concepts outside the map schema, then they go into sequentially numbered, typed fields (char120:1-8,char255:1-8,longtext:1-4,int:1-4,float:1-4). The order of the fields MUST match the order of the fields in the tab delimited file being passed to this application. |
<concept viewlist="1" colorlist="0" datatype="darwin:catalognumbertext" alias="CatalogNumber" order="1" /> <concept viewlist="1" colorlist="1" datatype="darwin:scientificname" alias="ScientificName" order="2" /> <concept viewlist="0" colorlist="1" datatype="darwin:country" alias="Country" order="9" /> <concept viewlist="0" colorlist="0" datatype="darwin:stateprovince" alias="StateProvince" order="3" /> <concept viewlist="1" colorlist="1" datatype="darwin:county" alias="County" order="4" /> <concept viewlist="0" colorlist="0" datatype="char120:1" alias="id_modifier" order="11" /> <concept viewlist="0" colorlist="0" datatype="char120:2" alias="Coll_Object_id" order="12" /> <concept viewlist="0" colorlist="0" datatype="char120:3" alias="type_status" order="5" /> <concept viewlist="0" colorlist="1" datatype="char120:4" alias="class" order="5" /> <concept viewlist="0" colorlist="1" datatype="char120:5" alias="order" order="50" /> <concept viewlist="0" colorlist="1" datatype="char120:6" alias="family" order="10" /> <concept viewlist="0" colorlist="0" datatype="char120:7" alias="tissues" order="19" /> <concept viewlist="0" colorlist="0" datatype="char120:8" alias="sex_cde" order="20" /> <concept viewlist="1" colorlist="0" datatype="darwin:collectioncode" alias="CollectionCode" order="1" /> <concept viewlist="0" colorlist="0" datatype="darwin:decimallatitude" alias="DecimalLatitude" order="20" /> <concept viewlist="0" colorlist="0" datatype="darwin:decimallongitude" alias="DecimalLongitude" order="21" /> <concept viewlist="0" colorlist="0" datatype="darwin:coordinateuncertaintyinmeters" alias="CoordinateUncertaintyInMeters" order="22" /> <concept viewlist="1" colorlist="0" datatype="darwin:horizontaldatum" alias="HorizontalDatum" order="23" /></concepts>
8. GIS Data Section
<gisdata>
| Element: | <layer> |
| Attributes: | title: Title of this layer as it appears in legend and to the user name: Internal name for this layer (corresponds to Mapserver Name used in Layer definition) location: Location of Mapserver Layer Definition. Can exist anywhere that is web-accessible legend: Value of 1 means to include in legend and 0 means to leave it out. active: Value of 1 means to make this layer active by default. Value of 0 will display this layer to the user but box will not be checked by default. url: URL that points to more information about the source of this layer. |
| Repeatable: | yes |
| Examples: |
A particular shapefile (that is loaded on server): <layer title="Plant Bed Layers" name="plant_bed_areas" location="/data/ucbg/plant_bed_areas.lyr" legend="1" active="1" url="http://someurl.com/" /> Global Amphibian Assessment (must dynamically construct config file for each species): <layer title="GAA Bufo canorus Distribution" name="gaa" location="Bufo canorus" legend="1" active="1" url="http://www.iucnredlist.org/amphibians"/> NatureServe North American Bird Ranges (must dynamically construct config file for each species): <layer title="NatureServe North American Bird Distribution" name="birds" location="Lagopus lagopus" legend="1" active="1" url="http://www.natureserve.org/getData/birdMaps.jsp"/> NatureServe North American Mammal Ranges (must dynamically construct config file for each species): <layer title="NatureServe North American Mammal Distribution" name="mamm" location="Lynx rufus" legend="1" active="1" url="http://www.natureserve.org/getData/mammalMaps.jsp"/> |
| Description: | This option allows users to pass in multiple layers that are custom to their application. Layer definitions must be in the form of Mapserv Mapfile format. Layers can be shapefiles, loaded in Postgres, or accessible via WMS. See admin for assistance. |
</gisdata>
9. Join File Specification (mandatory for ViewResults=join, uneccesary for other options>
| Element: | <join> |
| Attributes: | tablename: TableName of layer with polygons you want to join to (must be in Postgres) fieldname: FieldName of column to join to join to in postgres. fieldname2: FieldName of column to join to join to in postgres for 2nd join field. projection: Custom projection definition for this layer (reccomended to use layer in decimal degrees and to leave this blank currently) label: Value of 1 means to label polygons by default and 0 to not label. title: The title to use for this layer in the legend (what the user sees) myjoinfield: The name of the field that you passed in, in the concepts section you wish to join to myjoinfield2: The name of a second field to pass in so you can join on two fields (e.g. County AND State) identifier: a succinct description of what the polygons refer to. option: Name of a postgres option modifier to use when joining. For example, if internal data is stored as upper case only you can use 'upper'. |
| Repeatable: | no |
| Examples: | <join tablename="plant_bed_areas" fieldname="bed_id" projection="" label="1" title="Selected Plant Bed Area(s)" myjoinfield="darwin:catalognumbertext" identifier="plant bed" /> |
| Description: | This option is for joining dynamic data passed in from a tab delimited text file to a polygon layer stored in postgres. Please see the admin for assistance in loading polygon layer for joining. |
10. Annotation Section
<annotation show='1'>
| Element: | <annotation_replyto_email> |
| Attributes: | value: email receiving annotation request |
| Repeatable: | No |
| Example: | <annotation show='1'><annotation_replyto_email value='foobar@foo.com' /></annotation> |
| Description: | Map annotation currently just gets map images and sets of points and allows the user to send comments to a specified email address. If an email address is not specified in annotation_replyto_email tag then it goes to bnhm@berkeley.edu. Later revisions will allow user to draw on the map and do more fancy stuff, including sending annotations to a real annotation service. |
</annotation>
11. Web Services Section
<webservice>
| Element: | <webservice> |
| Attributes: |
webservicecontrol: A SOAP or CGI accessible service URL that returns to BerkeleyMapper how to call a specific function in a webservice. webservicename: The name of the function in the SOAP webservice that returns information to specific information to BerkeleyMapper, including the following in an array:
webservicedescription: a short description of this service to display to users. webservicetype: indicates how this webservice behaves inside the BerkeleyMapper application.
webservicemethod: How the web service operates
webservicexslt: If results are returned as an XML file, specify XSLT document to convert to HTML. webservicefields: (method type soap only) comma-separated list of fields to pass via SOAP to service. webservicelat: (method=CGI, type=Marker) Key that CGI service recognizes as latitude webservicelng: (method=CGI, type=Marker) Key that CGI service recognizes as longitude |
| Repeatable: | Yes |
| Examples: |
|
| Description: | This entry calls a service that tells BerkeleyMapper how to interact with the appropriate service. The service definition can call itself and specify another function. A sample web service would be (which would work with the XML given in the above Example):
<?php
// miomap-services.php
// Written in PHP and calls the nusoap code
require_once('nusoap.php');
$server = new soap_server;
$server->register('run');
function run($p_arrData){
// NOTE-- do not echo output in this function, just return all text/html
$l_strReturn='Hello from the run function of the miomap webservice!';
return $l_strReturn;
}
$server->service($HTTP_RAW_POST_DATA);
?>
|
</webservice>
12. Closing Tag
</berkeleymapper>