Ubuntu Manpage: Mojolicious::Plugin::AssetPack::Guides::Tutorial

Provided by: libmojolicious-plugin-assetpack-perl_2.02-1_all

NAME

       Mojolicious::Plugin::AssetPack::Guides::Tutorial - AssetPack tutorial

OVERVIEW

       This guide will give detailed information about how to define assets and include them into
       your templates.

       See "DESCRIPTION" in Mojolicious::Plugin::AssetPack for a short description of AssetPack.

GUIDE

Loading the plugin
The plugin needs to be installed an loaded before any assets can be defined:

$app->plugin(AssetPack => \%args);

Details about %args can be found under "register" in Mojolicious::Plugin::AssetPack, but
there is one mandatory argument worth noting: "pipes". "pipes" need to be a list of all
the pipes you need to process your assets. Example:

$app->plugin(AssetPack => {pipes => [qw(Sass Css Combine)]});

Loading the plugin with the list above will enable AssetPack to process Sass and Css
files, minify them and combine them into a single asset in production.

Optional dependencies
AssetPack has only optional dependencies. The reason for that is that the dependencies
should only be required while developing, and not for running the application. See
<https://github.com/jhthorsen/mojolicious-plugin-assetpack/blob/v2/cpanfile> for a
complete list, but here are the current list:

• CSS::Minifier::XS 0.09

Used to minify CSS.

• CSS::Sass 3.3.0

Used to process and minify CSS.

• Imager::File::PNG 0.90

TODO: Used to generate CSS sprites.

• JavaScript::Minifier::XS 0.11

Used to minify JavaScript.

Pipes
AssetPack does not do any heavy lifting itself: All the processing is left to the pipe
objects.

• Mojolicious::Plugin::AssetPack::Pipe::CoffeeScript

Process CoffeeScript coffee files. Should be loaded before
Mojolicious::Plugin::AssetPack::Pipe::JavaScript.

• Mojolicious::Plugin::AssetPack::Pipe::Combine

Combine multiple assets to one. Should be loaded last.

• Mojolicious::Plugin::AssetPack::Pipe::Css

Minify CSS.

• Mojolicious::Plugin::AssetPack::Pipe::Favicon

There is a special topic called "favicon.ico", combined with the
Mojolicious::Plugin::AssetPack::Pipe::Favicon pipe which can be used to describe
favicons, touch icons and tile icons.

• Mojolicious::Plugin::AssetPack::Pipe::Fetch

Will look for "url(...)" in CSS files and download the related assets.

• Mojolicious::Plugin::AssetPack::Pipe::JavaScript

Minify JavaScript.

• Mojolicious::Plugin::AssetPack::Pipe::Jpeg

Used to crush "jpeg" image files.

• Mojolicious::Plugin::AssetPack::Pipe::Less

Process Less CSS files. Should be loaded before
Mojolicious::Plugin::AssetPack::Pipe::Css.

• Mojolicious::Plugin::AssetPack::Pipe::Png

Used to crush "png" image files.

• Mojolicious::Plugin::AssetPack::Pipe::Riotjs

Process <http://riotjs.com/> tag files. Should be loaded before
Mojolicious::Plugin::AssetPack::Pipe::JavaScript.

• Mojolicious::Plugin::AssetPack::Pipe::Sass

Process sass and scss files. Should be loaded before
Mojolicious::Plugin::AssetPack::Pipe::Css.

Where to place source files
The source/input files that make up a virtual asset (topic) can come from either...

On disk

AssetPack will look for source files in the "assets" directory, relative to the
application home. Unlike the "public" directory, this directory is not shared on the
internet, but the generated assets will still be available thanks to a custom route.

Mojolicious::Plugin::AssetPack::Store is a sub class of Mojolicious::Static, allowing it
to find files relative to "paths" in Mojolicious::Static. For example, to change asset
search paths, you can do:

$app->asset->store->paths(["/some/new/location", "/other/location"]);

DATA section

Mojolicious::Plugin::AssetPack::Store is a sub class of Mojolicious::Static, allowing it
to look for files in DATA sections of "classes" in Mojolicious::Static.

The DATA section can also be used to lookup "@import" files. (Currently only supported by
Mojolicious::Plugin::AssetPack::Pipe::Sass)

Web

Any file starting with "http" or "https" will be downloaded from web using "ua" in
Mojolicious::Plugin::AssetPack.

It will also parse recursively "@import" files and download those as well. (Currently
only supported by Mojolicious::Plugin::AssetPack::Pipe::Sass)

Assets from web will be cached locally to prevent downloading new and untested assets on
each application startup.

Current Mojolicious application

See "DYNAMIC ASSETS" in Mojolicious::Plugin::Assets::Guides::Cookbook.

Process assets
Assets should be defined when you application starts. This can either be done using a
definition file or inside you application.

Defining assets in the application

Assets can be defined using the "process" in Mojolicious::Plugin::AssetPack method:

