Assets

Overview

Lamotivo Asset Manager is a Laravel package to manage assets in your application.

Main features:

  • Generating HTML tags for including your Javascript and CSS files.
  • Detecting the type of an asset.
  • Registering assets on the fly.
  • Supporting local and remote assets.
  • Preventing duplicated assets.
  • Concatenating and minifying assets to a single file.
  • Supporting asset collections, allowing asset dependency definition.
  • Grouping assets.
  • Preconfigured asset collections out of the box.

Installation

Require the package:

composer require lamotivo/assets

Publish a configuration file:

php artisan vendor:publish --provider="Lamotivo\Assets\AssetServiceProvider" --tag=config

Configuration

A public directory to store and fetch your compiled asset files is lm-assets, as of the assets.public_prefix configuration option.

This directory should be gitignored.

Asset Locations

Your assets may be placed in different directories. The default directories are set in the paths of your assets.php configuration file.

'paths' => [
    resource_path('js'),
    resource_path('css'),
],

If you want to keep all your assets in a combined directory, say resources/assets, you should change the paths:

'paths' => [
    resource_path('assets'),
]

You are free to add multiple paths, Lamotivo Asset Manager will find assets in the defined order.

On run time you may add new directories with the Asset::addLocation or Asset::prependLocation methods, just like in Laravel views.

Namespaced Assets

To integrate your application with vendor packages, assets may be namespaced.

Namespaced assets have prefix in their names.

Lamotivo Asset Manager ships with two packages of Bootstrap CSS framework under namespaced assets: bs3 for Bootstrap 3 and bs4 for Bootstrap 4.

To call the namespaced asset just use it the namespace::asset syntax convention: bs3::bootstrap.scss, bs3::bootstrap.min.js.

To add new namespace use the Asset::addNamespace or Asset::prependNamespace methods, just like in Laravel views:

Asset::addNamespace('custom', 'path/to/assets');

Registering Assets

Asset::add('script.js');
Asset::add('style.css');

// or just combine them:

Asset::add(['script.js', 'style.css']);

By default, all assets are stored in the app group. You may pass a group name as the second argument:

Asset::add('jquery.js', 'vendor');

You may register a remote asset, as well:

Asset::add('https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js', 'vendor');

Lamotivo Asset Manager detects a type automatically on the file extension.

Asset::addJs('resource.js');
Asset::addCss('resource.css');

Rendering Assets

To render the HTML code you may use the Asset::css and Asset::js methods:

echo Asset::css();
echo Asset::js();

This will render an HTML code like this:

<link rel="stylesheet" href="/lm-assets/app-906fb8eac3.css">
<script src="/lm-assets/app-939e488502.js"></script>

In your Blade view you may use the @asset_css and asset_js Blade helpers:

@asset_css
@asset_js

If no argument is passed to the rendering functions, the app group is rendered by default. If you want to render a specific group, you should pass its name as the first argument:

@asset_js('vendor')
@asset_css('vendor')

Typically, you will use a code like this:

<!doctype html>
<html>
    <head>
        <title>...</title>

        @asset_css('vendor')
        @asset_css('app')
    </head>
    <body>

        ...

        @asset_js('vendor')
        @asset_js('app')
    </body>
</html>

Collections

Lamotivo Asset Manager supports asset collections to realize asset dependency or just like asset name aliasing. A collection is a set of assets (Javascript or CSS file). Any collection may include other collections, as well.

To register a collection, you may add it to the collections configuration of your assets.php configuration file:

'collections' => [
    'angularjs' => 'angular.min.js',
    'jquery' => 'jquery.min.js',
    'moment' => 'moment.min.js',
    'bootstrap' => [
        'jquery',
        'bootstrap.min.css',
        'bootstrap.min.js',
    ],
]

Also, you may register a collection on run time:

Asset::registerCollection('basic', [
    'bootstrap',
    'angularjs',
    'jquery',
    'moment',
]);

If you pass to the Asset::add method a collection name instead of a certain asset, you will add all the assets that exist in the collection:

