← DamDir Directory Docs

DamDir Directory User Guide

This guide walks you through setting up your directory, creating listings, configuring features like search and reviews, and installing optional modules.

Getting Started

Installation

Automatic Installation

1. In your WordPress admin, go to Plugins → Add New.
2. Search for "DamDir Directory".
3. Click Install Now, then Activate.

Manual Installation

1. Download the plugin zip file.
2. Go to Plugins → Add New → Upload Plugin.
3. Upload the zip file and click Activate.

Initial Setup

After activation, follow these steps to get your directory running:

1. Configure Settings
   • Go to Listings → Settings.
   • Set your currency symbol and position.
   • Choose the default listing status (pending or published).
   • Enable or disable features (reviews, favorites, contact form).
2. Create Categories
   • Go to Listings → Categories.
   • Add your main categories (e.g., "Restaurants", "Hotels", "Services").
   • Set icons and colors for visual distinction.
3. Create Required Pages

   Create WordPress pages for each feature and add the corresponding shortcode:

   Page	Shortcode	Purpose
   All Listings	[apd_listings]	Main listings archive
   Submit Listing	[apd_submission_form]	Frontend submission
   My Dashboard	[apd_dashboard]	User dashboard
   My Favorites	[apd_favorites]	Saved listings

4. Add Menu Items
   • Go to Appearance → Menus.
   • Add your new pages to the navigation menu.

Settings page — General tab

Creating Listings

Creating Listings from Admin

1. Go to Listings → Add New.
2. Enter the listing title.
3. Add a description in the content editor.
4. Set a featured image (recommended size: 800×600px).
5. Select categories and tags.
6. Fill in custom fields in the "Listing Fields" meta box.
7. Set the publish status.
8. Click Publish or Save Draft.

Listing editor — content and sidebar meta

Listing editor — custom fields meta box

Listing Fields

The plugin ships with 24 field types. Installed modules may add more:

• Text fields — Single-line text (name, address, etc.)
• Textarea — Multi-line text (description, hours)
• Email — Email address with validation
• Phone — Phone number with formatting
• URL — Website links
• Number / Price — Numeric values with currency formatting
• Date / Time — Date and time pickers
• Select / Checkbox / Radio — Option selections
• File / Image — File uploads and images
• Gallery — Multiple images

Listing Statuses

Categories & Tags

Categories

Categories are hierarchical, so they can have parent/child relationships. Use them to organize listings into logical groups.

Creating Categories:

1. Go to Listings → Categories.
2. Enter a name and optional description.
3. Choose a parent category (optional) to create a hierarchy.
4. Select an icon (WordPress Dashicons).
5. Pick a color for the category badge.

Category management page

Popular Icon Choices:

• dashicons-location-alt — Location pin
• dashicons-store — Store / shop
• dashicons-building — Building
• dashicons-food — Food / restaurant
• dashicons-hammer — Services
• dashicons-calendar — Events

Tags

Tags are flat (no hierarchy) and useful for features, amenities, or attributes that cut across categories.

Examples:

• "Free WiFi", "Parking", "Pet Friendly"
• "Open 24/7", "Delivery Available"

Frontend Submission

Allow users to submit listings from the front end of your site without needing WordPress admin access.

Frontend Submission Setup

1. Create a page with the shortcode [apd_submission_form].
2. Configure submission settings in Listings → Settings → Submission:
   • Who can submit — Anyone, logged-in users, or specific roles.
   • Guest submission — Allow submissions without login.
   • Default status — Usually "Pending Review" for moderation.
   • Terms page — Require acceptance of your terms of service.
   • Redirect after — Where to send users after submission.

Frontend submission form

Submission Form Features

• All enabled fields are displayed automatically.
• Required fields are marked with asterisks.
• Client-side validation prevents incomplete submissions.
• Image uploads use the WordPress media library.
• Category and tag selection is included.

Spam Protection

The plugin includes built-in spam protection for frontend submissions:

