Directorist – Bulk Actions

Welcome to Directorist Bulk Actions! This guide will help you master all the powerful features to efficiently manage your directory site.

Table of Contents #

1. Getting Started
2. Update Listings
3. Taxonomy Import/Export
4. Delete Listings
5. Set Coordinates
6. Run Update
7. Tips & Best Practices
8. Troubleshooting

Getting Started #

Accessing the Extension #

After activating the plugin, navigate to: WordPress Admin → Directorist → Bulk Actions

You’ll see six powerful tools organized in tabs. Each tool is designed for a specific bulk operation.

Important Safety Tips #

⚠️ Before You Begin:

• Always backup your database before performing bulk operations
• Test on a staging site first if you’re new to bulk operations
• Use “trash” deletion initially – you can always restore from WordPress trash
• Don’t switch tabs while an operation is in progress

Update Listings #

Purpose: Import new listings or update existing ones in bulk using a CSV file.

When to Use This #

• Importing new listings from another directory or database
• Updating multiple listings with new information (prices, descriptions, images)
• Adding images to multiple listings at once
• Reorganizing categories and locations across many listings

Step-by-Step Guide #

1. Prepare Your CSV File #

Create a CSV file with the following columns:

Required Column:

• id – Leave empty for new listings, or use existing listing ID to update

Post Fields:

• listing_title – The listing name
• listing_content – Full description
• publish_date – Format: 01/12/2024 10:30 (day/month/year hour:minute)

Taxonomy Fields:

• category – Comma-separated categories (e.g., “Restaurant, Pizza, Italian”)
• location – Comma-separated locations (e.g., “New York, Manhattan”)
• tag – Comma-separated tags

Media:

• images – Comma-separated image URLs (first becomes featured image)

Custom Fields:

• Any other column becomes a custom field (automatically prefixed with _)
• Example: phone, website, price_range

Example CSV:

id,listing_title,listing_content,category,location,phone,images

,”Joe’s Pizza”,”Best pizza in town”,”Restaurant,Pizza”,”New York”,555-0123,”https://example.com/pizza.jpg”

123,”Updated Title”,”New description”,”Cafe”,”Manhattan”,555-0124,

2. Select Directory Type #

Choose which directory type these listings belong to (General, Places, Events, etc.)

3. Upload Your CSV #

Click “Choose File” and select your prepared CSV file.

4. Start Import #

Click “Start Import/Update” and watch the progress bar. The process happens in batches to ensure reliability.

5. Review Results #

After completion, you’ll see:

• ✅ Successfully created/updated listings
• ❌ Any errors with specific reasons
• Detailed log of all operations

Pro Tips #

• Images: The plugin automatically downloads images from URLs and attaches them to listings
• Categories/Locations: If a category doesn’t exist, it’s automatically created
• Updates: Include the listing id to update existing listings instead of creating duplicates
• Testing: Import just 1-2 listings first to verify your CSV format is correct

Taxonomy Import/Export #

Purpose: Bulk import or export your categories and locations with all their settings.

Export Taxonomies #

When to Use #

• Creating backups of your category structure
• Migrating to another site
• Reviewing your current taxonomy setup
• Preparing templates for import

How to Export #

1. Select Taxonomy Type
   • Choose “Categories” or “Locations”
2. Click Export
   • A CSV file downloads automatically
3. Review the File
   • Opens in Excel, Google Sheets, or any CSV editor
   • Contains all term data: names, slugs, icons, images, hierarchy

Exported Data Includes:

• Term ID, name, and slug
• Description
• Parent term (for hierarchical structure)
• Category icon (Font Awesome class)
• Directory type associations
• Featured image URL

Import Taxonomies #

When to Use #

• Bulk creating categories for a new site
• Importing from another directory system
• Restoring from backup
• Adding hierarchical term structures

How to Import #

1. Prepare Your CSV

Required Columns:

• name – Term name (required)

Optional Columns:

• id – For updating existing terms
• slug – URL-friendly version of name
• description – Term description
• parent – Parent term name (for child categories)
• category_icon – Font Awesome icon class (e.g., fas fa-pizza-slice)
• directory_type – Comma-separated directory types (e.g., general,places)
• image – Image URL to download and attach

Example CSV:

name,slug,parent,category_icon,directory_type,image

Restaurants,restaurants,,fas fa-utensils,general,https://example.com/restaurant.jpg

