Files, Functions & Architecture
Codebase navigation guide.
Which file bootstraps NexDirectory?
The main bootstrap file is nexdirectory.php. It loads traits, registers hooks, and wires activation/deactivation. Start debugging here when features do not initialize.
Where is admin settings code located?
includes/trait-eep-admin.php contains admin menus, setting registration, and admin action handlers.
Where are content type and REST route registrations?
includes/trait-eep-content.php registers post type, taxonomies, shortcodes, query vars, and REST routes.
Where are frontend handlers and forms implemented?
includes/trait-eep-frontend.php contains render methods, form submissions, moderation handlers, auth flows, and exports.
Where are boost and ticket payment flows implemented?
includes/trait-eep-monetization.php handles boost orders, ticket checkout, payment capture, and renewal jobs.
Where is dependency injection configured?
includes/utilities/class-eep-plugin-bootstrap.php instantiates services and registers service-level hooks.
Where do email templates live?
Templates are in templates/emails/. The email service supports theme overrides at your-theme/nexdirectory/emails/.
Where is import parsing and mapping logic?
includes/utilities/class-eep-import-service.php parses CSV/JSON, detects duplicates, maps fields, and inserts listings.
Where are analytics calculations implemented?
includes/utilities/class-eep-analytics-service.php builds owner/platform metrics and trend summaries.
Where is chatbot indexing logic implemented?
includes/utilities/class-eep-chatbot-knowledge-service.php builds embedding text, stores vectors, and runs reindex jobs.
Where is chatbot ranking and intent logic?
class-eep-chatbot-ranking-service.php and class-eep-chatbot-state-service.php manage ranking, query intent, and session state.
Where is map and navigation behavior implemented?
class-eep-frontend-navigation-service.php manages app page routing, sticky nav, theme override CSS, and auth links.
Where are role and capability checks centralized?
class-eep-user-capabilities.php controls submit, edit, moderate, and organizer-management permissions.
Where are custom field and meta sanitizers?
class-eep-event-meta-service.php sanitizes listing meta and custom field values.
Where are runtime logs stored and cleared?
class-eep-runtime-log-service.php stores logs in options and exposes admin clear-log action.
Where are template files for frontend pages?
Frontend templates are in templates/frontend/ and include archive, map, calendar, submit, account, moderation, and ticket views.
Where are Elementor widget integrations?
includes/elementor-widgets.php registers shortcode-backed Elementor widgets and controls.
Where are smoke tests located?
Basic tests are in tests/phpunit/ and tests/e2e/ for REST route and page render checks.
How many core code files were reviewed for this FAQ?
This guide was built from a full scan of plugin code files (PHP, JS, CSS) in the project, excluding vendor SDK assets and image libraries.
How can developers find a specific handler quickly?
Search by action name or method with rg "handle_..." or rg "admin_post_...". This maps UI actions directly to code paths.
Getting Started
First setup and launch checks.
How do I install NexDirectory?
Upload the plugin folder to wp-content/plugins, then activate NexDirectory in WordPress.
After activation, open WP Admin → NexDirectory and run through the onboarding page.
If pages are missing, use Generate Pages in settings.
What does NexDirectory create on activation?
Activation creates the listing post type, taxonomies, default pages, and plugin database tables for RSVP, inbox, analytics, boosts, and tickets.
It also schedules reminder and maintenance cron jobs.
Which default pages should I have?
You should have pages for archive, map, calendar, submit, my listings, account, auth, moderation, organizers, and claim listing.
Open WP Admin → NexDirectory → Settings → Setup to check page URLs.
How do I confirm the plugin is working after setup?
Visit your archive page, map page, and submit page as a test user.
Then create a draft listing, submit it, and approve it from the moderation queue.
How do I switch NexDirectory from Events mode to Directory mode?
Go to Settings → General → Setup and change the site profile.
This updates labels and route defaults for listings, owners, and profile-specific wording.
Can I use NexDirectory as a job board or marketplace?
Yes. Site profile options include events, directory, job board, and marketplace.
After switching profile, review submission rules and required fields for that profile.
How do I create required taxonomy terms?
Create terms for type, mode, tags, and price range from WordPress taxonomy screens.
If filters look empty on frontend, missing terms are the first thing to check.
How do I regenerate plugin pages safely?
Use the Generate Pages action from NexDirectory settings.
This is safer than deleting pages manually because it keeps route metadata consistent.
What user role should creators have?
Use the built-in event_submitter role for creator accounts.
Then enable or disable role capabilities in Roles & Access settings.
How do I verify cron jobs are active?
Open NexDirectory → Diagnostics and check scheduled jobs.
You should see reminder, chatbot reindex, and boost renewal schedules where enabled.
How do I test this plugin safely before launch?
Use staging, enable sandbox payment mode, and set ticket free-test mode if needed.
Run a full test flow: signup, verification, submit, moderate, RSVP, checkout, export.
How do I roll back after a failed setup change?
Restore from a backup and clear caches.
Then re-apply settings one tab at a time and test after each save so you can isolate the failing change.
REST API & Developer
Endpoint behavior and access rules.
How does the NexDirectory REST API work?
NexDirectory registers various endpoints under the /wp-json/eep/v1/ namespace. Public endpoints (like /archive-events or /quick-search) can be queried openly. Action-based endpoints (like /event-submit, /moderate-event, or /rsvp) require an authenticated user session and valid WP nonces.
If a request fails, ensure the user has the correct capabilities enabled in Settings, check authentication headers, and review browser console networks tabs for 401/403 rejections.
Settings: AI, Extension, SEO & Advanced
Advanced and integration settings.
How do I configure the AI Chatbot?
Go to WP Admin → NexDirectory → Settings → Advanced / AI. Here you can enable the chatbot, supply your OpenAI API key, write the welcome text/personality prompt, and configure re-index intervals for your directory content.
How do I manage IndexNow and SEO configurations?
In Settings → Advanced / SEO, you can configure Home Meta descriptions/titles and enable IndexNow. Supply your IndexNow key and endpoint to push instant content updates to supported search engines.
How do I configure White Label settings?
Toggle White Labeling in Settings → Advanced. This allows you to override the plugin name, author, menu icons, and support URLs in the WordPress admin panel, making it suitable for client hand-offs.
Settings: Design, Maps & Navigation
Visual controls and map/navigation settings.
How do I configure map providers and filters?
Navigate to WP Admin → NexDirectory → Settings → Design & Maps. Here you can choose your Map Provider (e.g., Google Maps or Mapbox), customize default view layouts, set default focus regions, and toggle frontend filters (Date, Distance, Price, Type).
How do I update sensitive API keys safely?
To enter or update keys for Google Maps or reCAPTCHA, go to Settings → Design & Maps. To protect your keys, they will appear hidden once saved. Only leave the fields blank if you wish to keep the current stored values active. Rotate keys immediately if you suspect exposure.
How do I customize the theme styles and preloader?
Under Design & Maps, use the Style settings to configure font families, global accent colors, spacing metrics, and override theme padding. You can also toggle the custom SVG preloader screen for smoother SPA page transitions.
Settings: Monetization & Tickets
Revenue and checkout settings.
How do I configure listing Boosts?
Go to WP Admin → NexDirectory → Settings → Monetisation. Under the Boost settings, you can enable auto-renewals, specify duration-based pricing, configure visual highlight styles, and choose your primary Boost currency.
How do I configure Ticketing and Payment Gateways (Stripe/PayPal)?
Inside the Monetisation settings tab, you can toggle integrations for Stripe and PayPal. Be sure to select the correct Gateway Mode (Test or Live) and provide the respective Client ID and Secret Keys for the environment you intend to use.
Settings: Notifications & Email
Outbound email and alert operations.
How do I customize email templates and notifications?
Go to WP Admin → NexDirectory → Settings → Notifications / Advanced Email. From here, you can set the exact Subject and Body text for cancellations, confirmations, ticket orders, and reminders. You can also toggle which events trigger Admin or Author notifications.
How do I configure SMTP settings?
Inside Settings → Notifications / Advanced Email, toggle SMTP Enabled. Enter your Host, Port, Encryption method, and Username/Password to bypass standard wp_mail routing and improve email deliverability.
Settings: Submissions & Moderation
Workflow, permissions, and moderation settings.
How do I configure submission and moderation rules?
Go to WP Admin → NexDirectory → Settings → Submissions & Moderation. This central hub allows you to define who can submit listings, configure auto-approval rules, require email verification, and toggle custom taxonomies or form fields.
How do I manage media upload limits?
In Settings → Submissions & Moderation, look for the upload limit fields to restrict max file sizes (KB) and the total number of gallery images allowed per listing to protect server storage.
How do I manage listing claims?
Toggle Enable Claim Listings inside Submissions & Moderation. You can also specify the Claim Listing Page URL and enforce whether claims require Admin Approval before transferring ownership.
Shortcodes, Pages & Routing
Page setup and route controls.
How do I use NexDirectory shortcodes?
Add a shortcode like [nexdirectory_events_archive], [nexdirectory_submit], or [nexdirectory_events_map] to a standard WordPress page. After publishing, copy the page URL into NexDirectory Settings → Routing so internal links and redirects stay correct.
If a page appears blank, double-check your shortcode spelling, clear your cache, and reload.
How do I configure page routing and custom URLs?
Open Settings → General → Routing. Here you can fill out the exact URLs for your Map, Archive, Submit, Account, and Auth pages.
Always use the full URL (including https://). Save, then test these links in an incognito window.
Why are users sent to the wrong page after login?
Check Login Redirect URL and Auth page URL settings.
If a custom login page is enabled, keep all auth links pointing to that same page.
How do I fix broken route links after changing slugs?
Update route URL settings, regenerate pages if needed, and re-save permalinks in WordPress.
Then clear server and CDN cache.
How do I show or hide the frontend sticky navbar?
Use Settings → General → Navbar and toggle sticky nav per user state.
You can also switch to WP menu mode for role-specific navigation.
How do I enable SPA hybrid page transitions?
Turn on Enable SPA Hybrid in settings.
If your theme conflicts, turn it off and use full page loads.
How do I hide theme titles on plugin pages?
Enable title hiding under display/theme override settings.
This only affects plugin pages and helps avoid duplicate headers.
Troubleshooting
Error-driven fixes and diagnostics.
How do I fix common authentication and access errors (e.g., Not allowed, Login required)?
If users are hitting access walls, navigate to Settings → Roles & Access and ensure their user role (like event_submitter) has the correct capability toggled on. If the issue persists, test the action while logged in as an Administrator, and check the Diagnostics tab for session blockages.
How do I fix payment and checkout errors (Stripe/PayPal missing, mismatch, or failed)?
Payment failures typically stem from API environment mismatches. Ensure your Gateway Mode (Test vs. Live) in Settings → Monetisation perfectly matches the API keys you provided. If using Stripe Auto-Renew, verify that webhooks are successfully reaching your server.
How do I fix validation and missing field errors?
If a user encounters "Address is required" or "Message content is required" despite filling out the form, clear the browser cache and try again. For address failures specifically, ensure that Map providers are configured properly and not hitting rate limits, which can block geolocation inputs.
What are the best general troubleshooting steps for unknown errors?
If you encounter an unexpected error, follow these three steps:
1. Reload the page to ensure WP Nonce security tokens haven't expired.
2. Clear site, server, and CDN caching.
3. Open WP Admin → NexDirectory → Diagnostics and review the recent runtime logs for detailed traceback warnings.