ICT:Cargo Geo Coordinnates

Handling Geographical Coordinates in Cargo

Geographical data is stored using the Coordinates field type. This allows for both precise database storage and interactive map displays using Page Forms and Cargo.

1. Define the Cargo Table

In your table declaration, use the `Coordinates` field type.

{{#cargo_declare:_table=Places
|Name=String
|Location=Coordinates
}}

2. Create the Input Form

Use the `leaflet` input type (part of Extension:Page Forms) to provide an interactive map where users can click to set coordinates.

{{{field|Location|input type=leaflet|height=300|width=500}}}

3. Displaying Maps

Display a map for a single location

Use the `#cargo_display_map` function on the page itself to show where the specific place is located.

{{#cargo_display_map:
|point={{{Location|}}}
|service=leaflet
|zoom=14
|height=400
}}

Display all places on a master map

To show all entries from your `Places` table on one map, use a `#cargo_query` with a map format.

{{#cargo_query:
|tables=Places
|fields=_pageName=Page, Name, Location
|format=leaflet
|height=500
}}

Technical Note: Coordinate Format

• Storage: Cargo stores coordinates as "Latitude, Longitude" in decimal degrees (e.g., `51.2194, 2.8972`).
• Precision: Ensure you use a period (`.`) for decimals and a comma (`,`) to separate the two values.
• Services: While `leaflet` is recommended for its ease of use, you can also use `googlemaps` or `openlayers` if they are configured on your wiki.

Choosing a Map Service for Forms

To display a map in a form for coordinate input, use the `input type` parameter.

Option A: Leaflet (Recommended)

Uses OpenStreetMap. No API key required.

{{{field|Location|input type=leaflet}}}

Option B: OpenLayers (Default)

Solid open-source alternative.

{{{field|Location|input type=openlayers}}}

Option C: Google Maps

Requires a Google Maps API Key to be configured in your wiki's LocalSettings.php.

{{{field|Location|input type=googlemaps}}}

Common Parameters

You can customize the map's appearance in the form using these parameters:

• `height`: Height in pixels (e.g., `300`).
• `width`: Width in pixels (e.g., `500`).
• `starting bounds`: Initial map area if no coordinate is set yet (e.g., `-20,-15;50,55`).

Leaflet Troubleshooting

• Map not appearing: Ensure the `height` parameter is set (e.g., `height=400`).
• Marker not saving: Make sure you clicked the map to place the marker; simply zooming in won't store coordinates in the field.
• Search box: To add a search-by-address bar to your form map, add `|show search box` to the field parameters.

Automating Place Data with Geocoding

The Maps extension provides the `{{#geocode:}}` function, which can automatically turn human-readable addresses into Cargo-compatible coordinates.

1. Using Geocode in a Template

You can set up your template so that it accepts a "Street Address" but stores "Coordinates" in Cargo.

{{#cargo_store:_table=Places
|Name={{{Name|}}}
|Location={{#geocode:{{{Address|}}}}}
}}

2. Using Geocode in a Query

You can also geocode "on the fly" to find distances or filter by location without having coordinates stored.

{{#cargo_query:
|tables=Places
|fields=Name
|where=DISTANCE(Location, '{{#geocode:Brussels, Belgium}}') < 5000
}}

3. Configuration Tips

• Default Service: By default, Maps uses Nominatim (OpenStreetMap). This is free and requires no API key.
• Accuracy: Geocoding results depend on the external service. For high-volume wikis, results are cached to improve performance.
• Manual Overrides: Always provide a field for manual coordinates in case the auto-geocoding fails for a specific obscure location.