# Apus Theme - Options Panel

Complete theme options panel for WordPress admin. Centralizes all theme settings in one modern, user-friendly interface.

## 🎯 Quick Access

**WordPress Admin:** `Appearance > Theme Options`

## 📦 What's Included

### Core Files (4)
- `inc/theme-options-helpers.php` - Helper functions library (30+ functions)
- `inc/admin/theme-options.php` - Admin menu and AJAX handlers
- `inc/admin/options-api.php` - Settings API implementation
- `inc/admin/options-page-template.php` - Complete HTML interface

### Assets (2)
- `assets/admin/css/theme-options.css` - Modern styling
- `assets/admin/js/theme-options.js` - Interactive functionality

### Documentation (6)
- `README-THEME-OPTIONS.md` - This file
- `QUICK-START-OPTIONS-PANEL.md` - Quick start guide
- `THEME-OPTIONS-STRUCTURE.txt` - Visual structure
- `ISSUE-14-COMPLETION-REPORT.md` - Complete project report
- `inc/admin/README.md` - Technical documentation
- `inc/admin/USAGE-EXAMPLES.php` - Code examples
- `inc/admin/TEST-CHECKLIST.md` - Testing guide

## ✨ Features

### 5 Organized Tabs
1. **General** - Logo, branding, breadcrumbs, social media
2. **Content** - Posts, pages, excerpts, layouts
3. **Performance** - Optimizations, lazy loading, script removal
4. **Related Posts** - Configuration for related posts display
5. **Advanced** - Custom CSS/JS

### Special Functions
- ✅ Import/Export settings (JSON)
- ✅ Reset to defaults
- ✅ Image upload via Media Library
- ✅ Live validation
- ✅ Tab navigation with URL hash
- ✅ Responsive design

## 🚀 Quick Start

### 1. Access
```
WordPress Admin > Appearance > Theme Options
```

### 2. Configure
Navigate through tabs and set your preferences

### 3. Use in Templates
```php
// Get logo
$logo_url = apus_get_logo_url();

// Check breadcrumbs
if (apus_show_breadcrumbs()) {
    $separator = apus_get_breadcrumb_separator();
}

// Related posts
if (apus_show_related_posts()) {
    $count = apus_get_related_posts_count();
}
```

## 📚 Documentation

### For Users
- **QUICK-START-OPTIONS-PANEL.md** - Get started in 3 steps

### For Developers
- **inc/admin/README.md** - Complete technical guide
- **inc/admin/USAGE-EXAMPLES.php** - 20 practical examples
- **THEME-OPTIONS-STRUCTURE.txt** - Visual structure overview

### For Testers
- **inc/admin/TEST-CHECKLIST.md** - 200+ test points

### For Project Managers
- **ISSUE-14-COMPLETION-REPORT.md** - Full project documentation

## 🔒 Security

- ✅ Nonce verification on all AJAX calls
- ✅ Capability checks (`manage_options`)
- ✅ Input sanitization (type-specific)
- ✅ Output escaping
- ✅ CSRF protection
- ✅ XSS prevention

## ⚡ Performance

- Assets load only on options page
- Minimal DOM manipulation
- Optimized AJAX calls
- Responsive images
- CSS: 8.1KB, JS: 16KB (unminified)

## ♿ Accessibility

- WCAG 2.1 Level AA compliant
- Full keyboard navigation
- Screen reader support
- Visible focus indicators
- Proper ARIA attributes

## 🌐 Compatibility

- WordPress 6.0+
- PHP 8.0+
- All modern browsers
- Fully responsive

## 📊 Statistics

- **Total Options:** 39+
- **Helper Functions:** 30+
- **Lines of Code:** 3,052+
- **Files Created:** 12
- **Tabs:** 5

## 🎨 Usage Examples

