# Troubleshooting Guide

## Common Issues and Solutions

### 1. "Content area was not found" Error

**Error Message:**
```
Sorry, the content area was not found in your page.
You must call 'the_content' function in the current template, 
in order for Elementor to work on this page.
```

**Cause:**
This error occurs when viewing a single AEFE Template directly and the template file doesn't properly call `the_content()` function, which Elementor requires.

**Solution:**
✅ **Already Fixed** - The `templates/single-afe-template.php` file now properly calls `the_content()` and handles both Elementor canvas templates and regular templates.

**How it works:**
- Checks if Elementor canvas template is being used
- Calls `the_content()` in the proper WordPress loop
- Supports both Elementor-built and regular content
- Handles theme header/footer appropriately

---

### 2. Template Not Displaying

**Symptoms:**
- Shortcode shows as text
- Template doesn't render
- Blank output

**Solutions:**

**A. Check Template Status**
- Ensure template is **Published** (not Draft)
- Verify template ID is correct
- Check if Elementor is active

**B. Verify Shortcode Syntax**
```php
✅ Correct: [aefe_embed id="123"]
❌ Wrong: [aefe_embed id=123]
❌ Wrong: {aefe_embed id="123"}
❌ Wrong: [aefe_embed]
```

**C. Check Conditional Attributes**
If using conditions, verify they match your context:
```php
// This won't show on desktop
[aefe_embed id="123" device="mobile"]

// This won't show to non-logged-in users
[aefe_embed id="123" role="subscriber"]

// This won't show on posts
[aefe_embed id="123" post_type="page"]
```

---

### 3. Elementor Editor Not Loading

**Symptoms:**
- "Edit with Elementor" button doesn't work
- Elementor editor shows blank screen
- Loading spinner never stops

**Solutions:**

**A. Clear Cache**
```
1. WordPress Admin → Elementor → Tools
2. Click "Regenerate CSS"
3. Click "Sync Library"
4. Clear browser cache (Ctrl+Shift+Delete)
```

**B. Check Permalinks**
```
1. WordPress Admin → Settings → Permalinks
2. Click "Save Changes" (even without changes)
3. This regenerates rewrite rules
```

**C. Check for Conflicts**
```
1. Temporarily disable other plugins
2. Switch to a default theme (Twenty Twenty-Three)
3. Test if Elementor editor loads
4. Re-enable plugins one by one to find conflict
```

**D. Increase PHP Limits**
Add to `wp-config.php`:
```php
define( 'WP_MEMORY_LIMIT', '256M' );
define( 'WP_MAX_MEMORY_LIMIT', '512M' );
```

---

### 4. Shortcode Shows as Plain Text

**Symptoms:**
- Shortcode appears as `[aefe_embed id="123"]` on frontend
- No template rendering

**Solutions:**

**A. Check Shortcode Support**
Some areas don't support shortcodes by default. Enable with:
```php
// In your theme's functions.php
add_filter( 'widget_text', 'do_shortcode' );
add_filter( 'the_excerpt', 'do_shortcode' );
```

**B. Verify Plugin is Active**
```
WordPress Admin → Plugins → Check if "AppsFruit Elementor Embed" is active
```

**C. Check for Typos**
```php
✅ [aefe_embed id="123"]
❌ [aefe-embed id=123]
❌ [aefe_emded id=123]
❌ [elementor_embed id=123]
```

---

### 5. Conditional Display Not Working

**Issue: Device Condition**

**Problem:** Template shows on all devices despite `device` attribute

**Solution:**
```php
// Check if wp_is_mobile() is working
// Add this to test:
add_action( 'wp_footer', function() {
    if ( current_user_can( 'manage_options' ) ) {
        echo '<div style="position:fixed;bottom:0;right:0;background:#000;color:#fff;padding:10px;">';
        echo wp_is_mobile() ? 'Mobile' : 'Desktop';
        echo '</div>';
    }
} );
```

**Note:** `wp_is_mobile()` detects user agent, not screen size. For screen-size detection, use CSS media queries instead.

---

**Issue: Role Condition**

**Problem:** Template shows to all users despite `role` attribute

**Solution:**
```php
// Verify user is logged in
// Role conditions only work for logged-in users

// Check current user role:
if ( is_user_logged_in() ) {
    $user = wp_get_current_user();
    echo 'Roles: ' . implode( ', ', $user->roles );
}
```

---

**Issue: Post Type Condition**

**Problem:** Template doesn't show on expected post types

**Solution:**
```php
// Verify you're on a singular post
// Post type conditions only work on single posts/pages

// Check current post type:
if ( is_singular() ) {
    echo 'Post Type: ' . get_post_type();
}
```

---

### 6. Gutenberg Block Not Appearing

**Symptoms:**
- Can't find "Insert Elementor Template" block
- Block search returns no results

**Solutions:**

**A. Clear Block Cache**
```
1. Save any work in progress
2. Refresh the page (Ctrl+R or Cmd+R)
3. Search for "elementor" or "template"
```

