Custom Theme

Custom themes are a popular choice for WordPress users who want to create a unique design for their website. By using a custom theme, you can tailor the appearance and functionality of your site to meet your specific needs. WindPress provides seamless integration with WordPress custom themes, allowing you to use Tailwind CSS in your custom theme with straightforward configuration.

Using Tailwind CSS with a custom theme

WindPress integrates Tailwind CSS into WordPress using a hybrid approach. We advise implementing this integration within your custom theme for both development and production environments.

Development environment

By default, WindPress loads the necessary libraries via the WordPress hook wp_head on the front-end. If your custom theme use the WordPress hook wp_head on the template, no additional configuration is needed and you can continue to the next section.

During development, WindPress loads the necessary libraries to provide a complete Tailwind CSS experience, including the compiler that allows you to use any Tailwind CSS classes and generates styles on-demand.

Add the following code snippet to the header.php file in your custom theme to load the necessary libraries:

header.php

<?php

$is_cache_enabled = apply_filters('f!windpress/core/runtime:append_header.cache_enabled', \WindPress\WindPress\Utils\Config::get('performance.cache.enabled', false));
$is_exclude_admin = apply_filters('f!windpress/core/runtime:append_header.exclude_admin', \WindPress\WindPress\Utils\Config::get('performance.cache.exclude_admin', false) && current_user_can('manage_options'));

$runtime = \WindPress\WindPress\Core\Runtime::get_instance();

$runtime->print_windpress_metadata();

if (!$is_exclude_admin && $is_cache_enabled && $runtime->is_cache_exists()) {
    $runtime->enqueue_css_cache();
} else {
    $runtime->enqueue_play_cdn();
}

Production environment

In the production environment, WindPress scans your custom theme for all the Tailwind CSS classes used and generates a single CSS file that contains only the styles used in the WordPress custom theme.

The scanner collects all content from the custom theme and sends it to the compiler to generate the cached CSS file. The scanner determines how to gather content from the custom theme by implementing a callback function.

Learn how to make your own scanner for the custom theme.

Step 1: Register the scanner

To register your scanner for the custom theme, add the following code snippet to the functions.php file in your custom theme:

functions.php

<?php

/**
 * @param array $providers The collection of providers that will be used to scan the design payload
 * @return array
 */
function register_my_theme_provider(array $providers): array {
    $providers[] = [
        'id' => 'my_theme', // The id of this custom provider. It should be unique across all providers
        'name' => 'My Theme Scanner',
        'description' => 'Scans the current active theme and child theme',
        'callback' => 'scanner_cb_my_theme_provider', // The function that will be called to get the data. Please see the next step for the implementation
        'enabled' => \WindPress\WindPress\Utils\Config::get(sprintf(
            'integration.%s.enabled',
            'my_theme' // The id of this custom provider
        ), true),
    ];

    return $providers;
}
add_filter('f!windpress/core/cache:compile.providers', 'register_my_theme_provider');

Step 2: Implement the scanner's callback

A scanner's callback function will be called during the cache CSS generation process.

Let's implement the scanner's callback function to gather content from the custom theme. Add the following code snippet to the functions.php file in your custom theme:

functions.php

<?php

function scanner_cb_my_theme_provider(): array {
    // The file with this extension will be scanned, you can add more extensions if needed
    $file_extensions = [
        'php',
        'js',
        'html',
    ];

    $contents = [];
    $finder = new \WindPressDeps\Symfony\Component\Finder\Finder();

    // The current active theme
    $wpTheme = wp_get_theme();
    $themeDir = $wpTheme->get_stylesheet_directory();

    // Check if the current theme is a child theme and get the parent theme directory
    $has_parent = $wpTheme->parent() ? true : false;
    $parentThemeDir = $wpTheme->parent()->get_stylesheet_directory() ?? null;

    // Scan the theme directory according to the file extensions
    foreach ($file_extensions as $extension) {
        $finder->files()->in($themeDir)->name('*.' . $extension);
        if ($has_parent) {
            $finder->files()->in($parentThemeDir)->name('*.' . $extension);
        }
    }

    // Get the file contents and send to the compiler
    foreach ($finder as $file) {
        $contents[] = [
            'name' => $file->getRelativePathname(),
            'content' => $file->getContents(),
        ];
    }

    return $contents;
}

Step 3: Generate the cached CSS file

Now that you have registered the scanner and implemented the scanner's callback function, we can now generate the final CSS file for your custom theme.

Oxygen

Learn how to use Tailwind CSS with Oxygen Builder in WordPress.

Simple File System

Learn how to use the Simple File System in WindPress.