Merge branch 'rellease/2.8.2'

README.md

@@ -6,12 +6,21 @@ A map block for WordPress' Gutenberg Editor which uses [OpenStreetMap](https://w
 
 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**](#hooks)🪝
+
+👇 [**Jump to the available Shortcodes**](#shortcodes)
+
+---
+
 👉 [Read more about the overall UX challenges](https://www.gsarigiannidis.gr/wordpress-gutenberg-map-block-openstreetmap/)
 
 👉 [The challenges of building a user-friendly place search for OpenStreetMap](https://www.gsarigiannidis.gr/openstreetmap-place-search/)
 
 👉 [Lessons learned from integrating OpenAI to a WordPress plugin](https://www.gsarigiannidis.gr/openstreetmap-openai-integration/)
 
+
 ## Demos
 
 ### The main functionality, with drag and drop pins and WYSIWYG editing
@@ -91,7 +100,8 @@ First of all, you will need to create an account to [OpenAI](https://openai.com/
 ### 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.
 
-### How can I use the shortcode?
+## 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:
 * source: (Optional) The source of the data. Can be either `geodata`, if you want to retrieve the posts based on their Location custom meta field, or `block`, to retrieve posts containing map blocks in their content. The default option, which will be used if the attribute is omitted, is `block`.
 * post_type: (Optional) The type of post to query. By default, it is set to `post`.
@@ -110,18 +120,23 @@ 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:
 
-### I want more control. Are there any hooks that I could use?
-Glad you asked! 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:
+### 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:
+
+### 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:
+
+### 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',
@@ -139,6 +154,40 @@ add_filter( 'ootb_query_posts_per_page', function() { return 500; } );
 ```
 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="%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](.wordpress-org/screenshot-3.jpg)

includes/classes/Query.php

@@ -178,11 +178,13 @@ private static function get_marker_data( int $current_post_id, array $post_ids,
 				if ( empty( $latitude ) || empty( $longitude ) ) {
 					continue;
 				}
+
 				$markers[][] = (object) [
 					'lat'  => $latitude,
 					'lng'  => $longitude,
-					'text' => $address,
+					'text' => wp_kses_post( apply_filters( 'ootb_cf_modal_content', $address, $post_id ) ),
 					'id'   => $post_id,
+					'icon' => self::get_cf_marker_icon( $post_id ),
 				];
 			} else {
 				if ( $post_id === $current_post_id ) {
@@ -341,4 +343,26 @@ private static function overridable_attrs(): array {
 			'marker'          => '',
 		];
 	}
+
+	/**
+	 * Gets the marker icon and allows the user to override it with a hook.
+	 *
+	 * @param int $post_id The post ID.
+	 *
+	 * @return array|null
+	 */
+	private static function get_cf_marker_icon( int $post_id = 0 ): ?array {
+		if ( empty( $post_id ) ) {
+			return null;
+		}
+		$icon_url = apply_filters( 'ootb_cf_marker_icon', '', $post_id );
+		$icon     = null;
+		if ( ! empty( $icon_url ) && filter_var( $icon_url, FILTER_VALIDATE_URL ) ) {
+			$icon = [
+				'url' => esc_url( $icon_url ),
+			];
+		}
+
+		return $icon;
+	}
 }

ootb-openstreetmap.php

@@ -5,7 +5,7 @@
  * Description:       A map block for the Gutenberg Editor using OpenStreetMaps and Leaflet that needs no API keys and works out of the box.
  * Requires at least: 5.8.6
  * Requires PHP:      7.4
- * Version:           2.8.1
+ * Version:           2.8.2
  * Author:            Giorgos Sarigiannidis
  * Author URI:        https://www.gsarigiannidis.gr
  * License:           GPL-2.0-or-later
@@ -21,7 +21,7 @@
 define( 'OOTB_PLUGIN_BASENAME', plugin_basename( __FILE__ ) );
 
 const OOTB_BLOCK_NAME     = 'ootb/openstreetmap';
-const OOTB_VERSION        = '2.8.1';
+const OOTB_VERSION        = '2.8.2';
 const OOTB_SCRIPT_VERSION = [
 	'leaflet'                  => '1.9.4',
 	'leaflet-gesture-handling' => '1.4.4',

readme.txt

@@ -5,7 +5,7 @@ Tags: Map, OpenStreetMap, Leaflet, Google Maps, block
 Requires at least: 5.8.6
 Tested up to: 6.5
 Requires PHP: 7.4
-Stable tag: 2.8.1
+Stable tag: 2.8.2
 License: GPLv2 or later
 License URI: http://www.gnu.org/licenses/gpl-2.0.html
 
@@ -22,6 +22,8 @@ Instead of manually adding coordinates for each one of your markers, just click-
 * [Follow the project's development on GitHub](https://github.com/gsarig/ootb-openstreetmap)
 * [Release history](https://github.com/gsarig/ootb-openstreetmap/releases)
 * [Roadmap](https://github.com/users/gsarig/projects/1)
+* [Hooks🪝](https://github.com/gsarig/ootb-openstreetmap?tab=readme-ov-file#hooks)
+* [Shortcodes](https://github.com/gsarig/ootb-openstreetmap?tab=readme-ov-file#shortcodes)
 
 = Features =
 
@@ -86,52 +88,10 @@ First of all, you will need to create an account to [OpenAI](https://openai.com/
 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.
 
 = How can I use the shortcode? =
-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:
-* source: (Optional) The source of the data. Can be either `geodata`, if you want to retrieve the posts based on their Location custom meta field, or `block`, to retrieve posts containing map blocks in their content. The default option, which will be used if the attribute is omitted, is `block`.
-* post_type: (Optional) The type of post to query. By default, it is set to `post`.
-* posts_per_page: (Optional) The number of posts to be displayed on page. Default value is `100`.
-* post_ids: (Optional) Comma-separated IDs of the posts to include in the query.
-* height: (Optional) The desired height for the map. Default value is empty, which falls back to `400px`.
-* provider: (Optional) Specifies the map provider. Options are: `openstreetmap`, `mapbox` and `stamen`. The default value is an empty string which falls back to `openstreetmap`.
-* maptype: (Optional) Specifies the type of map. Options are: `markers`, `polygon` and `polyline`. The default value is an empty string, which will fall back to `markers`.
-* touchzoom: (Optional) If set, touch zoom will be enabled on the map. It can be either `true` or `false`. The default value is an empty string, which falls back to `true`.
-* scrollwheelzoom: (Optional) If set, enables zooming on the map with mouse scroll wheel. It can be either `true` or `false`. The default value is an empty string, which falls back to `true`.
-* dragging: (Optional) If set, dragging is enabled on the map. It can be either `true` or `false`. The default value is an empty string, which falls back to `true`.
-* doubleclickzoom: (Optional) If set, allows zooming in on the map with a double click. It can be either `true` or `false`. The default value is an empty string, which falls back to `true`.
-* marker: (Optional) Specifies the marker for the map. This should correspond to the URL of the image that you want to use as the marker's icon (example: `https://www.example.com/my-custom-icon.png`). The default value is an empty string, which retrieves the default marker.
-
-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"]
-```
+To see the available shortcodes and the parameters that you can pass, [go here](https://github.com/gsarig/ootb-openstreetmap?tab=readme-ov-file#shortcodes).
 
 = I want more control. Are there any hooks that I could use? =
-Glad you asked! 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.
+Glad you asked! There are a few hooks that you can use to further customize the plugin's behavior. [You can find them here](https://github.com/gsarig/ootb-openstreetmap?tab=readme-ov-file#hooks).
 
 == Screenshots ==
 
@@ -176,6 +136,9 @@ Version 2.0.0 is a major, almost full, refactoring, both for the build scripts a
 = 1.0 =
 
 == Changelog ==
+= 2.8.2 =
+* [NEW] Adds the `ootb_cf_modal_content` and `ootb_cf_marker_icon` hooks, which allow you to change the content of the modal that appears when you query posts based on their "Location" custom fields, as well as the marker icon. For more info, check the plugin's FAQ section.
+
 = 2.8.0 =
 * [NEW] Adds an option to enable a location custom field, which can be used to store a post's or post type's location, following the [Geodata guidelines](https://codex.wordpress.org/Geodata).
 * [NEW] Adds a new block (a Block Variation, to be precise), to display a map that retrieves markers from posts or post types including the location custom field.