Adds documentation for WordPress.WP.EnqueuedResources.

[NielsdeBlaauw]

Related to #1722

[jrfnl]

Hi @NielsdeBlaauw Looking good.

I've left some small remarks inline.

Aside from that, I'm wondering if it would be better for the example code to reference local files instead of external URLs, as that is (or should be) the more common use-case.

For plugins, this would be something like:
plugins_url( 'css/my-css.css', __FILE__ ),

And for themes:
get_template_directory_uri() . '/js/nav.js'

[NielsdeBlaauw]

Aside from that, I'm wondering if it would be better for the example code to reference local files instead of external URLs, as that is (or should be) the more common use-case.

I'm worried the code for the invalid example might be too far from what the user is actually doing, or what the sniff will be picking up. It's not about what resource is loaded, it is more about the way it is being done. IMHO this example is easier and more accessible to people with limited knowledge of WP. Also it avoids a discussion of where the actual resource is coming from.

[jrfnl]

Aside from that, I'm wondering if it would be better for the example code to reference local files instead of external URLs, as that is (or should be) the more common use-case.

I'm worried the code for the invalid example might be too far from what the user is actually doing, or what the sniff will be picking up. It's not about what resource is loaded, it is more about the way it is being done. IMHO this example is easier and more accessible to people with limited knowledge of WP. Also it avoids a discussion of where the actual resource is coming from.

True enough. Maybe using a $path_to_file variable would simplify it in that case ?

The reason I'm not keen to leave the examples with the URLs is two-fold and revolves around other problems which this sniff is not sniffing for:

1. People using a CDN-version of script which WP natively ships with, often at a different version than the one which ships with WP.
   This breaks other plugins/themes as those expect the WP native version and their code may break when a different version is used. Also see Extra: Sniff to check for overruling of WP included scripts #867
2. People using just a CDN-version of a script without fall-back to local.
   This can break sites pretty badly when:
   • the CDN is down;
   • the CDN stops hosting a particular script or the particular version being pointed to;
   • the pointer is to a version-less script name and the version of the script on the CDN changes.

These are issues outside the scope of the sniff, so I agree that we shouldn't address them here, but I do believe showing code which we may well forbid at a later stage, is not a good idea either.

[NielsdeBlaauw]

Agree, I'm going to replace it with a variable.

[jrfnl]

👍