Mojolic...ookbook(3)

🍓 NAME 🍓

okay bestie, this is the Mojolicious::Plugin::AssetPack::Guides::Cookbook page — you might see it as Mojolic...ookbook(3) — and it's literally AssetPack recipes. 💅

🧁 OVERVIEW 🧁

This guide is gonna give you recipes for cooking with Mojolicious::Plugin::AssetPack. no cap, it's a whole kitchen vibe 🍳✨

🌈 ASSETS FROM CUSTOM DOMAIN 🌈

okay so maybe you wanna serve the assets from a domain that's different from where the main app is running? valid. Reasons you might do that:

• No cookies get sent on each request. This is especially useful when you use Mojolicious sessions, because they're stored in cookies and clients send the whole session with every request.
• More requests get done in parallel. Browsers have limits on sending parallel requests to one domain. With a separate domain, static files can be loaded in parallel.
• Serve files directly (by absolute url) from a CDN (or Amazon S3).

🎀 Synopsis 🎀

You need to customize route in Mojolicious::Plugin::AssetPack to pull this off:

$app->asset->route->to(base_url => "http://cdn.example.com/my-assets/");

💀 Caveat 💀

Many recent browsers block mixed content, meaning if your HTML is served over HTTPS, then you can't serve the assets over HTTP. One way to fix this is by using "//" instead of a scheme-specific URL. Example:

base_url => "//cdn.example.com/my-assets/"

This tells the browser to use the same scheme for fetching assets as it did for fetching the web page. cute, right? 🫶

🛰️ See also 🛰️

Also check out https://developers.google.com/speed/docs/best-practices/request#ServeFromCookielessDomain.

🦋 DYNAMIC ASSETS 🦋

Any web asset with the hostname "local" will be routed to the current Mojolicious application. Example:

$ cat assetpack.def
! app.js
< http://local/some/resource.js

The above URL will make AssetPack issue a request to the current Mojolicious application, letting it render dynamic JavaScript. Example Mojolicious resource:

get "/some/resource" => [format => "js"], sub {
  my $c = shift;
  $c->render(text => sprintf "rand = %s\n", rand);
};

🌸 Sass 🌸

Sass files can also be generated dynamically. Here's an example Sass file:

@import "http://local/sass/dynamic";
$color: red !default;
body { color: $color; }

Normally the @import statement would be left untouched, but AssetPack will (in the special case where the host is "local") inline the result from that resource. This allows $color to be set from the application and override the default $color in the file above. Example:

get "/sass/_dynamic" => [format => "scss"], sub {
  my $c = shift;
  $c->render(text => "\$color: black;\n");
};

Note that this feature is EXPERIMENTAL and not compatible with standard Sass rules. 😭

🌐 ONLINE ASSETS 🌐

Instead of making custom AssetPack plugins, you can simply include projects such as Bootstrap, FontAwesome or jQuery directly from the web instead. iconic behavior.

🥾 Bootstrap 🥾

The SASS version of http://getbootstrap.com can easily be included by defining it in the assetspack.def file:

$ cat - > assets/assetpack.def
! app.css
< https://github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/_bootstrap.scss

After that, you might want to customize bootstrap. This can then be done by changing "assetpack.def" to:

! app.css
<< https://github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/_bootstrap.scss
< sass/main.scss

assets/sass/main.scss should then have a modified version of https://github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/_bootstrap.scss:

@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";
...

The file _variables.scss should also be copied to assets/sass.

(Note that the rest of the example file above is truncated) 🙈

🦄 Font awesome 🦄

https://fortawesome.github.io/Font-Awesome/ can be included with the snippet below:

$app->asset->process(
  "app.css" => (
    "https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css",
  )
);

Also see Mojolicious::Plugin::AssetPack::Pipe::Fetch for info about automatically fetching related font files. slay 💅

🍓 Google fonts 🍓

https://www.google.com/fonts can be included with this snippet:

$app->asset->process(
  "app.css" => (
    "https://fonts.googleapis.com/css?family=Roboto:400,700",
    "your-app.css",
  )
);

🧚 JavaScript polyfills 🧚

https://github.com/Modernizr/Modernizr contains a list of many shims which can be included. Here's just one example:

$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",
  )
);

💜 jQuery 💜

http://jquery.com can easily be included by referring to a CDN:

$app->asset->process(
  "app.js" => (
    "http://code.jquery.com/jquery-1.12.0.js",
    "your-app.js",
  )
);

🎀 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 @import files and download those recusively as well.

$ cat - > assets/assetpack.def
! app.css
< https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss
< https://fonts.googleapis.com/icon?family=Material+Icons

After that, you might want to customize Materialize. This can then be done by changing "assetpack.def" to:

! app.css
<< https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss
< https://fonts.googleapis.com/icon?family=Material+Icons
< sass/main.scss

assets/sass/main.scss should then have a modified version of https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss:

@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";
...

The file _variables.scss should also be copied to assets/sass.

(Note that the rest of the example file above is truncated) 🙈

👑 SEE ALSO 👑

go check out Mojolicious::Plugin::AssetPack, Mojolicious::Plugin::AssetPack::Guides::Developing and Mojolicious::Plugin::AssetPack::Guides::Tutorial.

💖 that's the whole cookbook, bestie — served fresh from perl v5.42.0, dated 2024-12-12. now go slay those assets 💅✨