joomla/joomla-cms — pull request #2730 by chrisdavenport (2013-12-26 10:02:34+00:00)
Title: New jdoc syntax for extended asset handling.

A frequent problem encountered while building websites with Joomla is that JavaScript or CSS assets may be subject to various constraints that are not supported “out-of-the-box”. For example, certain assets may need to be loaded in a specific order, or not necessarily in the head, or internal and external assets need to be inter-mixed, and so on. Some third-party extensions attempt to address some of these issues, perhaps by hanging a plugin on the onBeforeCompileHead event, or by parsing and amending the full page output of Joomla before final delivery to the browser.

The approach detailed here is slightly different in that it extends the jdoc:include syntax with four new types. This approach has been taken because it supports a relatively straightforward syntax that should be usable by those with little or no PHP knowledge, whilst providing a great deal of flexibility and maintaining full backwards compatibility. It puts the site builder fully in control of all JavaScript and CSS that is loaded, regardless of which extensions loaded it, as long as they all used the Joomla API correctly to do it. Since this is based on a new set of document renderers all existing templates are completely unaffected. It is entirely “opt-in”; nothing changes until you start using the new jdoc:include tags.

The JHtml script and stylesheet support already provides a great deal of support for a variety of options such as serving minified versions, browser-specific versions and so on. However, it seems that many, perhaps most, extensions don't use this method. The code proposed here does not replace this capability but complements the current API support by giving control over asset loading to the template and hence to the site builder rather than the extension developer.

### Features
* Handles both internal and external scripts.
* By default all JavaScript assets are rendered at the bottom, but you can easily specify which must be rendered in the head instead.
* Each asset is given an id (which can be overridden if required) which can be used to specify dependencies between assets. All assets are rendered in dependency order (except that all JavaScript is rendered before all CSS in the head).
* Assets of any type can depend on assets of any other type in any combination.
* Only the template needs to be modified to make use of this new system. No components, modules or plug-ins need to be altered.
* Supports delivery of assets from an alternative source, such as a CDN where available.
* Assets you don’t want loaded can be stopped from loading.
* Supports the “defer” and “async” attributes for JavaScript if required.
* Supports the “media” attribute for CSS if required.
* Supports MS IE conditional comments.

Initial documentation is available with commenting available here: https://docs.google.com/document/d/15Kf1ZgRirNYZWm3eg-UTGnBW8QChDkbfEVPnHj_kayI/edit?usp=sharing