MyListing Proximity Notifications
The {CODICTS} MyListing Proximity Notifications plugin allows site administrators to send customized email and/or push notifications to the owners of nearby listings whenever a new listing is published.
When a user creates a listing (e.g., a new restaurant) and it goes live, the plugin calculates which other listings of a specified type (e.g., “Hotels”) are within a configurable radius. It then sends a personalized notification to each of those listing owners — via email, push notification, or both.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
On activation, the plugin automatically copies its frontend template file into your child theme. Navigate to the new {CODICTS} MyListing Proximity Notifications admin menu to create your first notification template.
Key Features
| Feature | Description |
|---|---|
| Proximity-Based Targeting | Query nearby listings using MyListing’s geolocation data with a configurable radius in kilometres or miles. |
| Dual Notification Channels | Send emails and/or OneSignal push notifications — or both simultaneously. |
| Custom HTML Email Templates | Full HTML support with a built-in code editor (CodeMirror) and dynamic template tags. |
| Push Notifications | Rich push notifications via OneSignal with cover images, click-through URLs, and personalized content. |
| Category & Region Filters | Narrow notification targets by taxonomy terms — only notify listings in specific categories or regions. |
| “Send to All” Toggle | Bypass the proximity radius and notify every listing of the target type. |
| Deferred Notification Queue | If a listing is saved as draft or pending, notifications are queued and sent automatically when the listing is published. |
| Frontend Radius Slider | Listing creators control the notification radius via an interactive slider on the Add Listing form. |
| Admin Template Manager | Full admin interface to create, edit, duplicate, delete, and search notification templates. |
How It Works
The plugin works through a three-part setup: create a notification template, add the proximity notification field to a listing type, and let users control the notification when adding a listing.
1. An admin creates a notification template with email and/or push notification content using dynamic tags.
2. An admin adds the “Proximity Notification” field to a listing type (e.g., “Events”) and configures it to target another listing type (e.g., “Restaurants”) with a selected notification template.
3. A user creates a new listing on the frontend. They set the notification radius with a slider, optionally filter by category/region, and check the email and/or push notification boxes.
4. When the listing is published, the plugin finds all target listings within the radius using geolocation data, processes the template with real data, and sends personalized notifications to each nearby listing owner.
Deferred notifications: If the listing is saved as draft or pending review, the notification settings are saved and automatically sent when the listing is later published. Notifications are never lost regardless of the publishing workflow.
Notification Templates
Notification templates define the content of the emails and/or push notifications sent to nearby listing owners.
Creating a Template
1. Go to {CODICTS} MyListing Proximity Notifications → Add New in the WordPress admin.
2. Enter a title for your template (e.g., “New Restaurant Nearby”).
3. Configure the Email Template tab and/or the Push Notification Template tab.
4. Click Save.
Email Template Fields
| Field | Description |
|---|---|
| From | Sender identity. Format: Site Name <email@domain.com>. Defaults to your site name and admin email. |
| Subject | Email subject line. Supports template tags. |
| Message Body | Full HTML email body, edited via a code editor with syntax highlighting. Supports template tags. If the body doesn’t include <html> tags, the plugin auto-wraps it in a basic HTML document structure. |
Push Notification Template Fields
| Field | Description |
|---|---|
| Link | Click-through URL the user is redirected to when tapping the notification. Use [listing-url] to link to the new listing. |
| Cover Image | Image URL attached to the notification. Use [listing-cover-image] for the new listing’s cover image. |
| Subject | Push notification heading/title. Supports template tags. |
| Message Body | Plain text body (HTML is automatically stripped). Supports template tags. |
Note: Push notifications require the OneSignal Free Web Push Notifications plugin to be installed and configured.
Available Template Tags
Use these tags in any template field. They are replaced with real data when notifications are sent.
| Tag | Resolves To | Push | |
|---|---|---|---|
[reciever-email] | Target listing owner’s email address | ✓ | ✓ |
[reciever-name] | Target listing owner’s display name | ✓ | ✓ |
[reciever-listing-name] | Target listing’s title | ✓ | — |
[listing-url] | New listing’s permalink | ✓ | ✓ |
[listing-email] | New listing owner’s email (falls back to account email) | ✓ | ✓ |
[listing-name] | New listing’s title | ✓ | ✓ |
[listing-author-name] | New listing author’s display name | ✓ | ✓ |
[listing-cover-image] | New listing’s cover image URL | ✓ | ✓ |
[listing-full-description] | New listing’s full description (HTML stripped) | ✓ | ✓ |
[listing-short-description] | New listing’s description truncated to 40 words | ✓ | ✓ |
Note:
[reciever-listing-name]is not available in push notification templates because push notifications are sent in bulk. Also note the historical spelling of “reciever” — you must use this exact spelling for the tags to work.
Managing Templates
The template list page provides search by title, sortable columns (Title, Author, Date), bulk delete, and row actions to Edit, Duplicate, or Delete individual templates. Pagination is configurable via Screen Options.
Adding the Proximity Notification Field to a Listing Type
1. Go to Listing Types in the MyListing admin and edit a listing type (e.g., “Events”).
2. Navigate to the Fields tab.
3. Click the {CODICTS} MyListing Proximity Notifications button at the bottom of the field list.
4. A new Proximity Notification field is added to your listing form. Configure the field options:
Field Options
| Option | Default | Description |
|---|---|---|
| Label | {CODICTS} MyListing Proximity Notifications | The field label shown on the Add Listing form. |
| Description | (empty) | Help text displayed below the field. |
| Listing Type | (none) | The target listing type to search for nearby listings (e.g., select “Restaurants” to notify nearby restaurant owners). |
| Notification Template | (none) | Select which notification template to use. Templates are created in the plugin’s admin menu. |
| Notification Type | Email and Push Notification | Choose “Email and Push Notification,” “Email only,” or “Push Notification only.” |
| Radius Units | Kilometres | Kilometres (metric) or Miles (imperial). |
| Radius Maximum Value | 500 | Maximum allowed radius value on the slider. |
| Radius Default Value | 20 | Default slider position when the form loads. |
| Radius Step Size | 1 | Increment step for the radius slider. |
| Filter by Categories | (none) | Restrict notifications to target listings in specific categories. Leave empty for no filter. |
| Show Category Filter on Frontend? | Off | If enabled, users can filter categories themselves on the Add Listing form. |
| Filter by Regions | (none) | Restrict notifications to target listings in specific regions. |
| Show Region Filter on Frontend? | Off | If enabled, users can filter regions on the Add Listing form. |
| Show “Send to All” Toggle? | Off | If enabled, the frontend shows a switch that bypasses the radius and notifies every listing of the target type. |
| Email Checkbox Label | Send an Email to nearby listings? | Label for the email opt-in checkbox on the frontend form. |
| Push Notification Checkbox Label | Send a Push Notification to nearby listings? | Label for the push notification opt-in checkbox. |
5. Save the listing type.
Frontend User Experience
When a user opens the Add Listing form for a listing type with a Proximity Notification field, they see:
Radius Slider — An interactive slider to set the notification radius (in km or miles). The current value is displayed in real time (e.g., “Radius 50 Km”).
“Send to All?” Toggle (optional) — When activated, the slider becomes disabled and the plugin notifies all listings of the target type regardless of distance.
Category Filter Dropdown (optional) — A multi-select dropdown to narrow target listings by category.
Region Filter Dropdown (optional) — A multi-select dropdown to filter by region taxonomy.
Notification Checkboxes — One or two checkboxes depending on the configuration: “Send an Email to nearby listings?” and/or “Send a Push Notification to nearby listings?” The user must check at least one for notifications to be sent.
Setting Up Push Notifications (OneSignal)
Push notifications are optional and require the OneSignal Free Web Push Notifications WordPress plugin.
1. Install and activate the OneSignal plugin.
2. Configure your OneSignal App ID and REST API Key in the OneSignal plugin settings.
3. Users must subscribe to push notifications on your site (the OneSignal prompt) and be logged in so their WordPress user ID is synced with OneSignal.
4. When notifications are sent, the plugin targets users by their WordPress user IDs via the OneSignal REST API. Rich notifications with cover images and click-through URLs are supported across all platforms (iOS, Android, Chrome).
Note: If OneSignal is not installed, the plugin displays a warning notice on the template editor pages. Email notifications work independently without OneSignal.
Example Setup
1. Activate the plugin with the MyListing theme and a child theme active. The frontend template is automatically copied.
2. Navigate to {CODICTS} MyListing Proximity Notifications → Add New.
3. Create a notification template titled “New Event Nearby” with the following email content:
Subject: A new event near [reciever-listing-name]!
Body:
Hi [reciever-name],
A new event called [listing-name] has been posted near your listing.[listing-short-description]
<a href=”[listing-url]”>View the event</a>
4. On the Push Notification Template tab, set the Link to [listing-url], the Cover Image to [listing-cover-image], the Subject to New event near you!, and the Body to [listing-name] was just posted nearby. Check it out!
5. Save the template.
6. Go to Listing Types and edit the “Events” listing type.
7. In the Fields tab, click the {CODICTS} MyListing Proximity Notifications button to add the field.
8. Configure the field: set Listing Type to “Restaurants” (target), select the “New Event Nearby” template, set Notification Type to “Email and Push Notification,” set Radius Units to Kilometres, Maximum to 100, Default to 25, Step to 5. Enable “Show Category Filter on Frontend” so users can narrow which restaurant categories receive notifications.
9. Save the listing type.
10. A user creates a new “Events” listing on the frontend. They see the radius slider (set to 25 km by default), a category filter dropdown, and checkboxes for email and push notifications. They set the radius to 50 km, select “Italian Restaurants” as a category filter, check both notification boxes, and submit the listing.
11. When the listing is published, the plugin finds all “Restaurants” in the “Italian Restaurants” category within 50 km. Each restaurant owner receives a personalized email with their listing name and the new event details, plus a push notification with the event’s cover image and a link to view it.
Frequently Asked Questions
Does this require a child theme?
Yes. The plugin copies a frontend form template into the child theme directory. Without a child theme, the plugin cannot install its template and will display an error notice.
Is there a settings page?
The plugin has its own admin menu ({CODICTS} MyListing Proximity Notifications) for managing notification templates. Individual field configuration is done within the MyListing listing type editor’s Fields tab.
Do I need OneSignal for this plugin to work?
No. OneSignal is only required for push notifications. Email notifications work independently using WordPress’s built-in mail system. If you only need email notifications, you don’t need OneSignal at all.
What happens if a listing is saved as draft instead of published?
The notification settings are saved and queued. When the listing later transitions to “published” status, the plugin automatically sends all configured notifications. Notifications are never lost regardless of the publishing workflow.
Can users control the notification radius?
Yes. The Add Listing form includes an interactive radius slider that listing creators use to set how far the notification reach extends. Admins configure the units (km/miles), maximum value, default value, and step size.
What does “Send to All” do?
When the “Send to All” toggle is enabled on the frontend form, the proximity radius is bypassed and every listing of the target type receives a notification regardless of distance. This option must be enabled by the admin in the field configuration.
Can I filter which listings receive notifications?
Yes. Admins can restrict notifications to specific categories and/or regions in the field configuration. You can also enable frontend filtering so that the user creating the listing can choose which categories or regions to target.
How are email addresses determined for each listing?
The plugin first checks the listing’s contact email field (_job_email). If that’s empty, it falls back to the listing owner’s WordPress account email address.
Can I customize the frontend form template?
Yes. After activation, the template file is located in your child theme at templates/add-listing/form-fields/proximity-notification-field.php. You can edit this file to customize the frontend form. Note that deactivating and reactivating the plugin will overwrite your customizations.
Does the plugin create any database tables?
No. Notification templates are stored as a custom post type. Notification settings on individual listings are stored as post meta. No custom database tables are created.
What about the “reciever” spelling in template tags?
The tags use the historical spelling [reciever-email], [reciever-name], and [reciever-listing-name]. You must use this exact spelling for the tags to work correctly.
Troubleshooting
Notifications Not Sending
| Cause | Solution |
|---|---|
| Listing not published | Notifications are only sent when a listing’s status is “publish.” Draft and pending listings queue notifications for when they go live. |
| User didn’t check notification boxes | The user must check the email and/or push notification checkboxes on the Add Listing form for notifications to be sent. |
| Notification template has no content | Verify the notification template has content in the subject and body fields for the chosen notification type. |
| No target listings within radius | There may be no listings of the target type within the configured radius. Try increasing the radius or using “Send to All.” |
| Target listings have no geolocation | The proximity query requires geolocation data. Ensure target listings have valid location data set. |
| WordPress email not working | The plugin uses WordPress’s wp_mail() function. Test that your site can send emails using an SMTP plugin. |
Push Notifications Not Working
| Cause | Solution |
|---|---|
| OneSignal not installed | Install and activate the OneSignal Free Web Push Notifications plugin. |
| OneSignal not configured | Ensure your OneSignal App ID and REST API Key are entered in the OneSignal plugin settings. |
| Users not subscribed | Target listing owners must have subscribed to push notifications on your site via the OneSignal prompt. |
| Users not logged in | Users must be logged in for their WordPress user ID to sync with OneSignal. If they subscribed while logged out, their ID won’t be linked. |
Notifications Going to Wrong Listings
| Cause | Solution |
|---|---|
| Wrong target listing type | Check the Listing Type target in the field configuration and ensure it points to the correct listing type. |
| Category/region filters incorrect | Verify the category and region filter settings in the field configuration match your intended targets. |
| Radius too large or too small | Adjust the radius slider default and maximum values in the field configuration. |
Radius Slider Not Appearing on Frontend
| Cause | Solution |
|---|---|
| Template file not installed | Deactivate and reactivate the plugin to re-copy the template file to the child theme. Check for templates/add-listing/form-fields/proximity-notification-field.php in your child theme. |
| JavaScript error | Check the browser console (F12 → Console) for errors. The slider requires jQuery UI Slider, which MyListing includes by default. |
| Custom template has PHP error | If you’ve customized the template file, check for PHP syntax errors. |
Template Tags Not Being Replaced
| Cause | Solution |
|---|---|
| Wrong tag syntax | Ensure you’re using the exact tag syntax with square brackets, e.g., [listing-name]. Check the template tags table for the full list of available tags. |
| Historical spelling | Receiver tags use the spelling [reciever-...] (not “receiver”). You must use this exact spelling. |
| Tag not available for push | [reciever-listing-name] is only available in email templates, not push notification templates. |
Template Overwrite Warning
The following template file in your child theme is managed by this plugin and will be overwritten on reactivation:
templates/add-listing/form-fields/proximity-notification-field.phpIf you’ve customized this file, back up your changes before deactivating/reactivating the plugin.
“MyListing Theme Not Detected” or “Child Theme Not Detected” Error
The MyListing theme and a child theme must both be installed and active. Go to Appearance → Themes to verify.
For further support, visit codicts.com or contact us at support@codicts.com.