NAME
Mojolicious::Plugin::AssetPack - Compress and convert css, less, sass,
javascript and coffeescript files
VERSION
0.32
SYNOPSIS
In your application:
use Mojolicious::Lite;
plugin 'AssetPack';
# define assets: $moniker => @real_assets
app->asset('app.js' => '/js/foo.js', '/js/bar.js', '/js/baz.coffee');
app->asset('app.css' => '/css/foo.less', '/css/bar.scss', '/css/main.css');
# you can combine with assets from web
app->asset('ie8.js' => (
'http://cdnjs.cloudflare.com/ajax/libs/es5-shim/2.3.0/es5-shim.js',
'http://cdnjs.cloudflare.com/ajax/libs/es5-shim/2.3.0/es5-sham.js',
'http://code.jquery.com/jquery-1.11.0.js',
'/js/myapp.js',
));
app->start;
In your template:
%= asset 'app.js'
%= asset 'app.css'
Or if you want the asset inlined in the HTML:
%= asset 'app.css', { inline => 1 }
You can also pass on attributes to the generated HTML tag:
%= asset 'app.css', {}, media => "print,handheld,embossed"
Or if you need to add the tags manually:
% for my $asset (asset->get('app.js')) {
%= javascript $asset
% }
See also "register".
DESCRIPTION
Mojolicious::Plugin::AssetPack is a Mojolicious plugin which can be used
to cram multiple assets of the same type into one file. This means that
if you have a lot of CSS files (.css, .less, .sass, ...) as input, the
AssetPack can make one big CSS file as output. This is good, since it
will often speed up the rendering of your page. The output file can even
be minified, meaning you can save bandwidth and browser parsing time.
The core preprocessors that are bundled with this module can handle CSS
and JavaScript files, written in many languages.
See Mojolicious::Plugin::AssetPack::Preprocessors for more details.
Production mode
This plugin will compress sass, less, css, javascript and coffeescript
with the help of external applications on startup. The result will be
one file with all the sources combined. This file is stored in "Packed
directory".
The files in the packed directory will have a checksum added to the
filename which will ensure broken browsers request a new version once
the file is changed. Example:
<script src="/packed/app-ed6d968e39843a556dbe6dad8981e3e0.js">
This is done using "process".
Development mode
This plugin will expand the input files to multiple script or link tags
which makes debugging and development easier.
This is done using "expand".
TIP! Make morbo watch your less/sass files as well:
$ morbo -w lib -w templates -w public/sass
You can also set the "MOJO_ASSETPACK_NO_CACHE" environment variable to 1
to convert your less/sass/coffee files each time their asset directive
is expanded (only works when "minify" is disabled).
Inlined assets
AssetPack is able to insert your assets directly into your markup. This
is useful if you want to make a one-page app and want to keep the number
of requests to the server at a minimum. However, the images, fonts or
any other external asset which again is referred to require more
requests to the server. See below on how to include the asset directly
in your template:
%= asset 'app.css', { inline => 1 }
Or for manual inspection:
% for my $data (asset->get('app.js', { inline => 1 })) {
%== $data;
}
Custom domain
You might want to serve the assets from a domain different from where
the main app is running. The reasons for that might be:
* No cookies send on each request. This is especially useful when you
use Mojolicious sessions as they are stored in cookies and clients
send whole session with every request.
* More request done in parallel. Browsers have limits for sending
parallel request to one domain. With separate domain static files
can be loaded in parallel.
* Serve files directly (by absolute url) from CDN (or Amazon S3).
This plugin support this if you set a custom "base_url".
See also
<https://developers.google.com/speed/docs/best-practices/request#ServeFr
omCookielessDomain>.
ENVIRONMENT
MOJO_ASSETPACK_DEBUG
Set this to get extra debug information to STDERR from AssetPack
internals.
MOJO_ASSETPACK_NO_CACHE
If true, convert the assets each time they're expanded, instead of once
at application start (useful for development). Has no effect when
"minify" is enabled.
ATTRIBUTES
base_url
$self = $self->base_url("http://my-domain.com/static/");
$str = $self->base_url;
This attribute can be used to control where to serve static assets from.
it defaults to "/packed". See also "Custom domain".
NOTE! You need to have a trailing "/" at the end of the string.
minify
Set this to true if the assets should be minified.
preprocessors
Holds a Mojolicious::Plugin::AssetPack::Preprocessors object.
out_dir
Holds the path to the directory where packed files can be written. It
defaults to "mojo-assetpack-public/packed" directory in temp unless a
static directory is writeable.
METHODS
add
$self->add($moniker => @rel_files);
Used to define new assets aliases. This method is called when the
"asset()" helper is called on the app.
fetch
$path = $self->fetch($url);
This method can be used to fetch an asset and store the content to a
local file. The download will be skipped if the file already exists. The
return value is the absolute path to the downloaded file.
get
@files = $self->get($moniker);
Returns a list of files which the moniker point to. The list will only
contain one file if the $moniker is minified.
process
$self->process($moniker => @files);
This method use "process" in
Mojolicious::Plugin::AssetPack::Preprocessors to convert and/or minify
the sources pointed at by $moniker.
The result file will be stored in "Packed directory".
register
plugin AssetPack => {
base_url => $str, # default to "/packed"
minify => $bool, # compress assets
};
Will register the "compress" helper. All arguments are optional.
"minify" will default to true if "mode" in Mojolicious is "production".
COPYRIGHT AND LICENSE
Copyright (C) 2014, Jan Henning Thorsen.
This program is free software, you can redistribute it and/or modify it
under the terms of the Artistic License version 2.0.
AUTHOR
Jan Henning Thorsen - "jhthorsen@cpan.org"
Alexander Rymasheusky
Per Edin - "info@peredin.com"
Viktor Turskyi