The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Mojolicious::Plugin::AssetPack::Guides::Cookbook - AssetPack recipes

OVERVIEW

This guide will provide recipes for cooking with Mojolicious::Plugin::AssetPack.

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:

  • 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 requests 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).

Synopsis

You need to customize "route" in Mojolicious::Plugin::AssetPack to accomplish this:

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

Caveat

Many recent browsers blocks 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 will tell the browser to use the same scheme for fetching assets, as it did fetching the web page.

See also

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

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.

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

See also Mojolicious::Plugin::AssetPack::Pipe::Fetch for information about automatically fetching related font files.

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 is 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 refering 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

Mojolicious::Plugin::AssetPack and Mojolicious::Plugin::AssetPack::Guides::Tutorial.