Neatline: Using Tags to Toggle Map Data

I'm interested in using Tags to filter what the public sees on a Neatline map. I found the following in the Neatline documentation, and it's almost exactly what I'm trying to do:

"And just show the records that are tagged with both precinct and democrat:
-If you're developing a custom theme or sub­plugin for an exhibit, you can use tags to toggle on and off different portions of the exhibit. For example, imagine you're mapping presidential election results, and you want to add a little widget that makes it possible for the user to check on or off different batches of data from 2000, 2004, etc. If all the data points are tagged to one of the election cycles, you could just run simple API queries like:
Neatline.execute('MAP:load', { tags: ['2004', 'democrat'] }); "

I see that customizing the theme would be necessary since this isn't part of a Neatline exhibit's intended functionality. Could someone who better understands the above quote please explain the process further for me?

Thanks for the help!

Crazy coincidence... I was just prowling the documentation about this exact same question, and was about to make the same post!

You'll want to start here ( to set up the theme for the exhibit and to get everything rolling.

Once you've done that, you'll need to use that theme to add some user interface form to the exhibit in order to provide a way for the user to select which group to display. There are several possibilities for this.

  • You could have a subplugin at add this selection to the exhibit and have it be always visible.
  • You could embed it into the HTML for an item.
  • You could use the theme to embed it into the HTML for every item.
  • You also might be able to have two items, one that turns on one set of items, one that turns on another. (This last one was just a stray thought, and it may not work. I haven't attempted it.)

In all of these cases, you'll need to write some JavaScript in order to respond to the user's interaction and call the Neatline.execute line above.


Hi Eric,

Thanks for your response to this. I got around to trying this, but haven't been able to get the Neatline.execute line to work.

I followed David's blog post and was able to get an exhibit theme up and running. Just to make sure everything is properly set up, I tried using his code for custom zoom in and zoom out buttons. That works perfectly. I tweaked the code just to remove the Neatline.request line and add in a Neatline.execute line with MAP:load and the relevant tags upon pressing some text (within a div).

Here's what I've got in my script.js:

Neatline.on('start', function() {

var map = Neatline.request('MAP:getMap');

$('.testtags').click(function() {
Neatline.execute('MAP:load', { tags: ['test'] });

$('.btn.out').click(function() {


And in my show.php, the relevant code is:

<div id="zoom">
<div class="testtags">test tags</div>
<div class="btn out">action</div>

The zoom out button still works, but the button associated with the MAP:load command doesn't select only records with "test" tags (rather, it does nothing).

I get the feeling that this is probably just due to my lack of competence with JS, but do you have any tips?


Hi Stephen,

Unfortunately, the MAP:load command doesn't actually still exist. We need to update the documentation in that example.

What you can do instead is to use the MAP:setFilter trigger. You can see an example of that in this gist.

Afterward, you'll need a way to remove the filters and view all items again. You can see an example of doing that in this gist.