• Honeypot fields — Invisible fields that only bots fill in.
• Time-based checks — Too-fast submissions are blocked.
• Rate limiting — Prevents mass submissions from the same user or IP.

Editing Listings

Users can edit their own listings after submission:

1. From the dashboard, click Edit on any listing.
2. Or navigate directly using the URL parameter: /submit-listing/?edit_listing=123

Search & Filtering

Search Form

Add search to any page with the [apd_search_form] shortcode.

Available Filters:

• Keyword — Searches title, content, and all searchable fields.
• Category — Filter by category (dropdown).
• Tags — Filter by multiple tags (checkboxes).
• Range — Filter by numeric fields (price, etc.).
• Date Range — Filter by date fields.

AJAX Filtering

Filters update results without a full page reload:

1. Select filter options.
2. Results update automatically via AJAX.
3. The URL updates so filtered results are shareable.

Search results with category filters

Sort Options

Users can sort results by:

• Date (newest / oldest)
• Title (A–Z, Z–A)
• View count (most / least viewed)
• Random

View Options

Switch between display modes:

• Grid View — Card layout with configurable columns.
• List View — Horizontal layout with more detail visible.

Reviews & Ratings

For Listing Owners

• Receive email notifications when someone reviews your listing.
• View reviews on your listing pages.
• Contact an admin to moderate inappropriate reviews.

Writing a Review

1. Go to a listing page.
2. Scroll to the reviews section.
3. Click "Write a Review".
4. Select a star rating (1–5).
5. Enter a review title and content.
6. Submit for moderation.

Single listing page with reviews

Review Rules:

• One review per user per listing.
• Users can edit their own reviews.
• Reviews may require admin approval before appearing publicly.

Review Moderation (Admins)

1. Go to Listings → Reviews.
2. View pending reviews.
3. Actions available: Approve, Reject, Spam, Trash.
4. Bulk actions are available for managing multiple reviews at once.

Favorites

Saving Favorites

Click the heart icon on any listing card to save it as a favorite.

• Logged-in users — Favorites are saved to their account permanently.
• Guests — Favorites are saved to browser cookies (30 days).

User dashboard — Favorites tab

Viewing Favorites

• Go to your dashboard's Favorites tab.
• Or use the [apd_favorites] shortcode on any page.

Guest to User Migration

When a guest logs in or registers, their cookie-based favorites are automatically merged with their account. No favorites are lost.

Contact Forms

For Visitors

1. Go to a listing page.
2. Find the contact form (usually in the sidebar).
3. Fill in your name, email, and message.
4. Optionally include a phone number.
5. Click Send.

For Listing Owners

• Receive email notifications for every inquiry.
• View inquiry stats in the dashboard.
• Optionally view full inquiry history.

For Admins

Enable or disable contact forms in Listings → Settings:

• "Enable Contact Form" checkbox to toggle the feature.
• Optional admin copy of all inquiries for oversight.

Email Notifications

The plugin sends email notifications automatically to keep admins and listing authors in the loop.

Admin Notifications

Listing Author Notifications

Configuration

Go to Listings → Settings → Email to configure notifications:

• Set the From Name and From Email used in outgoing messages.
• Set the Admin Email to receive admin notifications.
• Enable or disable individual notification types with toggle switches.

Settings — Email notifications tab

User Dashboard

The dashboard lets users manage their listings, favorites, and profile without needing WordPress admin access. Add it to any page with the [apd_dashboard] shortcode.

Dashboard Tabs

User dashboard — My Listings tab

My Listings Features

• View all listings with status badges (Published, Pending, Expired, etc.).
• See view counts and statistics for each listing.
• Available actions:
  • Edit — Modify listing details.
  • Delete — Remove a listing permanently.
  • Mark as Sold — Change the status for sold items.

Profile Settings

Users can update the following from the Profile tab:

