Customization Guide - MagicWP Documentation

1 CSS Customization

MagicWP modules use well-structured CSS that's easy to override. All styles are prefixed with magicwp- to avoid conflicts.

Method 1: WordPress Customizer

Add custom CSS through the WordPress Customizer:

Go to Appearance → Customize
Click on Additional CSS
Add your custom CSS code
Click Publish

Example CSS

/* Change Back to Top button color */
.magicwp-back-to-top {
    background: #ff6b6b !important;
}

/* Customize Floating Icons size */
.magicwp-floating-icons .icon {
    width: 50px !important;
    height: 50px !important;
}

/* Style the Search overlay */
.magicwp-search-overlay {
    backdrop-filter: blur(10px);
    background: rgba(0, 0, 0, 0.8) !important;
}

Method 2: Child Theme

For more extensive customization, use a child theme:

Create a child theme (or use existing one)
Create a file named magicwp-custom.css
Add your custom styles
Enqueue the stylesheet in your functions.php

functions.php

function my_magicwp_custom_styles() {
    wp_enqueue_style(
        'magicwp-custom',
        get_stylesheet_directory_uri() . '/magicwp-custom.css',
        array(), // Dependencies
        '1.0.0'
    );
}
add_action( 'wp_enqueue_scripts', 'my_magicwp_custom_styles', 100 );

CSS Specificity

Use !important sparingly. MagicWP styles have moderate specificity, so you can usually override them without !important.

2 WordPress Hooks & Filters

MagicWP provides several hooks and filters for developers to customize functionality.

Available Action Hooks

Hook Name	Description	Parameters
`magicwp_init`	Fires after MagicWP initializes	None
`magicwp_module_loaded`	Fires when a module is loaded	`$module_id`
`magicwp_before_settings_save`	Before module settings are saved	`$module_id`, `$settings`
`magicwp_after_settings_save`	After module settings are saved	`$module_id`, `$settings`

Example Usage

// Run custom code when MagicWP initializes
add_action( 'magicwp_init', function() {
    // Your custom code here
    error_log( 'MagicWP has been initialized!' );
});

// Track when a module is enabled
add_action( 'magicwp_module_loaded', function( $module_id ) {
    if ( $module_id === 'magic-search' ) {
        // Magic Search module is now active
    }
}, 10, 1 );

Available Filter Hooks

Filter Name	Description	Parameters
`magicwp_module_settings`	Filter module settings before use	`$settings`, `$module_id`
`magicwp_enqueue_assets`	Control whether to enqueue module assets	`$enqueue`, `$module_id`
`magicwp_search_results`	Filter Magic Search results	`$results`, `$query`
`magicwp_cookie_consent_message`	Customize cookie consent message	`$message`

Example Usage

// Modify module settings programmatically
add_filter( 'magicwp_module_settings', function( $settings, $module_id ) {
    if ( $module_id === 'magic-floating-icons' ) {
        // Change button color based on current page
        if ( is_singular( 'product' ) ) {
            $settings['button_color'] = '#ff6b6b';
        }
    }
    return $settings;
}, 10, 2 );

// Conditionally disable module assets on specific pages
add_filter( 'magicwp_enqueue_assets', function( $enqueue, $module_id ) {
    // Don't load floating icons on checkout page
    if ( $module_id === 'magic-floating-icons' && is_checkout() ) {
        return false;
    }
    return $enqueue;
}, 10, 2 );

3 Creating Custom Modules

Advanced developers can create custom modules that integrate seamlessly with MagicWP.

Module Structure

Create a new directory in wp-content/plugins/magicwp/modules/:

Directory Structure

modules/
└── my-custom-module/
    ├── class-module.php      // Main module class
    ├── assets/
    │   ├── css/
    │   │   └── style.css
    │   └── js/
    │       └── script.js
    └── includes/             // Additional PHP files (optional)

Module Template

class-module.php

<?php
namespace MagicWP\Modules\My_Custom_Module;

class Module extends \MagicWP\Core\Module_Base {

    protected $module_id = 'my-custom-module';
    protected $module_name = 'My Custom Module';
    protected $module_description = 'Description of my module';
    protected $module_version = '1.0.0';

    /**
     * Initialize the module
     */
    public function init() {
        // Module initialization code
        $this->register_hooks();
    }

    /**
     * Register WordPress hooks
     */
    public function register_hooks() {
        add_action( 'wp_footer', [ $this, 'render_output' ] );
    }

    /**
     * Get settings schema
     */
    public function get_settings_schema() {
        return array(
            'my_setting' => array(
                'type' => 'text',
                'label' => __( 'My Setting', 'magicwp' ),
                'default' => 'Default value',
            ),
        );
    }

