実務で活かすSWELL子テーマのカスタマイズ手法

SWELL子テーマのアーキテクチャとファイル構成

WordPressテーマ「SWELL」は、ブロックエディタ（Gutenberg）への完全対応と、独自のキャッシュ機能や非同期読み込み機能を備えた非常に高度なアーキテクチャを持っています。一般的なWordPressテーマ開発の経験があるエンジニアであっても、SWELL特有のファイル構成や処理の流れを理解せずにカスタマイズを行うと、テーマのアップデート時に不具合を起こすリスクが高まります。

実務においてSWELLのカスタマイズ案件を扱う場合、親テーマ（swell）のファイルを直接編集することは厳禁であり、必ず子テーマ（swell_child）を利用して差分のみを上書き、または追加していくアプローチをとります。

以下の表は、SWELL子テーマ開発において頻繁に操作する主要ファイルとその役割を整理したものです。

SWELLは保守性を高めるため、UIパーツを細かいテンプレートファイルとして分割しています。WordPressの標準的なテンプレート階層（single.phpやpage.php）による上書きも可能ですが、保守性の観点からは細分化されたパーツ単位でのアプローチが推奨されます。

テーマの読み込み優先順位と、SWELLにおけるオーバーライドの仕組みは以下の図の通りです。

functions.phpを活用した安全な機能拡張

エンジニアがSWELLのカスタマイズを行う際、最も腕の見せ所となるのがfunctions.phpの設計です。テンプレートファイルを無闇に上書きすると、親テーマのアップデート時にDOM構造の変更や新機能の追加に追従できなくなり、表示崩れやエラーの原因となります。これを防ぐため、可能な限りWordPressのアクションフックおよびフィルターフックを利用します。

アセット（CSS/JavaScript）の適切な読み込み制御

SWELLはパフォーマンス最適化のため、独自の非同期読み込み設定を持っています。子テーマで独自のJavaScriptやライブラリを追加する場合、標準のwp_enqueue_scriptsフックを使用しますが、依存関係や読み込みタイミング（defer属性の付与など）を正確に制御する必要があります。

/**
 * 子テーマ独自のCSSとJavaScriptを読み込む
 */
add_action('wp_enqueue_scripts', 'my_swell_child_enqueue_assets', 20);
function my_swell_child_enqueue_assets() {
    $theme_version = wp_get_theme()->get('Version');
    $child_dir_uri = get_stylesheet_directory_uri();

    // カスタムCSSの読み込み (SWELL親テーマのCSSより後に読み込ませるため優先度を下げる/依存関係を設定)
    wp_enqueue_style(
        'swell-child-custom-style',
        $child_dir_uri . '/assets/css/custom.css',
        ['swell_style'], // 親テーマのスタイルシートハンドル名を指定
        $theme_version
    );

    // カスタムJavaScriptの読み込み
    wp_enqueue_script(
        'swell-child-custom-script',
        $child_dir_uri . '/assets/js/custom.js',
        ['jquery'], // 依存関係
        $theme_version,
        true // フッターで読み込む
    );
}

上記のコードで重要なポイントは、第3引数の依存関係配列です。SWELLが出力するメインのCSSハンドル（swell_styleなど）の後に確実に読み込ませることで、CSSの詳細度で負けてスタイルが適用されないという事態を防ぎます。

SWELL独自のフックとWordPress標準フックの併用

SWELLは、記事の出力前後や特定のパーツの前後に対して、独自のフックをいくつか用意しています。しかし、全てがドキュメント化されているわけではないため、実務では親テーマ内のapply_filters()やdo_action()を直接検索して、介入可能なポイントを特定するスキルが求められます。

例えば、記事コンテンツの末尾に共通の独自コンポーネント（APIから取得したデータなど）を動的に挿入したい場合、テンプレートを上書きするのではなく、the_contentフィルターを使用するのが最も安全です。

PHP

add_filter('the_content', 'my_custom_content_appender');
function my_custom_content_appender($content) {
    // 単一記事ページでのみ実行
    if (is_single() && in_the_loop() && is_main_query()) {
        $custom_html = '<div class="my-custom-box">独自の追加コンテンツ</div>';
        return $content . $custom_html;
    }
    return $content;
}

テンプレートファイルの上書きとパーツ化

フックだけでは対応できない大規模なレイアウト変更や、既存のDOM構造自体を書き換える必要がある場合は、テンプレートファイルの上書きを行います。

テンプレート上書きの基本ルールとリスク管理

子テーマで親テーマのテンプレートを上書きするには、親テーマと全く同じディレクトリ構造とファイル名で子テーマ内にファイルを配置します。例えば、ヘッダーの構造を変更したい場合は、親テーマの /parts/header/header_contents.php を、子テーマの /parts/header/header_contents.php にコピーしてから編集します。

ただし、上書きするファイルは最小限に留めるのが鉄則です。SWELLは高頻度でアップデートが行われ、SEO対策や構造化データの出力ロジックがテンプレート内に含まれていることがあります。ファイルを丸ごと上書きしてしまうと、これらの恩恵を受けられなくなります。

新規テンプレートパーツの作成と呼び出し

特定の固定ページや、独自に追加したカスタム投稿タイプ向けに、全く新しいレイアウトを適用したい場合は、無理に既存のテンプレートを上書きせず、専用のテンプレートを新規作成します。

WordPressのテンプレート階層に従い、single-{post_type}.phpやpage-{slug}.phpを作成し、その中でget_template_part()を使用して保守性の高いコードを記述します。

<?php
/**
 * カスタム投稿タイプ 'works' 用のシングルテンプレート
 */
if (!defined('ABSPATH')) exit;
get_header();
?>

<main id="main_content" class="l-mainContent l-article">
    <div class="l-mainContent__inner">
        <?php
        while (have_posts()) :
            the_post();
            
            // 独自のテンプレートパーツを読み込む
            get_template_part('parts/custom/works', 'header');
            get_template_part('parts/custom/works', 'content');
            
        endwhile;
        ?>
    </div>
</main>

<?php get_footer(); ?>

このように、SWELLの基盤となるラッパークラス（l-mainContentなど）は維持しつつ、内部のコンポーネントを独自のパーツに切り出すことで、テーマの基本スタイルを壊さずに柔軟な開発が可能になります。