• Display name
• Email address
• Profile photo / avatar
• Bio / description
• Phone number
• Website
• Social links (Facebook, Twitter, LinkedIn, Instagram, YouTube)

Modules

DamDir Directory ships with five optional modules, each a separate plugin that adds specialized fields, templates, and features for a particular directory type. All modules require DamDir Directory 1.0.0 or later.

URL Directory

Turn your directory into a curated website and link collection. Good for bookmark directories, resource lists, blogrolls, and web directories.

Key Features:

• Favicon Fetching — Automatically grabs website favicons using Google's service with DuckDuckGo as a fallback, so each listing displays the site's icon without manual uploads.
• Link Health Monitoring — Periodically checks listed URLs using HEAD requests to detect broken links. A link is flagged as broken after 3 consecutive failures, helping keep your directory clean.
• Outbound Click Tracking — Tracks clicks on listed URLs using the sendBeacon API with atomic SQL increments and rate limiting. See which listings get the most outbound traffic.
• Per-Listing Nofollow Control — Add a rel="nofollow" attribute on a per-listing basis to control how search engines follow outbound links.
• Demo Data — Generates realistic URLs and website listings so you can preview the directory before adding real content.

Business Directory

Build a local business listing platform similar to Yelp or Yellow Pages. Adds location-based search, maps, hours, and verification to your directory.

Key Features:

• Google Maps Integration — Embed interactive maps on listing pages with geocoding via Google Maps API or Nominatim (free, OpenStreetMap-based).
• Business Hours — Display structured business hours with real-time Open, Closed, and Closing Soon status indicators based on the current time.
• Claim Listing Workflow — Allow business owners to claim their listings with an admin-managed verification process.
• Verified Badges — Four verification levels to indicate trust and authenticity of claimed listings.
• Proximity Search — Let visitors search for businesses within a radius of a location, using the Haversine formula for distance calculations.
• Social Links — Display social media profiles (Facebook, Twitter, Instagram, LinkedIn, etc.) on business listing pages.
• Business Categories — Ships with 7 parent business categories to get started quickly.

Classifieds

Create a buy/sell/trade marketplace similar to Craigslist or Facebook Marketplace. Adds pricing, seller profiles, and moderation workflows for classified ad directories.

Key Features:

• Pricing & Condition Fields — Dedicated fields for price, item condition (new, used, refurbished, etc.), and negotiable pricing.
• 5 Listing Types — For Sale, Wanted, Free, Services, and Gigs, each with appropriate field sets.
• Organized Categories — 10 parent categories with 50 subcategories covering electronics, vehicles, furniture, clothing, and more.
• Seller Profiles — Seller reputation system with 4-category ratings: communication, accuracy, timeliness, and overall.
• Saved Searches with Alerts — Users can save search criteria and receive email alerts (instant, daily, or weekly) when matching listings are posted.
• Bump & Renewal Systems — Bumping pushes a listing to the top for 24 hours (3 per week limit). Renewals extend listings in 30-day periods with optional auto-renewal.
• Flag & Report Workflow — Visitors can flag inappropriate listings. After 3 flags, the listing enters an admin moderation queue for review.

Job Board

Build a job listing and recruitment platform. Adds structured job fields, application management, company profiles, and automated job alerts.

Key Features:

• 14 Job Fields — Job type (full-time, part-time, contract, etc.), salary range, experience level, required skills, remote work options, benefits, education requirements, application deadline, and more.
• 7-Status Application Workflow — Applications progress through: Pending → Reviewing → Shortlisted → Interviewed → Offered → Hired or Rejected.
• Resume Uploads — Applicants can upload resumes in PDF, DOC, or DOCX format (5 MB default limit).
• Company Profiles — Dedicated company pages with logo, description, website, and all associated job listings.
• Job Alerts — Users subscribe to job alerts and receive email notifications (instant, daily, or weekly) when new jobs matching their criteria are posted.
• 6 Shortcodes — Dedicated shortcodes for job listings, single job views, application forms, company profiles, job alerts, and job search.

