J4.x

Assets Web

From Joomla! Documentation

This page is a translated version of the page J4.x:Web Assets and the translation is 5% complete.

Other languages:
Deutsch • ‎English • ‎français • ‎italiano

Concept

In the frontend world many assets are related. For example our keepalive script depends on the core.js file for options management. In Joomla there never was an easy way to specify this, you just had to include multiple files. Joomla 4 changes this with the concept of web assets.

Définition

Related assets are defined in a JSON file such as system/joomla.asset.json#L14-L21

This has a structure of having a schema definition (for validation), name, version, license and then one or more asset definitions. Assets are comprised of a list of js files and css files related to the assets and any dependencies. The dependencies section is just a list of asset names that are required for the asset to function. Example:

{
  "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
  "name": "com_example",
  "version": "4.0.0",
  "description": "Joomla CMS",
  "license": "GPL-2.0+",
  "assets": [
    {
      "name": "bar",
      "type": "style",
      "uri": "com_example/bar.css"
    },
    {
      "name": "bar",
      "type": "script",
      "uri": "com_example/bar.js"
    },
    {
      "name": "beer",
      "type": "style",
      "uri": "com_example/beer.css",
      "dependencies": [
        "bar"
      ],
    },
    {
      "name": "beer",
      "type": "script",
      "dependencies": [
        "core",
        "bar"
      ],
      "uri": "com_example/beer.js",
      "attribute": {
        "defer": true,
        "data-foo": "bar"
      }
    }
  ]
}

The $schema attribute is a schema definition file that allows you to validate your file using JSON Schema. Read [the official website](https://json-schema.org/understanding-json-schema/index.html) for more information on json schema validation works.

Note: Having joomla.asset.json for your extension or template are recommend but not required to WebAssset to work (see next section).

Register an asset

All known assets loaded and then stored in WebAssetRegistry (to enable/disable an asset item you have to use WebAssetManager, see next section).

Joomla! will look for next assets definition automatically at runtime (in following order):

media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.json

And load them to registry of known assets.

Note: Each following assets definition will override asset items from previous assets definition, by item name.


You can register your own assets definition via WebAssetRegistry:

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr->addRegistryFile('relative/path/to/your/joomla.asset.json');

To add a custom asset item at runtime:

$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));

Or more simply, using WebAssetManager:

$wa->registerScript('foobar', 'com_foobar/file.js');

The new asset item foobar will be added to the registry of know assets, but will not be attached to a document until your code (a layout, template etc) will request it.

To check whether an asset exists:

if ($wa->assetExists('script', 'foobar'))
{
    var_dump('Script "foobar" exists!');
}


Activer un asset

All asset management in the current Document handled by WebAssetManager, which is accessible with $doc->getWebAssetManager(); By using AssetManager you can enable or disable needed asset easily in Joomla! through a standard methods.

To enable an asset in the page use the useAsset function, for example:

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');

// Or multiple
$wa->useScript('keepalive')
    ->useScript('fields.validate')
    ->useStyle('foobar')
    ->useScript('foobar');

// Add new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);

WebAssetManager will look to WebAssetRegistry whether the requested asset exists, and will enable it for current Document instance. Otherwise it will throw an UnknownAssetException.

To disable an asset in the page use the disableAsset function. The example below will disable the jquery-noconflict asset from being loaded.

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->disableScript('jquery-noconflict');

Note: If there are any dependencies to the disabled asset, then this asset will be re-enabled automatically, no matter what.

To check whether asset enabled, and the asset state:

// Checking whether an asset are active (enabled manually or automatically as dependency)
if ($wa->isAssetActive('script', 'foobar'))
{
    var_dump('Script "foobar" are active!');
}

// Checking state
switch($wa->getAssetState('script', 'foobar')){
	case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
		var_dump('Active! Was enabled manually');
		break;
	case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
		var_dump('Active! Was enabled automatically while resolving dependencies');
		break;
	default:
		var_dump('not active!');
}


Overriding an asset

Overriding may be useful when you need to redefine the URI of asset item or its dependencies.

As already was noted, each of the following assets definition from joomla.asset.json will override asset items from previous assets definitions, by item name.

That means if you provide joomla.asset.json which contain already loaded asset items, they will be replaced with your items.

Another way to override in the code is to register an item with the same name.

Example, we have "foobar" script, that load com_example/foobar.js library, and we want to use CDN for this exact library:

How it defined in the system initially:

...
{
  "name": "foobar",
  "type": "script",
  "uri": "com_example/foobar.js",
  "dependencies": ["core"]
}
...

To override the URI we define the asset item with "foobar" name in our joomla.asset.json:

...
{
  "name": "foobar",
  "type": "script",
  "uri": "http://foobar.cdn.blabla/foobar.js",
  "dependencies": ["core"]
}
...

Or, register new asset item with AssetManager:

$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);

Working with a styles

AssetManager allow to manage Stylesheet files. Stylesheet asset item have a type "style".

Example json defination of item in joomla.asset.json:

...
{
  "name": "foobar",
  "type": "style",
  "uri": "com_example/foobar.css"
}
...

Methods to work with styles

AssetManager offer next methods to work with style files:

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useStyle('foobar');

// Disable foobar from being attached
$wa->disableStyle('foobar');

// Register custom item without json defination
$wa->registerStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
// And use it later
$wa->useStyle('bar');

// Register and attach a custom item in one run
$wa->registerAndUseStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);


Working with a scripts

AssetManager allow to manage Script files. Script asset item have a type "script".

Example json defination of item in joomla.asset.json:

...
{
  "name": "foobar",
  "type": "script",
  "uri": "com_example/foobar.js",
  "dependencies": ["core"]
}
...

Methods to work with scripts

AssetManager offer next methods to work with script files:

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useScript('foobar');

