visuellverstehen/statamic-sourcestack

SourceStack

A Statamic utility to only include css/js sources once. This can be useful when you want to include dedicated files for specific partials/sets that would otherwise be included multiple times within a template.

Assume a basic Statamic blueprint with a replicator field pagebuilder that stacks sets in a template:

<!-- page-template.antlers.html -->

{{ pagebuilder }}
    {{ partial:if_exists src="sets/{type}" }}
{{ /pagebuilder }}

Further assume that there is an 'image' and a 'gallery' set, which both require dedicated javascript source files:

<!-- sets/image.antlers.html -->

<img src"…" class="lightbox">

{{ once }}
    {{ push:scripts }}
        {{ vite src="resources/js/lightbox.js" }}
    {{ /push:scripts }}
{{ /once }}

<!-- sets/gallery.antlers.html -->

<ul class="gallery">
    …
</ul>

{{ once }}
    {{ push:scripts }}
        {{ vite src="resources/js/lightbox.js|resources/js/slider.js" }}
    {{ /push:scripts }}
{{ /once }}

By using the once tag we try make sure to only include every source once. The scripts stack is rendered in the layout.

However, if you add both an image and a gallery in a page, the lightbox.js script file will be added twice. The stack has no way to determine if a file was already added or not.

This is where SourceStack comes in.

How to Install

Run the following command from your project root:

composer require visuellverstehen/statamic-sourcestack

How to Use

Let's modify the Statamic setup described above. Instead of using the scripts stack for our js source, we use the sourcestack tag included in this package:

<!-- sets/image.antlers.html -->

<img src"…" class="lightbox">

{{ sourcestack src="resources/js/lightbox.js" }}

The tag collects all the sources throughout the template, making sure to add every source only once. Eventually, the sourcestack:render tag renders all collected sources as a vite source tag.

<!-- layout.antlers.html -->
<!-- … -->

<body>
    <main>
        {{ template_content }}
    </main>
    
    {{ sourcestack:render }}
</body>

You can also use the tag alias srcstk. Sources can be added with the src, source or file parameter. Output can be generated with render or vite.

{{ srcstk src="lightbox.js" }}
{{ srcstk:vite }}

Like in a vite tag you can add multiple sources at once. Files must be separated by either a comma (,) or a pipe (|):

{{ srcstk src="lightbox.js|gallery.js" }}

Dedicated stacks

If you need multiple stacks for different sources, you can define dedicated stacks in the config file:

'stacks' => [
    'css' => [
        'base_dir' => 'resources/css/',
        'extension' => 'css',
    ]
],

For each stack you can optionally define a base directory and a file extension. Assuming the example above, the tag would be used like this:

{{ sourcestack:css src="gallery" }}
{{ sourcestack:render stack="css" }}

Please note that stacks can't be called render or any other strings that resolve to public function names of the Sourcestack tag class.

Caveats

The way SourceStack is currently built requires the output to be called after all sources have been collected. You can however use Statamics section and yield logic to move e. g. a stack with css files to the <head> element:

<head>
    <!-- … -->
    
    {{ yield:css-sources }}
</head>
<body>
    <!-- … -->
    
    {{ section:css-sources }}
        {{ sourcestack:render stack="css" }}
    {{ /section:css-sources }}
</body>

Configuration

In addition to dedicated stacks (see above), you can configure the default base directory to be used for all regular source file paths in config/sourcestack.php.

More about us

• www.visuellverstehen.de

License

The MIT license (MIT). Please take a look at the license file for more information.