Real Estate

Create a property listing website for sales and rentals. Adds property-specific fields, comparison tools, and virtual tour support.

Key Features:

• Property Details — Dedicated fields for bedrooms, bathrooms, square footage, lot size, year built, and property type (house, condo, townhouse, land, etc.).
• Listing Status — Track whether a property is For Sale, For Rent, or Sold.
• Virtual Tours — Embed virtual tour links or 360-degree media directly on property listing pages.
• Property Comparison — Visitors can compare up to 4 properties side by side, reviewing key details like price, size, bedrooms, and features in a comparison table.

Shortcodes Reference

[apd_listings view="grid" columns="3" count="12" category="restaurants"]

[apd_search_form filters="keyword,category,tag" layout="horizontal"]

[apd_categories layout="grid" columns="4" show_count="true"]

[apd_submission_form]

[apd_dashboard]

[apd_favorites view="grid" columns="3"]

[apd_login_form redirect="/dashboard/"]

[apd_register_form redirect="/dashboard/"]

Settings Reference

Access all plugin settings at Listings → Settings. Settings are organized into tabs.

General Tab

Listings Tab

Submission Tab

Display Tab

Email Tab

Advanced Tab

Template Customization

Overriding Templates

Customize the look of your directory by copying template files from the plugin to your theme. The plugin will automatically use your theme's version instead of the default.

plugins/damdir-directory/templates/
    → your-theme/damdir-directory/

Available Templates

Template Priority

WordPress checks for template overrides in this order:

1. Child theme: your-child-theme/damdir-directory/
2. Parent theme: your-theme/damdir-directory/
3. Plugin: damdir-directory/templates/

Always use a child theme for template overrides so your changes are preserved during theme updates.

Troubleshooting

Listings Not Appearing

1. Check the listing status — it must be "Published" to be visible.
2. Verify permalink settings: go to Settings → Permalinks and click Save Changes to flush rewrite rules.
3. Clear any caching plugins (WP Super Cache, W3 Total Cache, etc.).
4. Check that listings are assigned to the correct categories.

Search Not Working

1. Ensure the search form shortcode is placed on a published page.
2. Check that fields are marked as "searchable" in the field settings.
3. Verify that AJAX requests are not blocked by a security plugin or firewall.

User Actions Failing (REST / AJAX Errors)

If actions like favoriting, submitting reviews, or saving listings fail silently or show errors:

1. Open your browser's developer tools (F12) and check the Network tab for failed requests.
2. Look for the X-WP-Nonce header on outgoing requests — it must be present for all write operations.
3. Check the response body for these common error codes:
   • 401 rest_not_logged_in — The user is not authenticated. Ensure the user is logged in.
   • 403 rest_nonce_invalid — The nonce is missing, expired, or invalid. A page reload usually resolves this.
4. If nonces expire frequently, check if a caching plugin is serving stale pages to logged-in users.

Emails Not Sending

1. Install a mail plugin such as WP Mail SMTP to ensure reliable delivery.
2. Check your spam and junk folders.
3. Verify email settings in Listings → Settings → Email.
4. Enable debug mode to view error logs.

Images Not Uploading

1. Check file size limits in php.ini (upload_max_filesize and post_max_size).
2. Verify folder permissions on /wp-content/uploads/.
3. Check allowed file types in the plugin settings.

Performance Issues

1. Reduce the number of listings per page.
2. Enable a caching plugin.
3. Optimize images before upload.
4. Check server resources (memory, CPU) with your hosting provider.

404 Errors on Listings

1. Go to Settings → Permalinks.
2. Click "Save Changes" — this flushes rewrite rules.
3. If the issue persists, deactivate and reactivate the plugin.

Getting Help

If you need further assistance:

1. Check the WordPress.org support forum.
2. When reporting an issue, include: WordPress version, PHP version, error messages, and steps to reproduce the problem.

FAQ