アセットの登録

アセットを呼び出す前に、concrete5にそれをどのように読み込むべきかを知らせるため、アセットを登録する必要があります。アセットの登録は短いPHPコードで可能です。jQueryをconcrete5のアセットとして登録する方法をご紹介します（注意：jQueryはconcrete5に標準で登録されているため、実際にはこのコードの記述は不要です。登録済みのアセットの一覧はこちらで確認できます）。

$al = \Concrete\Core\Asset\AssetList::getInstance();
$al->register('javascript', 'jquery', 'js/jquery.js');

まず、アセットリストクラスを呼び出します。このクラスはシングルトンですので、concrete5のどの部分からも呼び出すことができ、どこからでもアセットの追加が可能です。getInstance() を使って新しいインスタンスを生成せず、既存のインスタンスを呼び出しています。register() メソッドは３つの引数をとります。

  • アセットのタイプ( 'javascript' や 'css' など)
  • アセットを参照するためのハンドル(この場合は 'jquery' )
  • アセットへのURLまたはパス
  • オプション設定の配列(省略可能。今回の例には入っていませんが後ほど解説します)
  • \Concrete\Core\Package\Package オブジェクト、またはパッケージのハンドル(省略可能。今回の例には入っていません。アセットがパッケージの中にある場合に使います)

アセットのタイプ

concrete5の register() メソッドで指定できるアセットのタイプは4つです。

  • css CSSスタイルシートファイル
  • css-inline ページに直接出力されるCSS
  • css-localized (近日公開)
  • javascript JavaScriptファイル
  • javascript-inline ページに直接出力されるJavaScript
  • javascript-conditional (近日公開)
  • javascript-localized (近日公開)

パスについて

register() メソッドの中で指定できるパスは、以下の場所からの相対パスです。

  • application/ ディレクトリ
  • packages/package_handle/ ディレクトリ (パッケージのハンドル、またはパッケージのオブジェクトがメソッド内で指定されている場合)
  • concrete/ ディレクトリ

上から順番に、この3つの場所がチェックされます。今回の例では、まず application/js/jquery.js を読み込もうとして、それがなければ concrete/js/jquery.js を読み込もうとします。

ハンドルの一意性

アセットのハンドルは、同じタイプの他のアセットのハンドルと重複しないようにしなければなりません。これはつまり、あなたが"mysite/calendar"というハンドルでアセットを登録するとき、同じハンドルで1つのCSSファイルと1つのJavaScriptファイルを両方登録することができるということです。

register() を呼び出してアセットを登録

アセットはどこからでも登録することができます。自分のアプリケーションのカスタムスタートアップファイル(application/bootstrap/app.php)、パッケージの on_start() メソッド、ブロックタイプの on_start() メソッド、などなど…

ブロックの中でアセットを登録

アセットを必要とするカスタムブロックがあるなら、そのブロックのコントローラの on_start() メソッドの中でアセットを登録しましょう。(on_start() メソッドは、そのブロックがページの中で読み込まれたときに自動的に実行されます)

例えば以下のようにすれば、ブロックの中でMediaElement.jsライブラリの JavaScriptファイルとCSSファイルを登録することができます。

public function on_start()
{
    $al = \Concrete\Core\Asset\AssetList::getInstance();
    $al->register(
        'javascript', 'mediaelement', 'blocks/audio/mediaelement/mediaelement-and-player.min.js'
    );
    $al->register(
        'css', 'mediaelement', 'blocks/audio/mediaelement/mediaelementplayer.min.css'
    );
}

パッケージの中でアセットを登録

パッケージの中でアセットを登録するのも、ブロックの場合とほぼ同様です。仮に、私たちのパッケージのハンドルが "audio_player" で、このパッケージのなかでMediaElemant.jsライブラリを登録したいとしましょう。
このメソッドをパッケージの controller.php ファイルに追加しましょう。

public function on_start()
{
    $al = AssetList::getInstance();
    $al->register(
        'javascript', 'mediaelement', 'blocks/audio/mediaelement/mediaelement-and-player.min.js', array(), 'audio_player'
    );
    $al->register(
        'css', 'mediaelement', 'blocks/audio/mediaelement/mediaelementplayer.min.css', array(), 'audio_player'
    );
}

register() のオプション設定

register() の4つ目の引数は、オプションのパラメータを入れた配列です。以下はそのオプションと、何も指定しなかった場合のデフォルト値です。

  • position \Concrete\Core\Asset\Asset::ASSET_POSITION_HEADER (ページのヘッダー) または\Concrete\Core\Asset\Asset::ASSET_POSITION_FOOTER (ページのフッター) のどちらかが入ります。 何も指定していない場合、そのアセットのタイプによって自動で決まります。CSSのアセットはページのヘッダーに、JavaScriptのアセットはページのフッターに挿入されます。
  • local デフォルトは true です。falseが指定された場合、指定されたパスの文字列は外部のアセットファイルへのURLとして扱われます。
  • version デフォルトは false です。数値が指定された場合、その数値がこのアセットのバージョンとして記録されます。
  • combine true (アセットのキャッシュが有効な場合、このアセットを他のアセットと結合する) か false (このアセットを他のアセットと結合しない)のどちらかが指定できます。デフォルトは -1 で、そのアセットタイプのデフォルト指定を使用することを意味します。
  • minify true (アセットのキャッシュが有効な場合、このアセットを結合する前にminify(圧縮)する) か false (このアセットをminifyしない) のどちらかが指定できます。デフォルトは -1 で、そのアセットタイプのデフォルト指定を使用することを意味します。

オプション設定をつけて登録する

MediaElement.js ライブラリを register() メソッドで登録する際に、オプション設定をつけて登録するなら、このようになります。

$al->register(
    'javascript', 'mediaelement', 'blocks/audio/mediaelement/mediaelement-and-player.min.js',
    array('version' => '2.16.3', 'minify' => false, 'combine' => true)
);
$al->register(
    'css', 'mediaelement', 'blocks/audio/mediaelement/mediaelementplayer.min.css',
    array('version' => '2.16.3', 'minify' => false, 'combine' => true)
);

原文：Registering an Asset