Skip to content

Latest commit

 

History

History
103 lines (87 loc) · 6.01 KB

README.md

File metadata and controls

103 lines (87 loc) · 6.01 KB
Raw

UNCCD Event Map Drupal Module

The UNCCD Event Map Drupal Module display a map of events. Users can add events, which after approval appear on the map. Live version: UNCCD Events Around the World 2018

User Guide

Installing the module

The module requires Drupal 8.x, and has no other module dependencies. To install the module:

  1. Create a new folder "unccd_eventmap" inside "docroot/modules/unccd"
  2. Place all of the files from this repository inside the above folder.
  3. Go to "Extend" in the Drupal admin panel.
  4. Find UNCCD Event Map in the module list, and check the box next to it
  5. Click "Install" at the bottom of the page
  6. Clear the cache by running "drush cr" or go to "Configuration -> Performance" and click "Clear all caches"

Updating the module

To update the module:

  1. Update the contents of "docroot/modules/unccd/unccd_eventmap" with the contents of this repository
  2. Clear the cache by running "drush cr" or go to "Configuration -> Performance" and click "Clear all caches"

Usage

The module introduces two new blocks:

  • Event Map Block: Displays approved events on a map
  • Events Around the World Block: Displays approved events by country/continent These blocks can be inserted into any page in Drupal settings (Structure -> Block layout). The blocks by default show all the events, but can be restricted to a specific year in the configuration of each block.

The public form for adding events is acessible under /event-map/form, and also from a link included in the Event Map block.

The module also adds an admin panel page to manage events, which can be accessed at Structure -> UNCCD Event Map Events.

The permission "Manage UNCCD Event Map" can be given to users for them to be able to approve, edit and delete events.

Development

Folder structure

  • /config/install/unccd_event_map_config.yml The default values for the module configuration
  • /src/Controller/
    • EventAdminController.php The controller for the admin panel pages
    • MapController.php The controller for the admin panel pages
  • /src/Form/
    • AddEventForm.php The form to add new events in the admin panel
    • ConfigForm.php The form to change map configuration
    • EditEventForm.php The form to edit events
    • PublicEventForm.php The public form to submit events
  • /src/Plugin/Block/
    • EventMapBlock.php The event map as a Drupal Block
    • EventsAroundTheWorld.php The list of events split by continent and country
  • /src/Utils/
    • ContinentSpliter.php A utility which can categorize countries by continent
    • Geocoder.php A utility to convert addresses into latitude/longitude
  • /src/EventStorage.php A class managing the database storage of events
  • /templates The view of the pages/blocks
  • README.md This file
  • unccd_event_map.info.yml Description of the module
  • unccd_event_map.install A script ran when the module is installed. Adds the database table.
  • unccd_event_map.libraries.yml The list of js and css files used by the module.
  • unccd_event_map.link.action.yml A list of actions to add to the admin panel
  • unccd_event_map.links.menu.yml A list of menu entries to add to the admin panel
  • unccd_event_map.module Defines the view templates used by the module
  • unccd_event_map.permissions.yml A list of new permissions added by the module
  • unccd_event_map.routing.yml A list of new routes added by the module (both public and admin panel)

Database Schema

The module adds one additional database table called "unccd_event_map", it has the following fields:

Column name Type Description
id int Primary Key: Unique event ID.
title varchar Title of the event.
organisation varchar Organisation running the event.
organisation_url varchar Url of the event organizer(s)
url varchar URL of the event on an external website.
email varchar Email of the contact person.
city varchar City where the event takes place.
country varchar Country where the event takes place.
date datetime The date the event takes place on.
description text Description of the event
latitude float The latitude of the location of the event (for map display)
longitude float The longitude of the location of the event (for map display)
approved tinyint Has the event been approved?
image_id int The Drupal file id for the uploaded image (needed to delete image when event is deleted)
image varchar Url of the event image
attachment_type varchar The type of PDF attached (report, flyer, etc...)
pdf_id int The Drupal file id for the uploaded PDF (needed to delete PDF when event is deleted)
pdf varchar Url of the event PDF

Geocoding

The module has two different geocoding services implemented to convert from the user entered city and country to a latitude/longitude on the map.

The module implements Geocoding with OpenStreetMap Nominatim, GoogleMaps API, MapQuest API

The OpenStreetMap implementation is enabled by default.

External libraries

The module uses three third-party JavaScript libraries:

  • Leaflet: The interactive mapping library used to display the OpenStreetMaps tiles (Version: 1.3.1)
  • Leaflet MarkerCluster: Clusters nearby pins to reduce clutter and make the map cleaner (Version: 1.3.0)
  • Leaflet FullScreen: A button to fullscreen the map (Version: 1.0.1)
  • Date Picker: A date picker for the user event submission form (Version: 0.6.5)