// Disable foobar from being attached
$wa->disableScript('foobar');

// Register custom item without json defination
$wa->registerScript('bar', 'com_example/bar.js', [], ['defer' => true], ['core']);
// And use it later
$wa->useScript('bar');

// Register and attach a custom item in one run
$wa->registerAndUseScript('bar','com_example/bar.js', [], ['defer' => true], ['core']);

Working with a web component

Joomla! allows you to use Web Components (https://developer.mozilla.org/en-US/docs/Web/Web_Components) for your needs. In Joomla! web components are not loaded as regular script, but loaded via Web Component loader so that they are loaded asynchronously. Therefore, a web component asset item must have a flag "webcomponent" set to the boolean "true". In all other aspects, working with web components in AssetManager is the same as working with a "script" asset item.

Example json definition of some web components in joomla.asset.json:

...
{
  "name": "webcomponent.foobar",
  "type": "style",
  "uri": "com_example/foobar-custom-element.css",
  "webcomponent": true
},
{
  "name": "webcomponent.foobar",
  "type": "script",
  "uri": "com_example/foobar-custom-element.js",
  "webcomponent": true
}
...

Alternatively you can register them in PHP:

$wa->registerStyle('webcomponent.foobar', 'com_example/foobar-custom-element.css', ['webcomponent' => true])
    ->registerScript('webcomponent.foobar', 'com_example/foobar-custom-element.js', ['webcomponent' => true]);

Attach to document:

$wa->useStyle('webcomponent.foobar')
    ->useScript('webcomponent.foobar');

Note: It is preferred to prefix the asset name with "webcomponent." to make it easily to spot, and distinct it from regular scripts in a layout.

Methods to work with web component

All methods to work with a web component are the same as methods to work with script asset item.

Working with a presets

"Preset" is a special kind of asset item that hold a list of items that has to be enabled, in same way as direct call of useAsset() to each of item in the list. Preset can hold mixed types of assets (script, style, another preset, etc), the type should be provided after # symbol and follows after an asset name, example: foo#style, bar#script.

Example json defination of item in joomla.asset.json:

...
{
  "name": "foobar",
  "type": "preset",
  "uri": "",
  "dependencies": [
    "core#script",
    "foobar#style",
    "foobar#script",
  ]
}
...

Methods to work with preset

AssetManager offer next methods to work with preset items:

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach all items from foobar preset to the document
$wa->usePreset('foobar');

// Disable all items from foobar preset from being attached
$wa->disablePreset('foobar');

// Register custom item without json defination
$wa->registerPreset('bar', '', [], [], ['core#script', 'bar#script']);
// And use it later
$wa->usePreset('bar');

// Register and attach a custom item in one run
$wa->registerAndUsePreset('bar','', [], [], ['core#script', 'bar#script']);

Advanced: Custom WebAssetItem class

The default class for all WebAsset items is Joomla\CMS\WebAsset\WebAssetItem.

You are also allowed to use a custom class, which must implement Joomla\CMS\WebAsset\WebAssetItemInterface or extend Joomla\CMS\WebAsset\WebAssetItem.

A custom class can allow you to do advanced actions, for example, including a script file depending on an active language:

class MyComExampleAssetItem extends WebAssetItem
{
	public function getUri($resolvePath = true): string
	{
		$langTag = Factory::getApplication()->getLanguage()->getTag();
		// For script asset use ".js", for style we would use ".css"
		$path    = 'com_example/bar-' . $langTag . '.js';

		if ($resolvePath)
		{
			// For script asset use "script", for style we would use "stylesheet"
			$path = $this->resolvePath($path, 'script');
		}

		return $path;
	}
}

Additionally, implementing Joomla\CMS\WebAsset\WebAssetAttachBehaviorInterface allows you to add a script options (which may depend on the environment) when your asset is enabled and attached to the Document.

class MyFancyFoobarAssetItem extends WebAssetItem implements WebAssetAttachBehaviorInterface
{
	public function onAttachCallback(Document $doc): void
	{
		$user = Factory::getApplication()->getIdentity();
		$doc->addScriptOptions('com_example.fancyfoobar', ['userName' => $user->username]);
	}
}

Defining a custom WebAssetItem class in joomla.asset.json

In joomla.asset.json you can define which Class should be used with specific AssetItem. For this you can use 2 properties namespace and class. namespace can be defined at Root level (then it will be used as default namespace for all Asset items in joomla.asset.json) or in the Item level. For example:

{
  "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
  "name": "com_example",
  "version": "4.0.0",
  "namespace": "Joomla\Component\Example\WebAsset",
  "assets": [
    {
      "name": "foo",
      "type": "script",
      "class": "FooAssetItem",
      "uri": "com_example/foo.js"
    },
    {
      "name": "bar",
      "type": "script",
      "namespace": "MyFooBar\Library\Example\WebAsset",
      "class": "BarAssetItem",
      "uri": "com_example/bar.js"
    }
  ]
}

Here the asset foo will be associated with class Joomla\Component\Example\WebAsset\FooAssetItem, and bar with class MyFooBar\Library\Example\WebAsset\BarAssetItem.

Note: If namespace are not defined then by default will be used Joomla\CMS\WebAsset. When namespace is defined but empty, then no namespace will be used, only class. Example:

{
  "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
  "name": "com_example",
  "assets": [
    {
      "name": "foo",
      "type": "script",
      "class": "FooAssetItem",
      "uri": "com_example/foo.js"
    },
    {
      "name": "bar",
      "type": "script",
      "namespace": "",
      "class": "BarAssetItem",
      "uri": "com_example/bar.js"
    }
  ]
}

Here the asset foo will be associated with class Joomla\CMS\WebAsset\FooAssetItem, and bar with class BarAssetItem (without namespace).