アセットの登録

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

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

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

  • The asset type ('javascript' or 'css')
  • The handle we'd like to refer to this asset by ('jquery' in this case.)
  • The path or URL to the asset
  • An array of options (optional; described later, not pictured here)
  • A \Concrete\Core\Package\Package object or package handle (optional; used if the asset is found in a package, not pictured here.)

Asset Types

Concrete5 includes three asset types that can be called in register()

  • javascript for JavaScript files.
  • css for CSS style sheets.
  • javascript-inline for JavaScript that you would like to output inline into the page.

Path Details

The path specified in the register() function is relative to one of the following

  • The application/ directory
  • The packages/package_handle/ directory (if a package handle or package object is specified as part of the register() method.)
  • The concrete/ directory

These three locations are checked in this order. So, in our example, first we'll try and load jquery.js from application/js/jquery.js, then from concrete.js.

Handle Uniqueness

A handle should be unique across type and handle. This means that if you're registering an asset with the handle "mysite/calendar", you can register one CSS file and one JavaScript file with both that same handle.

Calling register()

You can register an asset from anywhere – your application's custom startup file (application/bootstrap/app.php), a package's onstart() method, a block type's onstart() method, etc…

Registering an asset in a block

Have a custom block that uses some assets? Register in your block's on_start() method (which automatically gets run when a block is embedded in a page.) Here's how a block can register the MediaElement.js JavaScript and CSS files.

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'
    );
}

Registering an asset in a package.

Registering an asset in a package is very similar – add it to the package controller's onstart() method. Let's say our package handle was "audioplayer" and we wanted to register MediaElement.js within it. Add this method to the package controller.php file:

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() options

The fourth argument of the register() function is an array of optional parameters. Here are the options, as well as their defaults if not specified.

  • position – either \Concrete\Core\Asset\Asset::ASSETPOSITIONHEADER or \Concrete\Core\Asset\Asset::ASSETPOSITIONFOOTER. If left blank, it will default to the position specified by the asset type. CSS assets are included in the header of the page, JavaScript assets in the footer.
  • local – defaults to true. If false, the exact string will be treated as a URL to a non-local asset.
  • version – defaults to false. If specified, this version will be stored against the asset as the numerical version of the asset.
  • combine – either true (combine this asset with other assets if asset caching is enabled) or false (do not combine this asset with others). Defaults to -1, which uses the default for the Asset type.
  • minify – either true (minify this asset before combining, if asset caching is enabled) or false (do not minify this asset). Defaults to -1, which uses the default for the Asset type.

Registering with Options

Let's take a look at what our Mediaelement.js register() method would look like with some more options relevant to the files:

$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