Italian Food,italian-food,Restaurants,fas fa-pizza-slice,general,

Pizza,pizza,Italian Food,,,

2. Choose Taxonomy Type
   • Select “Categories” or “Locations”
3. Set Update Option
   • ☑️ Allow updates: Updates existing terms with new data
   • ☐ Skip existing: Only creates new terms
4. Upload CSV
   • Select your prepared file
5. Start Import
   • Watch progress and review results

Understanding Hierarchy #

The plugin automatically creates parent-child relationships:

• If you specify a parent that doesn’t exist, it’s created automatically
• Children can be imported before or after parents
• Multi-level hierarchies are fully supported

Pro Tips #

• Backup First: Export before importing to have a restore point
• Icons: Use Font Awesome classes for icons
• Images: Images are downloaded from URLs automatically
• Directory Types: Use the exact slug of your directory types

Delete Listings #

Purpose: Remove multiple listings at once based on filters.

When to Use This #

• Removing expired or outdated listings
• Cleaning up test data
• Deleting listings from specific categories or locations
• Removing listings by specific authors
• Mass cleanup operations

Step-by-Step Guide #

1. Set Your Filters #

Choose one or more filters to target specific listings:

Available Filters:

• Directory Type – Select which directory type (General, Places, etc.)
• Category – Choose one or multiple categories
• Status – Published, Draft, Pending, Expired, etc.
• Author – Filter by who created the listings

Example: “Delete all expired restaurant listings in New York”

• Directory Type: General
• Category: Restaurants
• Location: New York
• Status: Expired

2. View Listing Count #

As you select filters, the total number of matching listings updates automatically. This helps you verify you’re targeting the right listings.

3. Choose Deletion Type #

Trash (Recommended):

• Moves listings to WordPress trash
• Can be restored within 30 days
• Safe option for testing

Permanent:

• Deletes listings completely
• Cannot be undone
• Use only when certain

4. Media & Metadata Options (Optional) #

Delete Featured Image:

• ☑️ Removes the main listing image from media library

Delete Gallery Images:

• ☑️ Removes all gallery images from media library

Delete All Metadata:

• ☑️ Removes all custom fields and metadata
• Use with permanent deletion for complete cleanup

5. Confirm and Start #

1. Click “Start Delete”
2. Type “Delete” in the confirmation dialog
3. Watch real-time progress
4. Review completion summary

Pro Tips #

• Start Small: Test with a small filter first
• Use Trash First: Always start with trash deletion to test your filters
• Check Count: If the listing count seems wrong, review your filters
• Media Cleanup: Only delete media if those images aren’t used elsewhere

Safety Features #

• Typed Confirmation: Must type “Delete” exactly to proceed
• Real-time Logging: See which listings are being processed
• Batch Processing: Processes 5 listings at a time for reliability
• Progress Tracking: Know exactly how far along you are

Set Coordinates #

Purpose: Automatically add GPS coordinates (latitude/longitude) to all listings with addresses.

When to Use This #

• After importing listings without coordinates
• Fixing map display issues
• Updating coordinates after address changes
• Bulk geocoding for better map accuracy

Requirements #

✅ Google Maps API Key must be configured in Directorist settings

How to Set Up:

1. Go to Directorist → Settings → Map Settings
2. Enter your Google Maps API Key
3. Ensure “Geocoding API” is enabled on your Google Cloud Console

How It Works #

1. The plugin reads the address from each listing
2. Sends it to Google Maps Geocoding API
3. Receives coordinates (latitude/longitude)
4. Saves coordinates to listing metadata
5. Your maps now display listings accurately

Step-by-Step #

1. Verify API Key
   • Ensure Google Maps API key is set in Directorist settings
2. Click Start
   • The process begins immediately
   • Processes all published, private, and draft listings
3. Monitor Progress
   • Watch the progress bar
   • See how many listings have been updated
   • View real-time log of processing
4. Completion
   • Review total updated listings
   • Check any listings that couldn’t be geocoded

What Gets Updated #

Updated Fields:

• _manual_lat – Latitude coordinate
• _manual_lng – Longitude coordinate

These override any previous coordinates and improve map accuracy.

Troubleshooting #

No coordinates updating?

• Verify API key is correct
• Check if Geocoding API is enabled in Google Cloud Console
• Ensure listings have valid addresses
• Check Google Cloud Console for API quota limits

Some listings skipped?

