.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojolicious::Plugin::AssetPack::Guides::Cookbook 3pm"
.TH Mojolicious::Plugin::AssetPack::Guides::Cookbook 3pm "2023-02-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojolicious::Plugin::AssetPack::Guides::Cookbook \- AssetPack recipes
.SH "OVERVIEW"
.IX Header "OVERVIEW"
This guide will provide recipes for cooking with
Mojolicious::Plugin::AssetPack.
.SH "ASSETS FROM CUSTOM DOMAIN"
.IX Header "ASSETS FROM 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:
.IP "\(bu" 2
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.
.IP "\(bu" 2
More requests done in parallel. Browsers have limits for sending parallel
request to one domain. With separate domain static files can be loaded in
parallel.
.IP "\(bu" 2
Serve files directly (by absolute url) from \s-1CDN\s0 (or Amazon S3).
.SS "Synopsis"
.IX Subsection "Synopsis"
You need to customize \*(L"route\*(R" in Mojolicious::Plugin::AssetPack to accomplish
this:
.PP
.Vb 1
\&  $app\->asset\->route\->to(base_url => "http://cdn.example.com/my\-assets/");
.Ve
.SS "Caveat"
.IX Subsection "Caveat"
Many recent browsers blocks mixed content, meaning if your \s-1HTML\s0 is served over
\&\s-1HTTPS,\s0 then you can't serve the assets over \s-1HTTP.\s0 One way to fix this is by
using \*(L"//\*(R" instead of a scheme specific \s-1URL.\s0 Example:
.PP
.Vb 1
\&  base_url => "//cdn.example.com/my\-assets/"
.Ve
.PP
This will tell the browser to use the same scheme for fetching assets, as it
did fetching the web page.
.SS "See also"
.IX Subsection "See also"
<https://developers.google.com/speed/docs/best\-practices/request#ServeFromCookielessDomain>.
.SH "DYNAMIC ASSETS"
.IX Header "DYNAMIC ASSETS"
Any web asset with the
hostname \*(L"local\*(R" will be routed to the current Mojolicious application.
Example:
.PP
.Vb 3
\&  $ cat assetpack.def
\&  ! app.js
\&  < http://local/some/resource.js
.Ve
.PP
The above \s-1URL\s0 will make AssetPack issue a request to the current Mojolicious
application, allowing it to render dynamic JavaScript. Example Mojolicious
resource:
.PP
.Vb 4
\&  get "/some/resource" => [format => "js"], sub {
\&    my $c = shift;
\&    $c\->render(text => sprintf "rand = %s\en", rand);
\&  };
.Ve
.SS "Sass"
.IX Subsection "Sass"
Sass files can also be generated dynamically. Here is an example Sass file:
.PP
.Vb 3
\&  @import "http://local/sass/dynamic";
\&  $color: red !default;
\&  body { color: $color; }
.Ve
.PP
Normally, the \f(CW@import\fR statement would be left untouched, but AssetPack will
(in the special case where the host is \*(L"local\*(R") inline the result from that
resource. This allow \f(CW$color\fR to be set from the application and override the
default \f(CW$color\fR in the file above. Example:
.PP
.Vb 4
\&  get "/sass/_dynamic" => [format => "scss"], sub {
\&    my $c = shift;
\&    $c\->render(text => "\e$color: black;\en");
\&  };
.Ve
.PP
Note that this feature is \s-1EXPERIMENTAL\s0 and not compatible with standard Sass
rules.
.SH "ONLINE ASSETS"
.IX Header "ONLINE ASSETS"
Instead of making custom AssetPack plugins, it is possible to simply include
projects such as Bootstrap, FontAwesome or jQuery directly from the web
instead.
.SS "Bootstrap"
.IX Subsection "Bootstrap"
The \s-1SASS\s0 version of <http://getbootstrap.com> can easily be included by defining it
in the assetspack.def
file:
.PP
.Vb 3
\&  $ cat \- > assets/assetpack.def
\&  ! app.css
\&  < https://github.com/twbs/bootstrap\-sass/raw/master/assets/stylesheets/_bootstrap.scss
.Ve
.PP
After that, you might want to customize bootstrap. This can then be done by changing
\&\*(L"assetpack.def\*(R" to:
.PP
.Vb 3
\&  ! app.css
\&  << https://github.com/twbs/bootstrap\-sass/raw/master/assets/stylesheets/_bootstrap.scss
\&  < sass/main.scss
.Ve
.PP
\&\*(L"assets/sass/main.scss\*(R" should then have a modified version of
<https://github.com/twbs/bootstrap\-sass/raw/master/assets/stylesheets/_bootstrap.scss>:
.PP
.Vb 5
\&  @import "variables.scss";
\&  @import "../cache/github.com/twbs/bootstrap\-sass/raw/master/assets/stylesheets/bootstrap/mixins";
\&  @import "../cache/github.com/twbs/bootstrap\-sass/raw/master/assets/stylesheets/bootstrap/normalize";
\&  @import "../cache/github.com/twbs/bootstrap\-sass/raw/master/assets/stylesheets/bootstrap/print";
\&  ...
.Ve
.PP
The file \*(L"_variables.scss\*(R" should also be copied to \*(L"assets/sass\*(R".
.PP
(Note that the rest of the example file above is truncated)
.SS "Font awesome"
.IX Subsection "Font awesome"
<https://fortawesome.github.io/Font\-Awesome/> can be included with the snippet
below:
.PP
.Vb 5
\&  $app\->asset\->process(
\&    "app.css" => (
\&      "https://maxcdn.bootstrapcdn.com/font\-awesome/4.5.0/css/font\-awesome.min.css",
\&    )
\&  );
.Ve
.PP
See also Mojolicious::Plugin::AssetPack::Pipe::Fetch for information about
automatically fetching related font files.
.SS "Google fonts"
.IX Subsection "Google fonts"
<https://www.google.com/fonts> can be included with this snippet:
.PP
.Vb 6
\&  $app\->asset\->process(
\&    "app.css" => (
\&      "https://fonts.googleapis.com/css?family=Roboto:400,700",
\&      "your\-app.css",
\&    )
\&  );
.Ve
.SS "JavaScript polyfills"
.IX Subsection "JavaScript polyfills"
<https://github.com/Modernizr/Modernizr> contains a list of many shims which
can be included. Here is just one example:
.PP
.Vb 7
\&  $app\->asset\->process(
\&    "app.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",
\&      "your\-app.js",
\&    )
\&  );
.Ve
.SS "jQuery"
.IX Subsection "jQuery"
<http://jquery.com> can easily be included by referring to a \s-1CDN:\s0
.PP
.Vb 6
\&  $app\->asset\->process(
\&    "app.js" => (
\&      "http://code.jquery.com/jquery\-1.12.0.js",
\&      "your\-app.js",
\&    )
\&  );
.Ve
.SS "Materialize \s-1CSS\s0"
.IX Subsection "Materialize CSS"
<http://materializecss.com/> can be included by defining it
in the assetspack.def
file. Mojolicious::Plugin::AssetPack::Pipe::Sass will also discover all
the \*(L"@import\*(R" files and download those recusively as well.
.PP
.Vb 4
\&  $ cat \- > assets/assetpack.def
\&  ! app.css
\&  < https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss
\&  < https://fonts.googleapis.com/icon?family=Material+Icons
.Ve
.PP
After that, you might want to customize Materialize. This can then be done by changing
\&\*(L"assetpack.def\*(R" to:
.PP
.Vb 4
\&  ! app.css
\&  << https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss
\&  < https://fonts.googleapis.com/icon?family=Material+Icons
\&  < sass/main.scss
.Ve
.PP
\&\*(L"assets/sass/main.scss\*(R" should then have a modified version of
<https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss>:
.PP
.Vb 6
\&  @charset "UTF\-8";
\&  @import "../cache/raw.githubusercontent.com/Dogfalo/materialize/master/sass/components/prefixer";
\&  @import "../cache/raw.githubusercontent.com/Dogfalo/materialize/master/sass/components/mixins";
\&  @import "../cache/raw.githubusercontent.com/Dogfalo/materialize/master/sass/components/color";
\&  @import "variables.scss";
\&  ...
.Ve
.PP
The file \*(L"_variables.scss\*(R" should also be copied to \*(L"assets/sass\*(R".
.PP
(Note that the rest of the example file above is truncated)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious::Plugin::AssetPack,
Mojolicious::Plugin::AssetPack::Guides::Developing and
Mojolicious::Plugin::AssetPack::Guides::Tutorial.