Asset::add('basic', 'vendor');

This will add to the vendor group the following assets: jquery.min.js, bootstrap.min.css, bootstrap.min.js, angular.min.js, moment.min.js. Here, it is worth noting that the Lamotivo Asset Manager eliminates duplicates, if such are (jquery.min.js will be included only once, when we called the boostrap collection, which has it as a dependency).

Lamotivo Asset Manager ships with some predefined collections, you may customize them to your liking at the assets.collections option.

Fonts

Lamotivo Asset Manager allows you easily add fonts from Google Web Fonts or your local fonts, as well.

Google Web Fonts

To register a web font, you may add it to the fonts configuration of your assets.php configuration file:

'font_subsets' => [
    'cyrillic',
],

'font_display' => 'swap',

'fonts' => [
    'Roboto Condensed' => '400,700',
],

In this example we added the Roboto Condensed font with variants of 400 and 700, with swapping font display and the cyrillic subset.

Alternatively, you may register a font on run time:

Asset::addFont('Roboto Condensed', '400,700', 'cyrillic');

Local Web Fonts

To register a local web font, you may add it to the local_fonts configuration of your assets.php configuration file:

'local_fonts' => [
    'TT Norms' => [
        '400' => 'TT Norms Regular',
        '600' => 'TT Norms Bold',
        '400i' => 'TT Norms Italic',
    ],
],

Alternatively, you may register a local font on run time:

Asset::addLocalFont('TT Norms', [
    '400' => 'TT Norms Regular',
    '600' => 'TT Norms Bold',
    '400i' => 'TT Norms Italic',
]);

Place your local fonts to the asset directory named fonts.

Name your local fonts in slugified way:

  • tt-norms-regular.eot, tt-norms-regular.woff, etc
  • tt-norms-bold.eot, tt-norms-bold.woff, etc
  • tt-norms-italic.eot, tt-norms-italic.woff, etc

Rendering Web Fonts

Use the @asset_font Blade helper to render HTML code that will include your registered web fonts, both Google and local web fonts.

Asset Filters

Lamotivo Asset Manager pass each your asset through filters, that impact on the asset compilation.

Javascript Filters

Javascript filters are set in the js_filters configuration of your assets.php configuration file:

'js_filters' => [
    new Lamotivo\Assets\Filters\JsMin,
    new Lamotivo\Assets\Filters\NewLine,
],

Lamotivo\Assets\Filters\JsMin minifies your JS assets, Lamotivo\Assets\Filters\NewLine adds new line after each JS asset.

CSS Filters

CSS filters are set in the css_filters configuration of your assets.php configuration file:

'css_filters' => [
    new Lamotivo\Assets\Filters\ScssCompiler,
    new Lamotivo\Assets\Filters\CssMin,
    new Lamotivo\Assets\Filters\CssRewriteUrls,
],

Lamotivo\Assets\Filters\ScssCompiler checks if the given asset is a SCSS file and compiles it into CSS.

Lamotivo\Assets\Filters\CssMin minifies your CSS assets, Lamotivo\Assets\Filters\CssRewriteUrls rewites the relative URLs in remote assets to their remote equivalents.

SCSS Assets

Lamotivo Asset Manager allows you to use SCSS assets with a SCSS compiler.

You may customize SCSS with the scss configuration in your assets.php configuration file:

'scss' => [
    'formatter' => 'compact',
    'paths' => [
        resource_path(),
    ],
    'vars' => [
    ],
    'functions' => [
        'theme-url' => new Lamotivo\Themes\ScssFunctions\ThemeUrl,
    ],
],

In this configuration option you may define a SCSS output format, paths to import inside SCSS files, predefined variables and functions.

If you use Lamotivo Theme Manager, you may add the theme-url SCSS function to properly retrieve a theme static asset (e.g. images).

SCSS Formatters

Available SCSS formatters are:

  • expanded
  • nested
  • compact
  • compressed
  • crunched

For more information, see the scssphp documentation.

© 2022 Softmedialine, LLC
Crafted in Siberia