    /**
     * Enqueue frontend assets
     */
    public function enqueue_frontend_assets() {
        wp_enqueue_style(
            'magicwp-my-module',
            $this->module_url . 'assets/css/style.css',
            array(),
            $this->module_version
        );

        wp_enqueue_script(
            'magicwp-my-module',
            $this->module_url . 'assets/js/script.js',
            array(),
            $this->module_version,
            true
        );
    }

    /**
     * Render module output
     */
    public function render_output() {
        $settings = $this->get_settings();
        // Output your HTML
    }
}

Important Note

Custom modules added directly to the plugin directory will be lost during updates. Consider creating modules as separate plugins or use a child plugin approach.

4 JavaScript API

MagicWP exposes JavaScript APIs for frontend interaction with certain modules.

Magic Search API

JavaScript

// Open search programmatically
MagicWP.Search.open();

// Close search
MagicWP.Search.close();

// Listen for search events
document.addEventListener('magicwp:search:opened', function() {
    console.log('Search overlay opened');
});

document.addEventListener('magicwp:search:closed', function() {
    console.log('Search overlay closed');
});

Back to Top API

JavaScript

// Scroll to top programmatically
MagicWP.BackToTop.scrollToTop();

// Check if button is visible
const isVisible = MagicWP.BackToTop.isVisible();

Cookie Consent API

JavaScript

// Check if user has accepted cookies
const hasConsent = MagicWP.CookieConsent.hasConsent();

// Show cookie consent banner again
MagicWP.CookieConsent.show();

// Listen for consent events
document.addEventListener('magicwp:cookies:accepted', function() {
    // User accepted cookies - load analytics, etc.
});

5 Theme Integration

Ensure MagicWP works seamlessly with your theme.

Color Scheme Integration

Make MagicWP modules match your theme colors:

functions.php

// Automatically set module colors to match theme
add_filter( 'magicwp_module_settings', function( $settings, $module_id ) {
    // Get theme primary color
    $primary_color = get_theme_mod( 'primary_color', '#1e90ff' );

    // Apply to all color settings
    foreach ( $settings as $key => $value ) {
        if ( strpos( $key, '_color' ) !== false ) {
            $settings[$key] = $primary_color;
        }
    }

    return $settings;
}, 10, 2 );

Responsive Breakpoints

Align MagicWP with your theme's breakpoints:

CSS

/* Match theme breakpoints */
@media (max-width: 768px) {
    .magicwp-floating-icons {
        /* Mobile styles */
    }
}

@media (max-width: 1024px) {
    .magicwp-search-overlay {
        /* Tablet styles */
    }
}

6 Performance Optimization

Tips for optimizing MagicWP's performance on your site.

Selective Loading

Load modules only where needed:

functions.php

// Disable module on specific pages
add_filter( 'magicwp_enqueue_assets', function( $enqueue, $module_id ) {
    // Don't load search on landing pages
    if ( $module_id === 'magic-search' && is_page( 'landing' ) ) {
        return false;
    }

    // Only load polls on blog pages
    if ( $module_id === 'magic-visitor-poll' && ! is_singular( 'post' ) ) {
        return false;
    }

    return $enqueue;
}, 10, 2 );

Asset Optimization

Enable Caching: Use a caching plugin (WP Rocket, W3 Total Cache)
Minify Assets: Enable the Magic Performance Mode module
CDN Integration: Use a CDN to serve MagicWP assets
Lazy Load: Only enabled modules load their assets

Performance Tip

MagicWP is designed to be lightweight. Each module only loads when enabled, and assets are minified in production. Typical overhead is less than 50KB total.

7 Troubleshooting Custom Code

Common issues when customizing MagicWP:

CSS Not Applying

Check CSS specificity - you may need !important
Clear browser cache and WordPress cache
Inspect element to verify correct selector
Ensure custom CSS is enqueued after MagicWP styles

Hooks Not Firing

Verify hook name is correct (check spelling)
Ensure priority is appropriate (default is 10)
Check that function accepts correct number of parameters
Add error_log() to verify function is called

JavaScript Errors

Open browser console to see error messages
Ensure jQuery is loaded if you're using it
Check for conflicts with other plugins
Verify MagicWP object is available: console.log(MagicWP)

Debug Mode

Enable WordPress debug mode in wp-config.php to see detailed error messages:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

8 Developer Resources

Additional resources for developers:

GitHub Repository: github.com/magicwp/magicwp
Issue Tracker: Report bugs and request features on GitHub Issues
Community Forum: community.magicwp.pro
Developer Email: dev@magicwp.pro

Contributing

MagicWP is open source! Contributions are welcome. Fork the repository, make your changes, and submit a pull request. Check the CONTRIBUTING.md file for guidelines.