AppFolio Property Listings API Plugin

WordPress plugin that displays property listings from the AppFolio REST API.

📦 Plugin Information

• Name: AppFolio Property Listings API
• Version: 2.0.0
• Author: Nemanja Tanaskovic
• Description: Displays property listings from AppFolio API for Farmers Athens

🏗️ Architecture

This plugin uses an API-first architecture where WordPress pulls data from a Python backend service.

┌─────────────────────────────┐
│   Python Service (Railway)   │
│   - Scrapes AppFolio         │
│   - Serves REST API          │
└──────────┬──────────────────┘
           │ HTTPS
           ▼
┌─────────────────────────────┐
│   WordPress Plugin          │
│   - Calls API               │
│   - Displays Properties     │
└─────────────────────────────┘

📁 Files

• appfolio-property-listings-demo.php - Main plugin file
• assets/style.css - Frontend styles
• assets/script.js - Frontend JavaScript

🚀 Installation

Via WordPress Admin:

1. Go to Plugins → Add New → Upload Plugin
2. Upload the plugin files
3. Click Activate

Via FTP:

1. Upload the entire plugin folder to /wp-content/plugins/
2. Go to WordPress admin → Plugins
3. Find "AppFolio Property Listings API" and click Activate

⚙️ Configuration

Set API URL:

1. Go to Settings → AppFolio API in WordPress admin
2. Enter your Railway API URL (e.g., https://your-app.up.railway.app)
3. Click Save Changes
4. Click Test API Connection to verify

📝 Usage

Basic Shortcode:

Add this shortcode to any page or post:

[appfolio_properties]

With Filters:

Filter properties by price, bedrooms, bathrooms, or search term:

[appfolio_properties min_price="1000" max_price="2000" bedrooms="2"]

Search for specific properties:

[appfolio_properties search="athens"]

Hide filters:

[appfolio_properties show_filters="false"]

Parameters:

• show_filters - Show/hide filter UI (default: true)
• min_price - Minimum rent price (e.g., "1000")
• max_price - Maximum rent price (e.g., "2000")
• bedrooms - Number of bedrooms (e.g., "2")
• bathrooms - Number of bathrooms (e.g., "1.5")
• search - Search term (searches title, address, description)

🎨 Features

• ✅ API-First Architecture - Pulls data from REST API
• ✅ Smart Caching - 15-minute cache reduces API calls
• ✅ Admin Settings - Easy API URL configuration
• ✅ API Testing - Built-in connection test
• ✅ Cache Management - Clear cache button in admin
• ✅ Responsive Grid Layout - Beautiful property cards
• ✅ Advanced Filtering - Price, bedrooms, bathrooms, search
• ✅ Mobile-Optimized - Works perfectly on all devices
• ✅ AJAX-Powered - No page refresh
• ✅ Real-Time Search - Instant filtering
• ✅ XSS Protection - Secure HTML escaping

🔧 Technical Details

API Endpoints:

The plugin calls these endpoints on your Python service:

• GET /api/properties - Get all properties
• GET /api/properties?min_price=1000&max_price=2000 - Filtered properties
• GET /api/properties?search=athens - Search properties

AJAX Endpoint:

• Action: get_properties
• URL: WordPress AJAX URL
• Method: POST
• Nonce: Required

WordPress Hooks:

• admin_menu - Adds settings page
• admin_init - Registers settings
• wp_enqueue_scripts - Loads CSS/JS
• wp_ajax_get_properties - AJAX handler
• appfolio_properties - Shortcode

🎯 Frontend Features

Property Card Display:

• Property image with fallback
• Price prominently displayed
• Address and title
• Bedroom/bathroom count
• Square footage
• Property description
• View Details button (links to AppFolio)
• Contact button

Filtering:

• Price range dropdown (Under $1,000, $1,000-$1,500, etc.)
• Bedroom count filter (1+, 2+, 3+, 4+)
• Search bar for keywords
• Real-time filtering
• No page refresh

📱 Responsive Design

• Desktop: 3-column grid
• Tablet: 2-column grid
• Mobile: Single column
• All features work on all devices

🔄 Data Flow

1. Python Service scrapes AppFolio every 4 hours
2. API Server exposes properties via REST API
3. WordPress Plugin checks cache first, then calls API if needed
4. Cache stores responses for 15 minutes to reduce API calls
5. Frontend displays properties with filters

Caching Strategy

The plugin uses WordPress transients to cache API responses:

• Cache Duration: 15 minutes (configurable in code)
• Cache Keys: Based on filter parameters
• Benefits:
  • Reduces API calls by ~95%
  • Faster page loads
  • Lower hosting costs
  • Better performance
• Cache Management: Clear cache button in Settings → AppFolio API

🌐 Railway Deployment

This plugin works with the Python backend service on Railway:

1. Deploy Python service to Railway
2. Get your Railway URL (e.g., https://your-app.up.railway.app)
3. Configure API URL in WordPress Settings → AppFolio API
4. Add shortcode to pages
5. Done!

See the Python backend's README for deployment instructions.

🐛 Troubleshooting

Properties Not Showing:

• ✅ Check plugin is activated
• ✅ Verify API URL is configured in Settings → AppFolio API
• ✅ Test API connection using the "Test API Connection" button
• ✅ Check API logs on Railway
• ✅ Clear WordPress cache

API Connection Failed:

• ✅ Verify Railway service is running
• ✅ Check API URL format (no trailing slash)
• ✅ Test API URL in browser: https://your-app.up.railway.app/api/properties
• ✅ Check firewall/CORS settings

Images Not Loading:

• ✅ Check image URLs are valid
• ✅ Verify CORS settings on API
• ✅ Test in browser console
• ✅ Check Railway logs

Filters Not Working:

• ✅ Check jQuery is loaded
• ✅ Verify JavaScript is enqueued
• ✅ Check browser console for errors
• ✅ Clear browser cache

🔐 Security

• API URL stored securely in WordPress options
• Nonce verification on all AJAX requests
• HTML escaping to prevent XSS
• Input sanitization
• Proper capability checks

📞 Support

For issues or questions:

• Check WordPress error logs (wp-content/debug.log)
• Test API endpoints directly
• Verify plugin activation
• Check browser console for JavaScript errors
• Review Railway logs for API issues

🔄 Migration from Version 1.0

If you were using the old version with custom post types:

1. Install this new version
2. Configure API URL in Settings → AppFolio API
3. Remove old custom post types (optional)
4. Update shortcodes on pages
5. Done!

📄 License

This plugin is proprietary software developed for Farmers Athens.