[4.0] Joomla.asset.json

[brianteeman]

1. If you use the copy template feature for the cassiopeia template all the references to cassiopeia in the joomla.asset.json file are maintained.

• Does that matter?
• Shouldnt they be renamed to the same value as the one you input when you copy the template?

2. Is there any documentation explaining how to use this file? What its purpose is etc etc. All I can find is https://docs.joomla.org/J4.x:Web_Assets which is way over my head. From what I have been able to deduce there are various joomla.asset.json all of which are loaded before the one for the template. So I am guessing that anything in the template joomla.asset.json file is either specific to that template and/or an override for the previous files.

I found a bit more information in the json-schema https://developer.joomla.org/schemas/json-schema/web_assets.json

If its technically possible to add comments to the joomla.asset.json file then it would be really helpful for anyone looking at cassiopeia as an example to build their new template with.

PS so far building a new site in j4 with bs5 has been a dream and lighthouse loves it. 99/100/100/100

[dgrammatiko]

If you use the copy template feature for the cassiopeia template all the references to cassiopeia in the joomla.asset.json file are maintained.

That should be fine, we only have to move the cassiopeia and atum to the new template mode (the one that supports child templates). I have to finish the work here #30359 In case that the templates finally ship with the legacy mode and someone forks the template then the file joomla.asset.json needs to be adjusted

PS so far building a new site in j4 with bs5 has been a dream and lighthouse loves it. 99/100/100/100

you can get 100 across the board with #32141 😉

[Fedik]

Does that matter?

Yes, much matter. Because it used by the "template", in various layouts:

joomla-cms/templates/cassiopeia/index.php

Lines 56 to 62 in c0a7b03

	// Enable assets
	$wa->usePreset('template.cassiopeia.' . ($this->direction === 'rtl' ? 'rtl' : 'ltr'))
	->useStyle('template.active.language')
	->useStyle('template.user')
	->useScript('template.user');

joomla-cms/templates/cassiopeia/error.php

Lines 55 to 60 in c0a7b03

	// Enable assets
	$wa->usePreset('template.cassiopeia.' . ($this->direction === 'rtl' ? 'rtl' : 'ltr'))
	->useStyle('template.active.language')
	->useStyle('template.user')
	->useScript('template.user');

etc.

Shouldnt they be renamed to the same value as the one you input when you copy the template?

No, because it will break the template.
However, if you like, you can rename it manually with all entries in the template files.

Is there any documentation explaining how to use this file?
All I can find is https://docs.joomla.org/J4.x:Web_Assets

Yes, you found correct, it is documentation 😄
Well, if you have an idea how it can be explained more understandable, that would be nice. Me and @wilsonge wrote all what we can 😄
(Perhaps there need some update about recent changes, but in general it is not much related to your question.)

[brianteeman]

Shouldnt they be renamed to the same value as the one you input when you copy the template?

No, because it will break the template.
However, if you like, you can rename it manually with all entries in the template files.

I dont follow you on this. I create a copy of cassiopeia and give it the name "starter". The templateDetails.xml is updated to say "starter" and the folder is called "starter". So why cant we update the assets.json file that is copied into the new template as well and instead have to manually update it.

Well, if you have an idea how it can be explained more understandable, that would be nice. Me and @wilsonge wrote all what we can 😄

It is very developer focused and not friendly to someone at my skill level. If you look at configuration.php-dist various lines are documented which is a start

joomla-cms/installation/configuration.php-dist

Lines 64 to 68 in c0a7b03

	public $ftp_enable = false;
	public $tmp_path = '/tmp'; // This path needs to be writable by Joomla!
	public $log_path = '/administrator/logs'; // This path needs to be writable by Joomla!
	public $live_site = ''; // Optional, full URL to Joomla install.
	public $force_ssl = 0; // Force areas of the site to be SSL ONLY. 0 = None, 1 = Administrator, 2 = Both Site and Administrator

