gsarig / ootb-openstreetmap

A map block for WordPress' Gutenberg Editor which uses OpenStreetMap and Leaflet.js. It needs no API keys and works out of the box. Benefiting from Gutenbergโ€™s potential, the plugin tries a different take on how to add your locations on the map and rethinks a few things, UX-wise. Install it from https://wordpress.org/plugins/ootb-openstreetmap/
29 stars 2 forks source link
gutenberg leafletjs markers multiple-markers openstreetmap wordpress

Download from WordPress.org

Out of the Block: OpenStreetMap

A map block for WordPress' Gutenberg Editor which uses OpenStreetMap and Leaflet.js. It needs no API keys and works out of the box (or, out of the Block, if you prefer). Benefiting from Gutenberg's potential, the plugin tries a different take on how to add your locations on the map and rethinks a few things, UX-wise.

Instead of manually adding coordinates for each one of your markers, just click-and-drop them directly on the map. You want to adjust their position? Just drag them wherever you want. And instead of filling-in custom fields to set each marker's popup content, just open that popup and start writing in it, the Gutenberg way (it supports WYSIWYG editing, with links, images, and all). It even stores the map's zoom level as you use it so that you don't have to set it by hand.


๐Ÿ‘‡ Jump to the available Hooks๐Ÿช

๐Ÿ‘‡ Jump to the available Shortcodes


๐Ÿ‘‰ Read more about the overall UX challenges

๐Ÿ‘‰ The challenges of building a user-friendly place search for OpenStreetMap

๐Ÿ‘‰ Lessons learned from integrating OpenAI to a WordPress plugin

Demos

The main functionality, with drag and drop pins and WYSIWYG editing

Demo GIF

Using the location search

Demo GIF

Drawing a polygon

Demo GIF

Drawing a polyline

Demo GIF

OpenAI integration in action:

Demo GIF

Features

Installation

  1. Upload the plugin to your WordPress plugins directory and activate it.
  2. That's it. You can go to a post/page that supports the Gutenberg editor and start using the block called "Out of the Block: OpenStreetMap"

Frequently Asked Questions

Do I need an API key, like with Google Maps?

No.

That's the point, actually. Just install the plugin and start adding maps. Keep in mind, though, that as stated on the OpenStreetMap Tile Usage Policy, OSMโ€™s own servers are run entirely on donated resources and they have strictly limited capacity. Using them on a site with low traffic will probably be fine. Nevertheless, you are advised to create an account to MapBox and get a free API Key.

How can I add a custom Mapbox style?

You can find the style URL on Mapbox Studio. There, use the "Share" button, and under "Developer resources", copy the "Style URL". It should look like that: mapbox://styles/username/style-id. You can declare a global style on the plugin's settings, to be used as a default for all the maps, or you can set a custom style for each map, by using the block's settings panel.

How do I add a new location?

To add a location, left-click on the map for a while, until you see the prompt saying "Release to drop a marker here". On browsers that support it, the cursor transforms from hand to crosshair, to make it even more apparent. As long as the prompt is visible, it means that releasing the click will drop the marker at that spot. That slight delay has been added to prevent you from accidentally adding markers all over the place with every click.

How do I remove a location?

Click on the marker to open up its popup. There, you will see the "Remove" button.

I can't find some of the options like disable dragging, setting zoom levels, etc

Check under the "Map behavior" section, at the blocks' settings at the sidebar on the right. It's toggled off by default, that's probably why you missed it.

How does the OpenAI integration work?

First of all, you will need to create an account to OpenAI and get an API key. Then, go to the plugin's settings page and paste your key there. After that, you can start adding markers by using commands in natural language. Just say "please" to activate (e.g. "Please, show me where GOT was filmed"). Please keep in mind, though, that it's like asking ChatGPT: the answers you get might not always be 100% reliable, and you should always double-check to confirm their accuracy. Read more.

How can I query maps from other posts or post types?

On the block's side panel, Select the "Map data" panel and click on the "Fetch locations" button. This will automatically retrieve on the frontend all the markers from your posts (you can also select a specific post type from the dropdown). The block will be locked from editing, as the markers will be dynamically retrieved from the selected posts. If you don't want that, there is a "Stop syncing" button that will unlock the block, drop the markers on the map and allow you to edit.

Shortcodes

[ootb_query]

The shortcode [ootb_query] allows you to display a dynamic map, which retrieves markers from other posts or post types. Just add it to a post or page and you're good to go. By default, it will fetch the markers from the 100 most recent posts. The shortcode supports the following attributes:

Here's an example of how you can use it:

[ootb_query post_type="post" post_ids="1,2,3,4" height="400px" provider="mapbox" maptype="polygon" touchzoom="true" scrollwheelzoom="true" dragging="true" doubleclickzoom="true" marker="https://www.example.com/my-custom-icon.png"]

Hooks

There are a few hooks that you can use to further customize the plugin's behavior. Here they are:

ootb_query_post_type

Allows you to change the post type that the plugin will query for markers. By default, it is set to post. You can pass multiple post types as an array. Example:

add_filter( 'ootb_query_post_type', function() { return array( 'post', 'page' ); } );

ootb_query_posts_per_page

Allows you to change the number of posts that the plugin will query for markers. By default, it is set to 100. Example:

add_filter( 'ootb_query_posts_per_page', function() { return 500; } );

ootb_query_extra_args

Allows you to add extra arguments to the query that the plugin will use to retrieve markers. By default, it is set to an empty array. Example:

  add_filter(
     'ootb_query_extra_args',
     function() {
        return [
           'tax_query' => [
           [
              'taxonomy' => 'people',
              'field' => 'slug',
              'terms' => 'bob'
           ]
        ];
     }
  );

Keep in mind that the extra args will be merged with the default ones, so you don't have to worry about overriding them. In fact, the args that are required for the query to work, cannot be overridden.

ootb_cf_modal_content

Allows you to change the content of the modal that appears when you query posts based on their "Location" custom fields. By default, it will display the value set in the Address field. For example, the following code will display the post's title, thumbnail, excerpt and a link to the post:

add_filter( 'ootb_cf_modal_content', 'my_modal_content', 10, 2 );

function my_modal_content( $address, $post_id ) {

    return sprintf(
        '<div>
            <h3>%1$s</h3>
            <figure>%2$s</figure>
            <p>%3$s</p>
            <p><a href="https://github.com/gsarig/ootb-openstreetmap/blob/master/%4$s">View post</a></p>
        </div>',
        get_the_title( $post_id ),
        get_the_post_thumbnail( $post_id, 'thumbnail' ),
        has_excerpt( $post_id ) ? get_the_excerpt( $post_id ) : $address,
        get_the_permalink( $post_id )
    );
}

ootb_cf_marker_icon

Allows you to change the marker icon for posts that have a "Location" custom field. By default, it will use the default marker. For example, the following code will use a custom marker for a post with ID 123:

add_filter( 'ootb_cf_marker_icon', 'my_marker_icon', 10, 2 );

function my_marker_icon( $icon_url, $post_id ){
    if( 123 === $post_id ) {
        $icon_url = 'https://example.com/my-marker.jpg';
    }
    return $icon_url;
}

Screenshots

The map editing screen The map editing screen

Map behavior options Map behavior options

Adding a marker Adding a marker

Using custom markers Using custom markers

Place search Place search