# Troubleshooting Guide

This guide helps you solve common issues with the Itinerator WordPress plugin.

## Quick Diagnosis

### Check API Keys
1. **Verify Platform API Key** is valid
2. **Test DMO API Key** (if using DMO content)
3. **Check Google Maps API Key** (if using maps)

## Common Issues

### No Content Displaying

**Symptoms:**
- Blocks show "No content to display"
- Empty pages with no error messages
- "Loading..." messages that never complete

**Solutions:**
1. **Check API keys** in Itinerator → Settings
2. **Verify content exists** in your Tourismo admin
3. **Clear caching plugins** (W3 Total Cache, WP Rocket, etc.)
4. **Clear Itinerator Cache** (From Admin bar or plugin Settings screen.)
5. **Check browser console** for JavaScript errors
6. **Test with a simple block** first

**Debugging Steps:**
```bash
# Check if API is responding
curl -H "Authorization: Bearer YOUR_API_KEY" https://admin.itinerator.ca/api/wp/v1/itineraries
```

### Blocks Not Appearing

**Symptoms:**
- No Itinerator blocks in block inserter
- "Itinerator" not found in block search
- Missing block categories

**Solutions:**
1. **Verify plugin activation** in Plugins → Installed Plugins
2. **Check WordPress version** (requires 5.0+)
3. **Ensure you're using block editor** (not classic editor)
4. **Clear browser cache** and refresh
5. **Check for JavaScript errors** in browser console

**Debugging Steps:**
- Try a different browser
- Check API key is valid, resave the plugin settings page.
- Disable other plugins temporarily
- Check if theme supports Gutenberg

### Layout Issues

**Symptoms:**
- Blocks not aligned properly
- Responsive design not working
- CSS conflicts with theme

**Solutions:**
1. **Check Bootstrap compatibility** - Plugin uses Bootstrap 4.6.1
2. **Test different column settings** (1-4 columns)
3. **Try different alignment options**
4. **Add custom CSS classes** for styling
5. **Check theme CSS conflicts**


### Performance Problems

**Symptoms:**
- Slow page loading
- High server resource usage
- Timeout errors

**Solutions:**
1. **Use page whitelist** in settings to limit script loading
2. **Enable Itinerator caching** (From plugin Settings page)
3. **Reduce number of blocks** per page
4. **Optimize images** in your Tourismo admin
5. **Use appropriate cache settings**

**Performance Tips:**
- Limit to 5-10 blocks per page

### Google Maps Not Working

**Symptoms:**
- Maps not displaying
- "Google Maps API error" messages
- Blank map areas

**Solutions:**
1. **Verify Google Maps API key** in settings
2. **Check API key restrictions** (domain, IP)
3. **Enable Maps JavaScript API** in Google Cloud Console
4. **Set up billing** in Google Cloud Console
5. **Check API quota** and usage limits

**API Key Setup:**
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create or select a project
3. Enable Maps JavaScript API
4. Create credentials (API key)
5. Restrict key to your domain
6. Add key to plugin settings

### Shortcode Issues

**Symptoms:**
- Shortcodes not rendering
- "Shortcode not found" errors
- Shortcodes showing as text

**Solutions:**
1. **Verify shortcode syntax** (check brackets and quotes)
2. **Check if plugin is activated**
3. **Clear page builder caches**
4. **Test shortcode in classic editor**
5. **Copy shortcode from block settings**
6. **Verify that each shortcode has required attributes, see block description**

**Common Shortcode Mistakes:**
```bash
# Wrong - missing quotes
[tourismo-itineraries show_title=true]

# Correct - with quotes
[tourismo-itineraries show_title="true"]

# Wrong - extra spaces
[tourismo-itineraries show_title = "true"]

# Correct - no extra spaces
[tourismo-itineraries show_title="true"]
```

### Theme Compatibility

**Symptoms:**
- Blocks not styling properly
- Layout conflicts with theme
- Missing Bootstrap styles

**Solutions:**
1. **Use custom CSS classes** for styling
2. **Test with default WordPress theme**
3. **Contact theme developer** for compatibility


## Advanced Troubleshooting

### Debug Mode

Enable WordPress debug mode to see detailed error messages:

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

### Check Error Logs

**WordPress Debug Log:**
- Location: `/wp-content/debug.log`
- Check for PHP errors and warnings

**Server Error Logs:**
- Apache: `/var/log/apache2/error.log`
- Nginx: `/var/log/nginx/error.log`
- Check for server-level issues

### API Testing

Test API connectivity directly:

```bash
# Test Platform API
curl -H "Authorization: Bearer YOUR_PLATFORM_API_KEY" \
     https://admin.tourismo.co/api/wp/v1/itineraries

# Test DMO API (if applicable)
curl -H "Authorization: Bearer YOUR_DMO_API_KEY" \
     https://admin.tourismo.co/api/wp/v1/dmos
```

### Browser Developer Tools

1. **Open Developer Tools** (F12)
2. **Check Console** for JavaScript errors
3. **Check Network** tab for failed requests
4. **Check Elements** tab for CSS issues

## Getting Help

### Before Contacting Support

1. **Document the issue:**
   - Screenshots of the problem
   - Error messages (exact text)
   - Steps to reproduce
   - Browser and device information

2. **Gather system information:**
   - WordPress version
   - Plugin version
   - Theme name and version
   - PHP version
   - Server environment

3. **Test basic functionality:**
   - Try with default WordPress theme
   - Disable other plugins temporarily
   - Test in different browser
   - Check on mobile device

### Contact Information

**Itinerator Support:**
- Email: support@itinerator.ca
- Website: https://support.tourismo.co
- Include detailed issue description

**WordPress Support:**
- For general WordPress issues
- WordPress.org support forums

## Prevention Tips

### Regular Maintenance
- **Keep WordPress updated**
- **Update plugins regularly**
- **Backup your site** before major changes
- **Monitor error logs**

### Best Practices
- **Test changes** on staging site first
- **Use appropriate caching** settings
- **Optimize images** before uploading
- **Monitor performance** regularly

### Documentation
- **Keep notes** of customizations
- **Document API keys** and settings
- **Save working configurations**
- **Track changes** over time

---

**Still having issues?** Contact Itinerator support with detailed information about your problem.