### Display Logo in Header
```php
<?php
$logo_url = apus_get_logo_url();
if ($logo_url) {
    ?>
    <a href="<?php echo home_url('/'); ?>" class="logo">
        <img src="<?php echo esc_url($logo_url); ?>"
             alt="<?php bloginfo('name'); ?>" />
    </a>
    <?php
} else {
    bloginfo('name');
}
?>
```

### Show Breadcrumbs
```php
<?php
if (apus_show_breadcrumbs() && !is_front_page()) {
    $separator = apus_get_breadcrumb_separator();
    // Your breadcrumb code here
}
?>
```

### Display Related Posts
```php
<?php
if (is_single() && apus_show_related_posts()) {
    $count = apus_get_related_posts_count();
    $title = apus_get_related_posts_title();
    // Your related posts code here
}
?>
```

### Check Performance Options
```php
<?php
if (apus_is_performance_enabled('remove_emoji')) {
    // Emoji scripts will be removed
}

if (apus_is_lazy_loading_enabled()) {
    // Images will have lazy loading
}
?>
```

## 🛠️ Available Helper Functions

### General
- `apus_get_option($name, $default)`
- `apus_is_option_enabled($name)`
- `apus_get_all_options()`

### Logo & Branding
- `apus_get_logo_url()`
- `apus_get_favicon_url()`
- `apus_get_copyright_text()`

### Breadcrumbs
- `apus_show_breadcrumbs()`
- `apus_get_breadcrumb_separator()`

### Content
- `apus_get_excerpt_length()`
- `apus_get_excerpt_more()`
- `apus_show_featured_image_single()`
- `apus_show_author_box()`

### Related Posts
- `apus_show_related_posts()`
- `apus_get_related_posts_count()`
- `apus_get_related_posts_taxonomy()`
- `apus_get_related_posts_title()`

### Social Media
- `apus_get_social_links()`

### Performance
- `apus_is_lazy_loading_enabled()`
- `apus_is_performance_enabled($name)`

### Advanced
- `apus_get_custom_css()`
- `apus_get_custom_js_header()`
- `apus_get_custom_js_footer()`

See **inc/admin/README.md** for complete function list.

## 📝 Options List

### General Tab (12)
- Site Logo, Favicon
- Breadcrumbs, Separator
- Date/Time Format
- Copyright Text
- Social Media (5 networks)

### Content Tab (12)
- Excerpt Length/More
- Post/Page Layouts
- Archive Settings
- Featured Image
- Author Box
- Comments
- Post Meta/Tags/Categories

### Performance Tab (7)
- Lazy Loading
- Remove Emoji/Embeds/Dashicons
- Defer JS
- Minify HTML
- Disable Gutenberg

### Related Posts Tab (5)
- Enable/Count
- Taxonomy
- Title/Columns

### Advanced Tab (3)
- Custom CSS
- Custom JS (Header/Footer)

## 🔄 Import/Export

### Export
1. Click "Export Options"
2. JSON file downloads
3. Save for backup

### Import
1. Click "Import Options"
2. Paste JSON
3. Click "Import"
4. Settings restored

## 🔄 Reset

Click "Reset to Defaults" to restore all options to default values.
**Warning:** This cannot be undone. Export first!

## 🐛 Troubleshooting

### Settings Not Saving
- Check admin permissions
- Check browser console (F12)
- Clear cache

### Images Not Uploading
- Check file size
- Check file permissions
- Try different format

### Changes Not Visible
- Clear browser cache
- Clear WordPress cache
- Hard refresh (Ctrl+F5)

## 📞 Support

1. Check **QUICK-START-OPTIONS-PANEL.md**
2. Review **inc/admin/README.md**
3. See **inc/admin/USAGE-EXAMPLES.php**
4. Check **inc/admin/TEST-CHECKLIST.md**

## 📄 License

Part of Apus Theme. All rights reserved.

## 👥 Credits

Developed for Apus Theme v1.0.0

---

**Version:** 1.0.0
**Last Updated:** 2025-11-03
**Status:** Production Ready ✅

For complete documentation, see all README files in the theme directory.