webrouse/n-asset-macro

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

Thursday, July 12, 2018
by webrouse
Repository
3 Watchers
7 Stars
7,107 Installations

PHP
2 Dependents
0 Suggesters
1 Forks
0 Open issues
6 Versions
28 % Grown

The README.md

Webrouse/n-asset-macro

, _(*1)

Asset macro for Latte and Nette Framework., _(*2)

Useful for assets cache busting with gulp, webpack and other similar tools., _(*3)

Requirements

PHP >=7.1
Nette >=2.4
Latte >=2.4

Nette 3 is fully supported and tested., _(*4)

Installation

The best way to install webrouse/n-asset-macro is using Composer:, _(*5)

$ composer require webrouse/n-asset-macro

Then register the extension in the config file:, _(*6)

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

Usage

Macro can by used in any presenter or control template:, _(*7)

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

It prepends path with $basePath or $baseUrl (see absolute) and loads revision from the revision manifest:, _(*8)

<script src="/base/path/resources/vendor.d78da025b7.js"></script>
<script src="http://www.example.com/base/path/resources/main.34edebe2a2.js"></script>

See the examples for usage with gulp, webpack., _(*9)

Revision manifest

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

It can be generated by various asset processors such as gulp and webpack, see examples., _(*11)

Revision manifest is searched in the asset directory and in the parent directories up to %wwwDir%., _(*12)

Expected file names: assets.json, busters.json, versions.json, manifest.json, rev-manifest.json., _(*13)

The path to revision manifest can be set directly (instead of autodetection):, _(*14)

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

Or you can specify asset => revision pairs in config file:, _(*15)

# app/config/config.neon
assetMacro:
    manifest:
      '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., _(*16)

Method 1: asset version in file name (preferable)

With this method, the files have a different name at each change., _(*17)

Example revision manifest:, _(*18)

{
    "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., _(*19)

Method 2: asset version as a query string

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

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

Example revision manifest:, _(*22)

{
    "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., _(*23)

Asset macro automatically detects which of these two formats of revision manifest is used., _(*24)

Macro arguments

`format`

The format is defined by the second macro parameter or using the format key (default %url%)., _(*25)

format can be used with needed => false to hide whole asset expression (eg. <link ...) in case of an error., _(*26)

You can also use it to include asset content instead of a path., _(*27)

Placeholder	Example output
`%content%`	`<svg>....</svg>` (file content)
`%path%`	`js/main.js` or `js/main.8c48f58df.js`
`%raw%`	`8c48f58df` or `js/main.8c48f58df.js`
`%base%`	`%baseUrl%` if `absolute => true` else `%basePath%`
`%basePath%`	`/base/path`
`%baseUrl%`	`http://www.example.com/base/path`
`%url%`	`%base%%path%` (default format) eg. `/base/path/js/main.8c48f58df.js`

{* 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>

`needed`

Error handling is set in the configuration using: missingAsset, missingManifest and missingRevision keys., _(*28)

These settings can by overrided by third macro parameter or using needed key (default true)., _(*29)

Argument needed => false will cause the missing file or the missing revision record will be ignored., _(*30)

Missing version will be replaced with unknown string., _(*31)

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)., _(*32)

{asset 'js/absent.js', '<script src="%url%"></script>', FALSE}
{asset 'js/missing_rev.js', format => '<script src="%url%"></script>', needed => FALSE}

Generated output:, _(*33)

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

`absolute`

Output URL type - relative or absolute - is defined by fourth macro parameter or using absolute key (default false)., _(*34)

If absolute => true or asset path is prefixed with // eg. (//assets/js/main.js), the absolute URL will be generated instead of a relative URL., _(*35)

{asset 'js/vendor.js'}      {* equal to {asset 'js/vendor.js', absolute => false} *}
{asset '//js/vendor.js'}    {* equal to {asset 'js/vendor.js', absolute => true}  *}

Generated output:, _(*36)

Caching

In production mode is the macro output cached in default application's cache storage., _(*37)

It can be changed in the configuration using the boolean cache key., _(*38)

Configuration

Default configuration, which usually doesn't need to be changed:, _(*39)

# app/config/config.neon
assetMacro:
    # Cache generated output
    cache: %productionMode%
    # Path to revision manifest or asset => revision pairs,
    # if set, the autodetection is switched off
    manifest: null # %wwwDir%/assets/manifest.json
    # File names for automatic detection of revision manifest
    autodetect:
        - assets.json
        - busters.json
        - versions.json
        - manifest.json
        - rev-manifest.json
    # Absolute path to assets dir
    assetsPath: %wwwDir%/ # %wwwDir%/assets
    # Public path to "assetsPath"
    publicPath: / # /assets
    # 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: notice
    # Default format, can be changed in macro using "format => ..."
    format: '%%url%%' # character % is escaped by %%

`ManifestService`

It is also possible to access the manifest from your code using Webrouse\AssetMacro\ManifestService (from DI container)., _(*40)

/** @var ManifestService $manifestService */
$cssAssets = $manifestService->getManifest()->getAll('/.*\.css$/');

Examples

MIT

The Requires

The Development Requires

by Michal Jurečko

20/01 2017

v0.1

0.1.0.0

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

library n-asset-macro

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