Repo: GitHub - paviliondev/discourse-locations: Tools for handling locations in Discourse
This plugin allows you to associate locations with topics, and list topics with locations on a map.
Additionally it allows users to record their position (voluntarily) and this can show up on a map of Users in the Users directory.
You can see an example of it here.
Maps are handled by Leaflet.js and multiple geocoding providers are supported. Both are customizable via admin settings as explained below in ‘Admin Settings’.
Features:
-
A map of Users (whose locations have been set) can be turned on.
-
Locations can be turned on for specific categories by toggling ‘Allow locations to be added to topics in this category’ in the Category settings.
-
When locations are turned on a for a category:
-
The composer will include an ‘Add Location’ button when composing a new topic in that category.
This opens a modal which allows the user to enter the location details, including a geocoded address:
-
‘Map’ will be added to the category nav items. This will display a map in place of the topic list with topics that have geocoded locations associated with them marked on it. This list can be set as the default for the category in the category settings. When multiple topics are associated with the same location, they are grouped into expandable clusters (using the Marker Cluster plugin for Leaflet). Clicking on the markers navigates the user to the associated topic.
-
-
When a location is added to a topic:
-
The location details will appear underneath the topic title. If the location is geocoded a ‘Show Map’ button appears to the right of the location details. This button toggles a mini-map showing the location.
-
Locations can be edited in the ‘topic title’ edit controls.
-
-
The map controls available to users are:
-
Expand
. This will expand the map to take over the whole window aside from the Header bar.
-
Zoom
. These are standard leaflet zoom controls.
-
Attribution
. This toggles the visibility of the attribution.
-
Admin Settings:
-
location input fields enabled
: toggles whether ‘Add Location’ modal displays specific location input fields or a single location query input
OR
-
location input fields
: sets what input fields are used iflocation input fields enabled
is true -
location geocoding
:-
none: User is required to enter either a name or an address when adding a location. Addresses are stored as a string.
-
optional: User is required to enter either a name or an address when adding a location. Addresses are geocoded and will display on any associated maps.
-
required: User is required to enter an address when adding a location. Addresses are geocoded and will display on any associated maps.
-
-
location geocoding provider
: the service that translates user input into coordinates that can be displayed on a map. Geocoding is handled by the Geocoder gem, which supports a number of geocoding providers. Think of these providers like you would a transactional email provider. The list of providers available in this plugin is a sub-set of the list in the gem. The providers currently supported by this plugin are:- nominatim (for testing only). See further)
- location_iq
- opencagedata
- mapbox
- mapquest
Nominatim, the default, is good for testing, but should not be used in production. Each provider has strengths and weaknesses. I suggest you review each of them (e.g. check the Terms; test relevant addresses) if you’re serious about using this plugin.
This sub-set of providers available through the Geocoder gem were chosen according to these criteria:
-
Ease of integration. The reason I didn’t include Google is because Google Maps is not designed to be used with Leaflet.js (or any other 3rd party software). I did get it working, however it requires multiple customizations specific to Google and the end result is not great, so I don’t want to support it considering there are a number of other more customizable providers that can do the job just as well. If for some reason you must use Google Maps with this plugin, it is possible, but you will need to handle and support the integration yourself.
-
Terms of Service. A number of the Geocoding providers only allow you to use their geocoding data in conjunction with their own maps. This is true of some of the providers this plugin does support. For example, you can’t use Mapbox data on non-Mapbox maps. For the providers that have this restriction I have only included those that make it relatively easy to use both their geocoding service and their mapping service with Leaflet.js, so the service can be used without breaching the provider’s terms.
-
Functionality. Some of the providers listed in the Geocoder gem docs no longer work.
-
location geocoding api key
: When a geocoding provider requires an API key, enter it here before you switch to that service in thelocation geocoding provider
setting. If you switch to a provider that requires a key before entering a key you will get an error. -
location geocoding timeout
: This sets the timeout for the Geocoder gem. It is unlikely you will need to change this. -
location map tile layer
: Aka the “basemap”. This is the actual map image on which locations are shown. There is a large variety of basemaps that can be used. Keep in mind that some Geocoding providers require you to use their basemaps when using their geocoding service. There’s a nice basemap showcase here. -
location map tile layer subdomains
: Relevant for some basemap providers. It is unlikely you will need to use this. -
location map attribution
: This string will appear when the ‘i’ button in the bottom right corner of the map is clicked. Please always give attribution to the providers you are using.
How to safely install or update when using our plugins:
Pavilion’s update schedule and support policy
This plugin is one of the Pavilion family of open source plugins.
Pavilion focuses on ensuring compatibility of a core set of its plugins with Discourse Core tests-passed
branch during the first 5 days of every month only.
Any bugs which arise because of an incompatibility will be addressed asap during this ‘supported period’, preferably by the 7th day. Low severity or Beta feature bugs may not be addressed by this date, but obvious things which are ‘breaking’ a forum should be resolved.
If you’ve not used the plugin before, it is safer to adopt it within the support window, so add it and rebuild your site within the first five days of any month, otherwise it’s possible you may be introducing an incompatibility and we might not be around to help.
More about this policy here: Pavilion's Support Policy and Schedule - Support - Pavilion