I have worked out what some of the entries are supposed to be and changed accordingly. But others I dont have a clue what they mean.

joomla-cms/templates/cassiopeia/joomla.asset.json

Lines 30 to 36 in c0a7b03

	"name": "template.active.language",
	"type": "style",
	"uri": "",
	"class": "LangActiveAssetItem",
	"dependencies": [
	"template.active"
	]

[Fedik]

I dont follow you on this. I create a copy of cassiopeia and give it the name "starter".

Look at the code I have shown previously, where it used in the template. Example index.php :

joomla-cms/templates/cassiopeia/index.php

Lines 56 to 62 in c0a7b03

	// Enable assets
	$wa->usePreset('template.cassiopeia.' . ($this->direction === 'rtl' ? 'rtl' : 'ltr'))
	->useStyle('template.active.language')
	->useStyle('template.user')
	->useScript('template.user');

You cannot rename only in json. You need to rename all usages.
For test: try to rename in json manually in your copy, and will see what will happen.

But others I dont have a clue what they mean.

template.active.language load the css provided with the language (if there any)
template.user load user.css (style) and user.js (script)

It is very developer focused and not friendly to someone at my skill level.

Yeah. I think would be nice to add some extra explanation to the documentation for the "template how to" (if there any) with cross reference to Web_Assets.

If its technically possible to add comments to the joomla.asset.json

Yes it possible with description property, like it done for template.active asset

joomla-cms/build/media_source/system/joomla.asset.json

Lines 26 to 31 in c0a7b03

	{
	"name": "template.active",
	"type": "style",
	"uri": "",
	"description": "A dummy asset to allow to extensions to use it as dependency to active template"
	},

[brianteeman]

You cannot rename only in json. You need to rename all usages.

We can/should rename in all places - otherwise you can end up with someone uninstalling the original template as they think its not in use and it breaks the copied template which was in use

I have made a first draft at adding descriptions to the json file #32411

Yeah. I think would be nice to add some extra explanation to the documentation for the "template how to" (if there any) with cross reference to Web_Assets.

That is what I am really missing

[Fedik]

We can/should rename in all places - otherwise you can end up with someone uninstalling the original template

No, we should not. It does not break if someone uninstalling the original template.
Because all assets copied also, and now they part of copied template.

templates/cassiopeia/joomla.asset.json refers to files within cassiopeia template
templates/cassiopeia_copy/joomla.asset.json refers to files within cassiopeia_copy template (even if there same names), previous file is ignored here.

Example an asset template.cassiopeia.ltr will look for template.min.css for active template. It would break, if URI was hardcoded to templates/old_template/template.min.css (It the same behavior as JHtml::_('script', 'template.min.css'))

joomla-cms/templates/cassiopeia/joomla.asset.json

