webrouse/n-asset-macro

Asset macro for Latte and Nette Framework useful for assets cache busting (with gulp, webpack, grunt, etc.)

v1.1 2017-08-31 08:36 UTC

README

Build Status Scrutinizer Code Quality Code Coverage Latest stable

Asset macro for Latte and Nette Framework.

Useful for assets cache busting with gulp, webpack, grunt and other similar tools.

Requirements

PHP 7.1 and Nette 3 are fully supported and tested.

Installation

The best way to install webrouse/n-asset-macro is using Composer:

$ composer require webrouse/n-asset-macro

Then register the extension in configuration:

# app/config/config.neon
extensions:
    assetMacro: Webrouse\AssetMacro\DI\Extension

Usage

Macro can by used in any presenter or control template:

{* app/presenters/templates/@layout.latte *}
<script src="{asset resources/vendor.js}"></script>
<script src="{asset resources/main.js}"></script>

Asset macro prepend path with $basePath and load revision from the revision manifest:

<script src="/base/path/resources/vendor.d78da025b7.js"></script>
<script src="/base/path/resources/main.34edebe2a2.js"></script>

See the examples for usage with gulp, webpack, grunt.

Configuration

Default configuration, which usually doesn't need to be changed:

# app/config/config.neon
assetMacro:
    # Path to revision manifest or asset => revision pairs,
    # if set, the autodetection is switched off
    revManifest: null # %wwwDir%/assets.json
    # File names for automatic detection of revision manifest
    autodetect:
        - assets.json
        - busters.json
        - versions.json
        - manifest.json
        - rev-manifest.json
    # Action if missing asset file: exception, notice, or ignore
    missingAsset: notice
    # Action if missing manifest file: exception, notice, or ignore
    missingManifest: notice
    # Action if missing asset revision in manifest: exception, notice, or ignore
    missingRevision: ignore

Revision manifest

Revision manifest is a JSON file that contains the revision (path or version) of asset.

This file can be generated by various asset processors gulp, grunt and webpack, see examples.

This asset macro searches for the revision manifest in the asset directory or in any parent directory up to %wwwDir%.

By default is rev. manifest expected in: assets.json, busters.json, versions.json, manifest.json or rev-manifest.json file.

Instead of autodetection, the path to revision manifest can be set directly:

# app/config/config.neon
assetMacro:
    revManifest: %wwwDir%/assets.json

Or you can specify asset => revision pairs directly in config file:

# app/config/config.neon
assetMacro:
    revManifest:
      'js/vendor.js': 16016edc74d  # or js/vendor.16016edc74d.js
      'js/main.js':  4b82916016    # or js/main.4b82916016.js

Revision manifest may contains asset version or the asset path. Both ways are supported.

Revision manifest with asset paths

With this method, the files have a different name at each change.

Example revision manifest:

{
	"js/app.js": "js/app.234a81ab33.js",
	"js/vendor.js": "js/vendor.d67fbce193.js",
	"js/locales/en.js": "js/locales/en.d78da025b7.js",
	"js/locales/sk.js": "js/locales/sk.34edebe2a2.js",
	"css/app.css": "css/app.04b5ff0b97.js"
}

With the example manifest, the expr. {asset "js/app.js"} generates: /base/path/js/app.234a81ab33.js.

Revision manifest with asset versions

This approach looks better at first glance. The asset path is still the same, and only the parameter in the query changes.

However, it can cause problems with some cache servers, which don't take the URL parameters into account.

Example revision manifest:

{
	"js/app.js": "234a81ab33",
	"js/vendor.js": "d67fbce193",
	"js/locales/en.js": "d78da025b7",
	"js/locales/sk.js": "34edebe2a2",
	"css/app.css": "04b5ff0b97"
}

With the example manifest, the expr. {asset "js/app.js"} generates: /base/path/js/app.js?v=234a81ab33.

Asset macro automatically detects which of these two formats of revision manifest is used.

Custom format

It is possible to specify the custom format using placeholders:

Placeholder Example output
%url% /base/path/js/main.js?v=8c48f58df or /base/path/js/main.8c48f58df.js
%path% js/main.js or js/main.8c48f58df.js
%raw% 8c48f58df or js/main.8c48f58df.js
%basePath% /base/path

The format is defined by the second macro parameter or using the format key.

{* app/presenters/templates/@layout.latte *}
{asset 'js/vendor.js', '<script src="%url%"></script>'}
<script src="{asset 'js/livereload.js', format => '%path%?host=localhost&v=%raw%'}"></script>

Error handling

Error handling can be set using the configuration keys: missingAsset, missingManifest, missingRevision.

It can be mutted by third macro parameter or key needed (default TRUE).

Argument needed => FALSE will cause the missing file or the missing revision record will be ignored.

Empty string will be result for missing asset. Missing version will be replaced with unknown string.

Example of needed parameter

  • absent.js file doesn't exist.
  • missing_rev.js exists but doesn't have revision in manifest (or the manifest has not been found).
{asset 'js/absent.js', '<script src="%url%"></script>', FALSE}
{asset 'js/missing_rev.js', format => '<script src="%url%"></script>', needed => FALSE}

Generated output:

<script src="/base/path/js/missing_rev.js?v=unknown"></script>

Caching

If you don't want to load the revision manifest in the production mode, you can use the cache macro:

{cache "scripts-$locale", if => ! \Tracy\Debugger::isEnabled()}
<script src="{asset 'js/vendor.js'}" defer></script>
<script src="{asset "js/locales/$locale.js"}" defer></script>
<script src="{asset 'js/main.js'}" defer></script>
{/cache}

Examples

Examples based on nette/sandbox:

License

N-asset-macro is under the MIT license. See the LICENSE file for details.