=encoding utf8

=head1 NAME

Mojolicious::Plugin::AssetPack::Manual::Assets - How to define assets

=head1 DESCRIPTION

This manual will show you various ways to define assets with
L<Mojolicious::Plugin::AssetPack>.

=head1 DEFINING ASSETS

First you need to load the plugin. Here is an example lite app, which does
that:

  plugin "AssetPack";

=head2 Local assets

Here is the basic way of defining an asset:

  app->asset(
    "some-asset.js" => (
      "/js/foo.js",
      "/js/bar.js",
    )
  );

The "some-asset.js" string is just so you can refer to the generated bundle
in your templates L<later|Mojolicious::Plugin::AssetPack::Manual::Include>,
while the list of files after (foo.js and bar.js) are files that exist in
one of the public L<static|Mojolicious/static> directories defined in your
application.

=head2 Online assets

The assets do not need to be on the same machine. They can also be
L<fetched|Mojolicious::Plugin::AssetPack/fetch> from the world wide web:

  app->asset(
    "bundle.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",
    )
  );

The code above will download three assets from web and combine them with
one asset defined locally.

NOTE! The online assets are cached locally, which means that they will not
be refreshed, unless you manually delete them.

=head2 Dynamic assets

This is very similar to L</Online assets>, except that they are generated by
the current L<Mojolicious> application.

  app->asset("some-asset.css" => "/dynamic-path/foo.css")

The above "/dynamic-path/foo.css" will be fetched from the current C<app>
unless a static file has the same name.

=head2 Wildcards

Assests can be brought in via wildcards:

  app->asset(
    "bundle.js" => ("/js/myapp.js", "/js/*.js")
  );

The C</js/*.js> will tell AssetPack to look in all public directories for any
files mathing the L<wildcard expression|perlfunc/glob>. Note that since
"myapp.js" is already defined, it will not be added again even if the wildcard
expression match that file.

If there is a need to set a load precedence, simply add the files that need
to be loaded first into the array before the wildcard or prefix the filenames
with a number: C<01-polyfill.js>, C<02-main.js>, ...

=head2 Custom source directories

It's possible to make AssetPack look for source files in a different directory
than in the public directories. This is useful if you want to keep your source
files outside of the web root.

  plugin AssetPack => {
    source_paths => [
      "assets",
      "/usr/share/assets",
      @{$app->static->paths},
    ]
  };

The code above tells AssetPack to look for assets in the "assets" directory,
relative to the L<app home dir|Mojo/home>, then in the absolute path
"/usr/share/assets" and fallback to the static directories (web root).

This is also very neat when using L<morbo|Mojo::Server::Morbo> to watch your
files:

  # Before and after specifying "source_paths"
  $ moboo -w public/css -w public/js -w public/tags -w public/sass -w lib
  $ morbo -w assets -w lib

  # This will cause an infinite loop, since public/packed change on
  # application reload:
  $ morbo -w public -w lib

=head1 NEXT

Now that you know how to define your assets, you can start using them in
your L<templates|Mojolicious::Plugin::AssetPack::Manual::Include>.

=head1 AUTHOR

Jan Henning Thorsen - C<jhthorsen@cpan.org>

=cut