**B. Check Block Registration**
```php
// Add to functions.php to debug:
add_action( 'init', function() {
    if ( function_exists( 'register_block_type' ) ) {
        $registered = \WP_Block_Type_Registry::get_instance()->get_all_registered();
        if ( isset( $registered['afe/embed-template'] ) ) {
            error_log( 'AFE Block is registered' );
        }
    }
}, 999 );
```

**C. Verify Gutenberg is Active**
- Classic Editor plugin disables Gutenberg
- Check if you're using block editor or classic editor

---

### 7. Templates Not Syncing Globally

**Symptoms:**
- Changes to template don't appear everywhere
- Old version still showing on some pages

**Solutions:**

**A. Clear All Caches**
```
1. Elementor cache: Elementor → Tools → Regenerate CSS
2. WordPress cache: Delete cache plugin data
3. Browser cache: Ctrl+Shift+Delete
4. Server cache: Contact hosting provider
```

**B. Force Refresh**
```
Hold Shift and click browser refresh button
Or press Ctrl+Shift+R (Cmd+Shift+R on Mac)
```

**C. Check Caching Plugins**
Exclude AEFE Templates from caching:
```php
// Example for WP Rocket
add_filter( 'rocket_cache_reject_uri', function( $urls ) {
    $urls[] = '/aefe_template/(.*)';
    return $urls;
} );
```

---

### 8. Permission Issues

**Symptoms:**
- Can't create templates
- Can't edit templates
- "You don't have permission" error

**Solutions:**

**A. Check User Role**
```
AEFE Templates use 'page' capability type
Users need 'edit_pages' capability
```

**B. Grant Permissions**
```php
// Add to functions.php to give editors access:
add_action( 'admin_init', function() {
    $role = get_role( 'editor' );
    $role->add_cap( 'edit_pages' );
    $role->add_cap( 'edit_others_pages' );
    $role->add_cap( 'publish_pages' );
    $role->add_cap( 'delete_pages' );
} );
```

---

### 9. Styling Issues

**Issue: Template Styles Not Loading**

**Solution:**
```
1. Elementor → Tools → Regenerate CSS
2. Clear browser cache
3. Check if theme has conflicting styles
```

**Issue: Template Breaks Theme Layout**

**Solution:**
```php
// Wrap template with custom CSS:
add_filter( 'aefe_wrapper_classes', function( $classes ) {
    $classes[] = 'aefe-isolated';
    return $classes;
} );

// Add CSS to isolate template:
.aefe-isolated {
    all: initial;
    display: block;
}
```

---

### 10. Performance Issues

**Symptoms:**
- Slow page load
- Multiple templates cause lag
- High server load

**Solutions:**

**A. Limit Templates Per Page**
```
Don't embed too many heavy templates on one page
Consider lazy loading or conditional loading
```

**B. Optimize Elementor**
```
1. Elementor → Settings → Advanced
2. Enable "CSS Print Method: Internal Embedding"
3. Enable "Optimized DOM Output"
4. Disable unused widgets
```

**C. Use Caching**
```php
// Cache template output:
add_filter( 'aefe_template_content', function( $content, $post_id ) {
    $cache_key = 'aefe_template_' . $post_id;
    $cached = get_transient( $cache_key );
    
    if ( false === $cached ) {
        set_transient( $cache_key, $content, HOUR_IN_SECONDS );
    }
    
    return $content;
}, 10, 2 );
```

---

### 11. JavaScript Errors

**Symptoms:**
- Console shows JavaScript errors
- Interactive elements don't work
- Copy button doesn't work

**Solutions:**

**A. Check jQuery**
```
Ensure jQuery is loaded
Check browser console for errors
```

**B. Check for Conflicts**
```javascript
// Add to test for jQuery conflicts:
jQuery(document).ready(function($) {
    console.log('jQuery version:', $.fn.jquery);
    console.log('AFE Admin loaded:', typeof afeAdmin !== 'undefined');
});
```

**C. Reload Scripts**
```
Clear browser cache
Disable script optimization plugins temporarily
```

---

## Debug Mode

Enable WordPress debug mode to see detailed errors:

**Add to `wp-config.php`:**
```php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );
```

**Check debug log:**
```
wp-content/debug.log
```

---

## Getting Help

If issues persist:

1. **Check Documentation**
   - README.md
   - SETUP.md
   - DEVELOPER.md

2. **Gather Information**
   - WordPress version
   - PHP version
   - Elementor version
   - Plugin version
   - Active theme
   - Other active plugins
   - Error messages
   - Steps to reproduce

3. **Contact Support**
   - Email: support@appsfruit.com
   - Include all information from step 2
   - Attach screenshots if applicable

---

## Prevention Tips

✅ **Keep Everything Updated**
- WordPress core
- Elementor plugin
- AFE plugin
- PHP version

✅ **Use Staging Environment**
- Test changes before going live
- Verify compatibility

✅ **Regular Backups**
- Backup before major updates
- Use reliable backup plugin

✅ **Monitor Performance**
- Check page load times
- Monitor server resources
- Optimize as needed

✅ **Follow Best Practices**
- Use descriptive template names
- Organize with categories/tags
- Document custom code
- Test thoroughly

---

**Last Updated:** September 30, 2025  
**Plugin Version:** 1.0.2