Site Essentials for Statamic

Site Essentials for Statamic

Front-end Asset Queues

Site Essentials for Statamic provides a simple, yet powerful asset management queue system to help manage various style and script assets that are not included in the site's main builds. For example, in a page builder setup, we might want to include a JavaScript file to enable some particular interaction that is not applicable to all pages.

Historically, we would use a section to achieve this:

1{{# Somewhere, possibly in the layout. #}}
2{{ yield:scripts /}}
4{{# Somewhere else, like a page builder loop. #}}
5{{ push:scripts }}
6 <script src="//my/awesome/file.js" defer></script>
7{{ /push:scripts }}

This approach can work, but on sufficiently large/complicated designs it can quickly become tedious, especially if we need to remove duplicate script references, etc. It is the latter scenario where the Site Essentials asset queue really shines.

The asset queue system is designed to be used with two types of content: scripts and styles. Like the yield tag, we need to output our queued contents somewhere. For example, if we wanted to output our dynamic styles and scripts at once we could use the following:

1<!doctype html>
2<html lang="en">
3 <head>
4 {{ se_asset_queue queue="styles|scripts" /}}
5 </head>

If we wanted to output our styles in the header of our document, but move the scripts to before the closing body tag, we could instead use:

1<!doctype html>
2<html lang="en">
3 <head>
4 {{ se_asset_queue queue="styles" /}}
5 </head>
6 <body>
8 {{ se_asset_queue queue="scripts" /}}
9 </body>

Now that we have our queue output setup we actually need to push content to it. This can be done easily using the se_asset_queue:queue tag:

1{{ se_asset_queue:queue }}
2 <script src="//my/awesome/file.js" defer></script>
3 <script src="//my/awesome/file2.js" defer></script>
4 <link rel="stylesheet" href="//my/awesome/styles.css">
5{{ /se_asset_queue:queue }}

When using the se_asset_queue:queue tag we do not need to specify if something is a script or stylesheet. Internally, the asset queue system will parse the contents that should be added to the queue. If it is a <script> tag, it will automatically be added to the scripts queue, otherwise it is added to the styles queue.

Do Not Queue Arbitrary Code

The asset management system is designed to be used with stylesheet/script path references. It was not designed to be used with arbitrary inline CSS or JavaScript code.

Additionally, the asset management system will automatically remove duplicate script/stylesheet references for you, regardless of any extraneous whitespace that might appear within the tag's contents. Not only does the asset management system handle duplicate asset references with extraneous whitespace, it can also remove duplicates even if attributes are in a different order.

As an example, the following would only output one stylesheet link:

1{{ se_asset_queue:queue }}
2 <link rel="stylesheet" href="//my/awesome/styles.css">
3 <link href="//my/awesome/styles.css" rel="stylesheet">
4{{ /se_asset_queue:queue }}
6... more template code ...
8{{ se_asset_queue:queue }}
9 <link rel="stylesheet"
10 href="//my/awesome/styles.css">
11 <link href="//my/awesome/styles.css" rel="stylesheet">
12{{ /se_asset_queue:queue }}

Some absolutely amazing

The following amazing people help support this site and my open source projects ♥️
If you're interesting in supporting my work and want to show up on this list, check out my GitHub Sponsors Profile.