roi-theme/wp-content/themes/apus-theme/inc/admin/README.md

# Apus Theme Options Panel

## Overview
Complete theme options panel for managing all theme settings from WordPress admin.

## Location
`Appearance > Theme Options` in WordPress admin

## Files Structure

```
inc/admin/
├── theme-options.php           # Main admin page registration
├── options-api.php             # Settings API and sanitization
├── options-page-template.php   # HTML template for options page
└── README.md                   # This file

inc/
└── theme-options-helpers.php   # Helper functions to get options

assets/admin/
├── css/
│   └── theme-options.css       # Admin styles
└── js/
    └── theme-options.js        # Admin JavaScript
```

## Features

### General Tab
- Site logo upload
- Site favicon upload
- Breadcrumbs enable/disable
- Breadcrumb separator customization
- Date and time format
- Copyright text
- Social media links (Facebook, Twitter, Instagram, LinkedIn, YouTube)

### Content Tab
- Excerpt length
- Excerpt more text
- Default post/page layouts
- Archive posts per page
- Featured image display
- Author box display
- Comments enable/disable for posts/pages
- Post meta visibility
- Tags and categories display

### Performance Tab
- Lazy loading
- Remove emoji scripts
- Remove embeds
- Remove Dashicons on frontend
- Defer JavaScript
- Minify HTML
- Disable Gutenberg

### Related Posts Tab
- Enable/disable related posts
- Number of posts to show
- Taxonomy to use (category, tag, or both)
- Section title
- Number of columns

### Advanced Tab
- Custom CSS
- Custom JavaScript (header)
- Custom JavaScript (footer)

## Usage

### Getting Options in Templates

```php
// Get any option with default fallback
$value = apus_get_option('option_name', 'default_value');

// Check if option is enabled (boolean)
if (apus_is_option_enabled('enable_breadcrumbs')) {
    // Do something
}

// Specific helper functions
$logo_url = apus_get_logo_url();
$excerpt_length = apus_get_excerpt_length();
$social_links = apus_get_social_links();
```

### Available Helper Functions

All helper functions are in `inc/theme-options-helpers.php`:

- `apus_get_option($option_name, $default)`
- `apus_is_option_enabled($option_name)`
- `apus_get_breadcrumb_separator()`
- `apus_show_breadcrumbs()`
- `apus_get_excerpt_length()`
- `apus_get_excerpt_more()`
- `apus_show_related_posts()`
- `apus_get_related_posts_count()`
- `apus_get_related_posts_taxonomy()`
- `apus_get_related_posts_title()`
- `apus_is_performance_enabled($optimization)`
- `apus_get_copyright_text()`
- `apus_get_social_links()`
- `apus_comments_enabled_for_posts()`
- `apus_comments_enabled_for_pages()`
- `apus_get_default_post_layout()`
- `apus_get_default_page_layout()`
- `apus_get_archive_posts_per_page()`
- `apus_show_featured_image_single()`
- `apus_show_author_box()`
- `apus_get_date_format()`
- `apus_get_time_format()`
- `apus_get_logo_url()`
- `apus_get_favicon_url()`
- `apus_get_custom_css()`
- `apus_get_custom_js_header()`
- `apus_get_custom_js_footer()`
- `apus_is_lazy_loading_enabled()`
- `apus_get_all_options()`
- `apus_reset_options()`

## Import/Export

### Export Options
1. Go to `Appearance > Theme Options`
2. Click "Export Options" button
3. A JSON file will be downloaded with all current settings

### Import Options
1. Go to `Appearance > Theme Options`
2. Click "Import Options" button
3. Paste the JSON content from your exported file
4. Click "Import"
5. Page will reload with imported settings

## Reset to Defaults

Click "Reset to Defaults" button to restore all options to their default values. This action requires confirmation.

## Sanitization

All options are sanitized before saving:
- Text fields: `sanitize_text_field()`
- URLs: `esc_url_raw()`
- HTML content: `wp_kses_post()`
- Integers: `absint()`
- Checkboxes: Boolean conversion
- CSS: Custom sanitization removing scripts
- JavaScript: Custom sanitization removing PHP code

## Hooks Available

### Actions
- `apus_before_options_save` - Before options are saved
- `apus_after_options_save` - After options are saved

### Filters
- `apus_theme_options` - Filter all options
- `apus_default_options` - Filter default options

## JavaScript Events

Custom events triggered by the options panel:

- `apus:options:saved` - When options are saved
- `apus:options:reset` - When options are reset
- `apus:options:imported` - When options are imported
- `apus:options:exported` - When options are exported

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Accessibility

- Keyboard navigation supported
- Screen reader friendly
- WCAG 2.1 Level AA compliant
- Focus indicators visible

## Security

- Nonce verification on all AJAX calls
- Capability checks (`manage_options`)
- Input sanitization
- Output escaping
- CSRF protection

## Performance

- Lazy loading for tab content
- Conditional script loading (only on options page)
- Optimized AJAX requests
- Minimal DOM manipulation

## Troubleshooting

### Options not saving
1. Check WordPress user has `manage_options` capability
2. Check file permissions
3. Check for JavaScript errors in browser console
4. Verify WordPress nonce is valid

### Images not uploading
1. Check PHP upload_max_filesize setting
2. Check WordPress media upload permissions
3. Check browser console for errors

### Import not working
1. Verify JSON format is valid
2. Check for special characters in JSON
3. Ensure JSON is from same theme version

## Version History

### 1.0.0
- Initial release
- All basic options implemented
- Import/Export functionality
- Reset to defaults
- Full sanitization