Locations Plugin

(Angus McLeod) #1

*** Mapzen was removed as a supported provider on Wednesday, 10th Jan . See further. ***

Repo: GitHub - angusmcleod/discourse-locations

This plugin allows you to associate locations with topics, and list topics with locations on a map.

You can see an example of it in action on my sandbox.

Maps are handled by Leaflet.js and multiple geocoding providers are supported. Both are customizable via admin settings as explained below in ‘Admin Settings’.


  • 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.

      11 PM

      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 01 PM. This will expand the map to take over the whole window aside from the Header bar.

    • Zoom 13 PM. These are standard leaflet zoom controls.

    • Attribution 12 PM. 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

    51 PM
    10 PM

  • location input fields: sets what input fields are used if location 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 is the default, as it doesn’t require an api key, has no (relevant) restrictions in terms of use and is good for testing and light use. 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 the location 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.

Events Plugin :calendar:
OpenStreet maps embedding
National Flags - Display user nationality in Discourse
Events Plugin :calendar:
Object instead of users due to locations plugin
Custom Layouts Plugin
Events Plugin :calendar:
Learn how to build Discourse plugins by helping me
Locations plugin modifications
Events Plugin :calendar:
Project ideas for Google Summer of Code 2018
Adding location at sign up
Developing with Discourse
More options to filter users on users page
(Christoph) #2

Wow, you are incredible! :star_struck:
You’re producing plugins faster than I can install them :+1:


So. So cool!

What if you added an option for a map of the users locstion, taking the data from their profile? So it could simply show everyone’s location in the forum?

(Chris Beach) #4

Brilliant, @angus! Can’t wait to try this. My only concern is that the Add Location button impinges on the already-constrained editor height on smartphone screens:

Would it work as an option in the cog menu instead?

(Angus McLeod) #5

Interesting idea. Yeah, totally doable. Where would this map go?

Yes, I agree it’s an issue. However, the issue with tucking the button away in the options menu is that the ‘Add Locations’ button is only going to appear in a locations enabled category - i.e. it’s a ‘special context’ - so I don’t think it would be great UX for the functionality to not be immediately obvious within that context. But yes, the button takes up a fair amount of space particularly on mobile. Perhaps there’s somewhere else it could go I’m not seeing.

Events Plugin :calendar:

It could go on a separate page /map I suppose…

(Angus McLeod) #7

@ChrisBeach Ok, I’ve pushed some responsive CSS improvements that, among other things, reduce the size of the add location button in mobile web. This is what those elements look like now in an iPhone 6 sized screen.


On User’s Location and Privacy

Careful with privacy here! Make sure to allow users to opt-in to be on the map, and that the map is only accessible to members. Discourse takes a lot of care to avoid spammers, it’s not to give them free user data. One could argue that if the users put their location in their profile it’s already consent to be pin-pointed on a map, but it’s not:

  • people feel different marking a city than seeing it on a map
  • the plugin may interact with other plugins, e.g., if the user is on mobile and share their location, they would then be tracked ; that might be what they want, or not.

Really nice plugin @angus, thank you!


that’s right. we’d want them to be able to opt-in for sure.

(Chris Beach) #10

Thanks Angus, that’s definitely an improvement.

When I view these on an iPhone screen with the keyboard up, the editor size is still compromised though:

I know the cog menu is a discoverability problem. Perhaps a location icon could be added to the editor menu bar next to the cog? There is a bit of room up there.

(Angus McLeod) #11

The problem with putting it in the toolbar is that it doubles as a label to show you the selected location. Even if the button was there, you would still need to find space for the label.

48 PM


40 PM

Also, the buttons in the post toolbar all relate to content in the post itself. This is arguably information about the topic, rather than the first post per se.

(Chris Beach) #12

Yes, I do see the problem. But the text box is king.

From my own point of view, I don’t mind not seeing the location label in the editor. I think it would be sufficient to colour the location icon in the menu bar to show a location has been selected, and then I can click it to see / edit the location.

(Jeff Atwood) #13

Make sure you test on all iPhone sized devices (5 / SE, 6, 6 plus)

(Angus McLeod) #14

hm. Content in the editor has to be mutable. The way special (mutable) content is normally added to the editor is via markup, e.g.

[poll type=regular]
* apples
* oranges

The reason I didn’t go down this path is for the reason I mentioned previously: unlike some other special content you can add to posts / topics, this feature is category-specific. Some categories will allow you to add locations, others won’t. It should be immediately obvious to the user that they can, or even should, add a location to a topic in a category in which this is enabled. This is not true of the other controls in the post toolbar. They are all generic and apply equally to any context in which you are posting.

That said, there are ways to handle this aspect of the feature within the approach of putting the button in the toolbar. Like making it a primary button (i.e. colored) so that it stands out.

Another way would be to add toolbar-like buttons next to the title input.

Screenshot at Sep 11 15-49-07

(Chris Beach) #15

That’s a good idea :+1:

(Angus McLeod) #16

You know, the more that I think about it now though - now that I’ve finished v0.1 of this - the more I think it would be kinda cool to be able to specify arbitrary locations on the map via markup, in addition to the ability to add locations via natural language lookups in the ‘Add Locations’ modal.

e.g. [location lat=-31.94534 lng=115.8610513 name='The Moon Cafe'][/location]

Perhaps a change for v0.2.

(Angus McLeod) #17

Ok, I’ve pushed a version of the button next to the title approach. This approach scales well over different device sizes.

Before a location is added
06 PM

After a location is added
32 PM

(Chris Beach) #18

Awesome! :+1:

Thanks for taking this feedback onboard.


@angus thank you for fixing the Redis connection, it now works fine on multisite installs! :clap:

I met another minor issue: when pasting a TileLayer URL from Leaflet Provider Demo I got an error with {ext} not having a default value. A fallback to png makes sense. I replaced the former with the latter in the setting and things started working.

(Angus McLeod) #20

Tile layer urls can be a little tricky.

However, I’m not sure it’s worth either hardcoding {ext} to .png in the TileLayer config, or having a SiteSetting for that particular attribute though.

Just using .png in the TileLayer url itself is a fine solution for this kind of issue. It’s more explicit.