[4.0][RFC] Elephant can manage assets also. The WebAssetRegistry class to manage assets and it`s dependacies

[Fedik]

Pull Request for Issue #12402, improved version of #8913 .

Summary of Changes

The patch introduce new class WebAssetRegistry to manage the assets, and it's dependencies.
The assets - > read as CSS/JS library.

How it works

All registry information stored in a registry file, a simple json file called joomla.asset.json.
I made an example for media/vendor/joomla.asset.json, media/system/joomla.asset.json, and for each template atum/joomla.asset.json, cassiopeia/joomla.asset.json.

The Registry file are for:

• The registry file contain an information about provided assets.
• Each asset provide dependencies, and js/css files which be attached to the Document on header rendering event.
• Each asset can be overridden by another registry file (take a look in atum/joomla.asset.json where overridden bootstrap.css, and font-awesome).

To add your registry file:

Factory::getContainer()->get('webasset')
  ->addRegistryFile('media/blabla/path/joomla.asset.json')

How to use, enable/disable assets:

/** @var Joomla\CMS\WebAsset\WebAssetRegistry $wa */
$wa = Factory::getContainer()->get('webasset');

// Enable Core asset
$wa->enableAsset('core');
// If the asset do not exists, then Exception will be thrown

// Disable Bootstrap CSS
$wa->disableAsset('bootstrap.css'); 
// bootstrap.css - is an asset name, not a file name !!!
// look in media/vendor/joomla.asset.json to see why

NOTE: Method enableAsset() / disableAsset() do NOT add anything to the document. It just change the asset state. The files of all active assets will be attached to the Document on before header rendering.

By default WebAssetRegistry use a "lazy loading" of assets.
The registry file parsed only when WebAssetRegistry requested for new asset.
All dependencies will be resolved while attaching WebAssetRegistry to the document. See WebAssetRegistry::attach()

Also I have made an example in behavior.core, bootstrap.framework.

Further changes/ideas

Allow custom class per asset, that can handle stuff like in 'behavior.core':

function onBeforeAtach() {
  $doc->addScriptOptions('system.paths', [
	'root' => Uri::root(true),
	'rootFull' => Uri::root(),
	'base' => Uri::base(true),
  ]);
}

In theory, this allow to clean up JHtml from adding a scripts.

For now feedback are welcome!

Documentation Changes Required

yes, if it will be accepted

ping @wilsonge @mbabker @dgrammatiko @C-Lodder @laoneo
also everyone else who doing frondend stuff

[dgrammatiko]

you aren't working in an environment where all the paths are going to be static

require.js can handle this in the same manner script tags are appended in the html.

talking down on the project because it doesn't push for a compiled build environment

You got me wrong, all I said was that you should try to ease the path for modules (by forcing defer) not actually implement it right now (yes till dynamic imports are supported everywhere there's no point even trying to do it)

[Fedik]

The problem is you are in an environment where there is an end user facing feature for runtime resolution of assets that enables end users to create overrides.

After some tweaks WebAssetRegistry allow to generate a config for require.js, which can be used as script/module loader.

but all this not in current PR

[Fedik]

@mbabker Here another example about what is doing enable/disable and add/remove methods:

// Empty asset registry
$wa = new WebAssetRegistry;

// Add some assets
$wa->addAsset(new WebAssetItem("🍻"));
$wa->addAsset(new WebAssetItem("🐘"));

// At this point we have 2 asset in registry, with STATE_INACTIVE
// So nothing will be added to Document
$wa->attachActiveAssetsToDocument($document); // Will do nothing, because all assets is inactive

// Enable asset
$wa->enableAsset("🐘");

// At this ponit we still have 2 assets, but only 1 is Active
$wa->attachActiveAssetsToDocument($document); // Will add files from "🐘" asset to Document

// Try to enable not-existing asset
$wa->enableAsset("🐛"); // Will throw Exception

And use of RegistryFile just doing addAsset() for you, all you need is just enable/disable existing.
Of course you still can do $wa->addAsset(new WebAssetItem("🍪"))->enableAsset("🍪"), if need.

[wilsonge]

Let's take this as a first pass. I'm pretty sure there's some improvements to be made here - but I'm happy with this as the base concept

[Fedik]

oh, that was fast 😄

for note, one issue left:

@mbabker : If I enable an asset with dependencies I expect the dependencies to be enabled as well.

This might be a case of trying to be too lazy. It's fine to defer parsing the JSON files until you actually start adding WebAssetItem entries to the internal store, but once you start populating WebAssetRegistry::$assets with objects it should always contain the full resource tree. It really shouldn't be a partial snapshot.

I think it is pretty important.
I will try to fix it, in one of next pull request.

[wilsonge]

I've started working on docs for this feature https://docs.joomla.org/J4.x:Web_Assets Any help is always appreciated!