$app->asset->process(
"app.css" => (
"sass/bar.scss",
"foo/bar.css",
"https://github.com/Dogfalo/materialize/blob/master/sass/materialize.scss",
)
);

In the example above we have defined a topic named "app.css" which later can be included
in templates. The list of files following are the source files which will make up the
final asset.

Defining assets in a definition file

Moving the definition to an external file can be useful for keeping the application code
tidy. The definition file should be located in the assets directory, or optionally defined
it in the "DATA" section. The default file is called "assetpack.def" and will be looked up
if "process" in Mojolicious::Plugin::AssetPack is called without arguments. Example file:

! app.css
< sass/bar.scss
<< https://github.com/Dogfalo/materialize/blob/master/sass/materialize.scss
< sass/main.scss

Empty lines and lines starting with "#" will be skipped. Each line starting with "!" will
be used to define a topic (virtual asset name), and "<" will define a source file. This
means that the file above will result in (almost) the same as in the example above.

The idea of the line starting with "<<" is to download an external (remote) file for your
convenience, which can be imported in your SASS/LESS files. The downloaded file is not
included in the output asset. For example, you have "sass/main.scss" which depends on
"materialize.scss" (remote file) and you need this "materialize.scss" file locally
available to be imported in "sass/main.scss". If you want to include a remote file in
your output asset, use '<' insteaf of '<<'.

It is also possible to add conditions:

! app.css
< development.css [mode==development] [minify==0]
< production.css [mode!=development]

"development.css" will be processed if "mode" in Mojolicious is "development" and "minify"
in Mojolicious::Plugin::AssetPack is "0". "production.css" will be processed if "mode" in
Mojolicious is something else than "development". This is especially useful if you want to
include a JavaScript with debug flags set while developing, but switch to a smaller
version without debug in production.

Using assets
Any processed asset can be accessed by referring to a topic.

Template

An asset can be included in a template using the "asset" in Mojolicious::Plugin::AssetPack
helper:

<head>
%= asset "app.css"
%= asset "app.js"
</head>

The "asset" in Mojolicious::Plugin::AssetPack helper takes additional arguments which will
be passed on directly to either the "javascript" in Mojolicious::Plugin::TagHelpers helper
or "stylesheet" in Mojolicious::Plugin::TagHelpers helper. Example:

%= asset "app.css", media => "print"

In production mode, the helper above will just result in one "link" tag. On the other
hand, if you are in "development" mode, it will result in on "link" tag per source asset.

Asset objects

It is also possible to retrieve the processed asset objects. The example below will
retrieve a Mojo::Collection object holding zero or more
Mojolicious::Plugin::AssetPack::Asset objects:

my $collection = $app->asset->processed("app.css");
print $collection->map("checksum")->join(", ");

This can also be used to inline assets in a template:

%= stylesheet sub { asset->processed('app.css')->map('content')->join }

Application mode
The application mode will define if the assets should be combined and minified. The
"minify" in Mojolicious::Plugin::AssetPack attribute can also be set manually if you have
special needs.

Development

The assets will be processed, but not minified/combined if MOJO_MODE or "mode" in
Mojolicious is set to "development". This is to make it easier to map JavaScript or CSS
bugs to a specific file and line. "development" is the default mode while running morbo:

$ morbo -w assets/ -w lib/ -w templates/ script/myapp

Any other mode

Any "production" mode will result in one combined and minified asset. This will save
bandwidth and roundtrip time to the server.

Caching
Processed assets will be cached to disk when possible. The process step is run so if such
a processed asset exists, the process step will not be run again. Again, the external
tools (less, coffee, ...) and modules (JavaScript::Minifier::XS, CSS::Sass) will only be
required while developing, but can be skipped when installing an already built
application.

Assets without topics
One nifty feature is to use Mojolicious::Plugin::AssetPack for assets which do not have
any pipe to process them. The reason why this comes in handy is to avoid cache issues,
since changing the file on disk will generate a new URL.

These assets can also be defined directly in the templates, without having to be defined
in the application startup process. Examples:

# <img src="/asset/52e98718f0/foo.gif">
%= asset "/image/foo.gif"

# <img src="/asset/87652910af/baz.svg">
%= asset "/image/baz.svg"

# <link rel="icon" href="/asset/65428718f1/bar.ico">
%= asset "/image/bar.ico"

# <source src="/asset/87652718f0/baz.mp3" type="audio/mpeg">
%= asset "/audio/baz.mp3"

# <source src="/asset/52e87652f0/foo.mp4" type="video/mp4">
%= asset "/video/foo.mp4"

# <source src="/asset/52eaz7613a/bar.ogg" type="audio/ogg">
%= asset "/audio/bar.ogg"

# <source src="/asset/baf72618f1/foo.ogv" type="audio/ogv">
%= asset "/video/foo.ogv"

# <source src="/asset/92118711f0/bar.webm" type="audio/webm">
%= asset "/video/bar.webm"

NAME

OVERVIEW

GUIDE

SEE ALSO