• Listings without addresses are automatically skipped
• Invalid addresses may fail to geocode
• Check the log for specific error details

Pro Tips #

• Run Periodically: Especially after importing new listings
• API Costs: Google charges after free tier (~$0.005 per request)
• Address Quality: Better formatted addresses = better coordinates

Run Update #

Purpose: Execute custom update operations on all listings.

When to Use This #

This is an advanced feature for developers. It runs a custom action hook on every listing, allowing developers to implement custom bulk operations.

For Site Administrators #

If your developer has created custom functionality, this tool will:

1. Loop through all your listings
2. Apply the custom logic to each one
3. Show progress as it works

Before using:

• Confirm with your developer what the operation does
• Understand which listings will be affected
• Backup your database

For Developers #

Hook into the bulk update loop:

add_action(‘directorist_bulk_actions_run_update_loop’, function($post_id) {

// Your custom logic here

// Example: Recalculate ratings

// Example: Update custom meta fields

// Example: Sync with external API

}, 10, 1);

How to Use #

1. Click “Start Update”
2. Monitor progress
3. Review completion status

Note: This tool processes all listings regardless of status or category.

Tips & Best Practices #

Before Any Bulk Operation #

✅ Always backup your database

• Use a plugin like UpdraftPlus or BackupBuddy
• Or use your hosting control panel’s backup feature

✅ Test on staging first

• Clone your site to staging
• Test the operation there
• Verify results before running on live site

✅ Start small

• Test with 5-10 items first
• Verify the results
• Then run on your full dataset

During Operations #

⚠️ Don’t switch tabs

• Operations continue in the background
• Switching tabs may interrupt them
• Wait for “Completed” message

⚠️ Don’t close the browser

• Keep the tab open until completion
• Closing may stop the process mid-way

✅ Monitor the logs

• Watch for any error messages
• Note which items succeed/fail
• Use logs to troubleshoot issues

CSV Best Practices #

✅ Use proper encoding

• Save CSV files as UTF-8
• Ensures special characters display correctly

✅ Test your format

• Import just 1-2 rows first
• Verify all fields work as expected

✅ Clean your data

• Remove extra spaces
• Check for consistency
• Validate URLs for images

General Maintenance #

✅ Regular exports

• Export taxonomies monthly for backup
• Keep copies of your CSV imports

✅ Review before delete

• Double-check listing counts
• Verify your filters are correct
• Use trash first, then permanent

✅ Monitor performance

• Large operations may take time
• Be patient with thousands of listings
• Consider breaking very large imports into smaller batches

Troubleshooting #

Common Issues #

“Operations not working” #

Solution:

1. Check browser console for JavaScript errors (F12 → Console)
2. Verify you have Administrator role
3. Ensure Directorist plugin is active and updated
4. Clear browser cache and try again

“CSV import failing” #

Solution:

1. Verify CSV format matches examples
2. Check file encoding (should be UTF-8)
3. Test with a small 2-row CSV first
4. Remove special characters that might cause issues

“Images not importing” #

Solution:

1. Verify image URLs are publicly accessible
2. Check image file types (JPG, PNG, GIF supported)
3. Ensure URLs use https:// not http://
4. Test URLs in browser to confirm they load

“Coordinates not updating” #

Solution:

1. Verify Google Maps API key in Directorist settings
2. Enable Geocoding API in Google Cloud Console
3. Check API quota limits haven’t been exceeded
4. Ensure listings have valid address fields

“Operation stopped mid-way” #

Solution:

1. Don’t close browser or switch tabs during operations
2. Check if operation actually completed (scroll to bottom of page)
3. If truly stuck, refresh page and start with remaining items
4. Note the offset/count where it stopped

Getting Help #

Check the Logs

• Each operation shows detailed logs
• Look for specific error messages
• Note which items failed and why

System Requirements

• WordPress 5.8 or higher
• PHP 7.4 or higher
• Directorist 7.0 or higher

Still Need Help?

• Open an issue on GitHub
• Include WordPress version, PHP version, and error messages
• Describe what you’re trying to do and what’s happening

Support & Resources #

📚 Documentation: GitHub Wiki 🐛 Report Issues: GitHub Issues 💬 Community: Directorist Community

Thank you for using Directorist Bulk Actions! We hope this extension saves you countless hours and makes managing your directory a breeze. If you find it helpful, please consider leaving a review and sharing with others who might benefit.