Lines 8 to 12 in 421c3a1

	{
	"name": "template.cassiopeia.ltr",
	"type": "style",
	"uri": "template.min.css",
	"dependencies": [

joomla.asset.json files of the template loaded only for active template, other templates is ignored.

Check screen form the docs:

That means only system, vendor, legacy joomla.asset.json always loaded. But component and template joomla.asset.json only per active component and template.

[brianteeman]

I give up. I can't get bootstrap js loading in my custom template. Looking at cassiopeia as an example I cant see anything there that is loading bs. What am I missing

[brianteeman]

Simple case using just the default menu and the dropdown mobile menu isnt opening on my template

This is the same site just different templates
cassiopeia is showing this

mytemplate is showing this

[dgrammatiko]

Check

joomla-cms/administrator/templates/atum/index.php

Line 129 in 46216f8

<?php HTMLHelper::_('bootstrap.collapse', '.toggler-burger'); ?>

This line tells Joomla to load the collapse component and initialise it for the '.toggler-burger' Css selector.
Also

joomla-cms/administrator/modules/mod_user/tmpl/default.php

Line 19 in 46216f8

HTMLHelper::_('bootstrap.dropdown', '.dropdown-toggle');

is instructing Joomla to load the dropdown and initialise it for the '.dropdown-toggle' Css selector

[brianteeman]

Thanks for the hint.

Cassiopeia has this line in the template and I didnt

joomla-cms/templates/cassiopeia/index.php

Line 132 in 46216f8

<?php HTMLHelper::_('bootstrap.collapse', '.navbar-toggler'); ?>

[brianteeman]

I was so busy looking at the head and the assets I forgot to look in the body

[dgrammatiko]

I hope someone will pick up the Bootstrap demo component https://github.com/dgrammatiko/bs5/tree/main/test_component and polish it with proper documentation. It will be an invaluable help for newcomers

[brianteeman]

When you register an asset in your template joomla.asset.json there is a URI for each asset
But how does it know where these files live in the filesystem?

joomla-cms/templates/cassiopeia/joomla.asset.json

Line 12 in 7c42442

"uri": "template.min.css",

joomla-cms/templates/cassiopeia/joomla.asset.json

Line 56 in 7c42442

"uri": "template.js",

In other words if i want to add a new asset to my json where do I put the files in the template folder structure. I didnt see anything in the docs for this

[level420]

@brianteeman I could not completely follow all hints in this thread, but also like to load additional js files within my template which is a child template of cassiopeia called cassiopeia_mysite.

I've created a joomla.asset.json file in the directory template/cassiopeia_mysite file with the following content:

{
  "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
  "name": "cassiopeia_mysite",
  "version": "4.0.0",
  "description": "an additional js file which should be loaded",
  "license": "GPL-2.0-or-later",
  "assets": [
    {
      "name": "template.test",
      "description": "The name of a file where a user can add their own javascript",
      "type": "script",
      "uri":  "media/templates/site/cassiopeia_mysite/js/test.js"
    }
  ]
}

and of course the file test.js in media/templates/site/cassiopeia_mysite/js.

And honestly I don't know from the discussion if this should work or not, but it doesn't.

[dgrammatiko]

but it doesn't.

It's expected if your joomla.asset.json looks like what you posted above. The explanation is that child templates inherit functionality from the parent template as is unless there is an override then they completely disregard the parent and use the local functionality in the child template. So, basically what it happens in the case of joomla.asset.json is:

• if the child template doesn't have the file joomla.asset.json the parent template's one is used
• if there is a file joomla.asset.json then that file should resolve ALL the static assets, there is no merging functionality.

In short, if you want to use a file joomla.asset.json in a child template you have to redefine all the assets (most will have to point to the parent template using absolute paths, your extra entries could be relative to the child assuming the files are also under the child media place). I hope this is easy to follow

[level420]

@dgrammatiko thank you for your answer.

But in the setup which I've described above, it seems that the childs joomla.asset.json is ignored, as all assets which are defined in the parents template/cassiopeia/joomla.asset.json file still get loaded.

Anyway: if the assets defined in the child template do not get additionally loaded, this scenario is useless for me.

What I really need is a simple way to load additional javascript in a child template besides user.js. I'm not finding a general hook where I can do that, as all php overrides are specific to a layout, component, module etc. and therefore are only involved where those overrides are used. I'll need to load the additional files everywhere on the website.

[level420]

BTW.: I'm on Joomla 4.4.1

[Fedik]

In template/foo-bar//joomla.asset.json you defining template assets, they not loaded automaticlay.
They need to be enabled when needed in your template with $wa->useScript('template.test').

Here is an example form Cassiopeia index.php, how it enable own assets:

joomla-cms/templates/cassiopeia/index.php

Lines 56 to 62 in c0a7b03

	// Enable assets
	$wa->usePreset('template.cassiopeia.' . ($this->direction === 'rtl' ? 'rtl' : 'ltr'))
	->useStyle('template.active.language')
	->useStyle('template.user')
	->useScript('template.user');

You can find more on Doc page https://docs.joomla.org/J4.x:Web_Assets