Mojolicious::Plugin::AssetPack::Guides::Cookbook(3pm)

1Mojolicious::Plugin::AsUsseetrPaCMcooknj:to:rlGiiubciuidtoeeusds:::P:CePorlolukgbDioonoc:ku:(mA3es)nsteattPiaocnk::Guides::Cookbook(3)
2
3
4

NAME

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

OVERVIEW

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

ASSETS FROM CUSTOM DOMAIN

13       You might want to serve the assets from a domain different from where
14       the main app is running. The reasons for that might be:
15
16       • No cookies send on each request. This is especially useful when you
17         use Mojolicious sessions as they are stored in cookies and clients
18         send whole session with every request.
19
20       • More requests done in parallel. Browsers have limits for sending
21         parallel request to one domain. With separate domain static files can
22         be loaded in parallel.
23
24       • Serve files directly (by absolute url) from CDN (or Amazon S3).
25
26   Synopsis
27       You need to customize "route" in Mojolicious::Plugin::AssetPack to
28       accomplish this:
29
30         $app->asset->route->to(base_url => "http://cdn.example.com/my-assets/");
31
32   Caveat
33       Many recent browsers blocks mixed content, meaning if your HTML is
34       served over HTTPS, then you can't serve the assets over HTTP. One way
35       to fix this is by using "//" instead of a scheme specific URL. Example:
36
37         base_url => "//cdn.example.com/my-assets/"
38
39       This will tell the browser to use the same scheme for fetching assets,
40       as it did fetching the web page.
41
42   See also
43       <https://developers.google.com/speed/docs/best-practices/request#ServeFromCookielessDomain>.
44

DYNAMIC ASSETS

46       Any web asset with the hostname "local" will be routed to the current
47       Mojolicious application.  Example:
48
49         $ cat assetpack.def
50         ! app.js
51         < http://local/some/resource.js
52
53       The above URL will make AssetPack issue a request to the current
54       Mojolicious application, allowing it to render dynamic JavaScript.
55       Example Mojolicious resource:
56
57         get "/some/resource" => [format => "js"], sub {
58           my $c = shift;
59           $c->render(text => sprintf "rand = %s\n", rand);
60         };
61
62   Sass
63       Sass files can also be generated dynamically. Here is an example Sass
64       file:
65
66         @import "http://local/sass/dynamic";
67         $color: red !default;
68         body { color: $color; }
69
70       Normally, the @import statement would be left untouched, but AssetPack
71       will (in the special case where the host is "local") inline the result
72       from that resource. This allow $color to be set from the application
73       and override the default $color in the file above. Example:
74
75         get "/sass/_dynamic" => [format => "scss"], sub {
76           my $c = shift;
77           $c->render(text => "\$color: black;\n");
78         };
79
80       Note that this feature is EXPERIMENTAL and not compatible with standard
81       Sass rules.
82

ONLINE ASSETS

84       Instead of making custom AssetPack plugins, it is possible to simply
85       include projects such as Bootstrap, FontAwesome or jQuery directly from
86       the web instead.
87
88   Bootstrap
89       The SASS version of <http://getbootstrap.com> can easily be included by
90       defining it in the assetspack.def file:
91
92         $ cat - > assets/assetpack.def
93         ! app.css
94         < https://github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/_bootstrap.scss
95
96       After that, you might want to customize bootstrap. This can then be
97       done by changing "assetpack.def" to:
98
99         ! app.css
100         << https://github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/_bootstrap.scss
101         < sass/main.scss
102
103       "assets/sass/main.scss" should then have a modified version of
104       <https://github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/_bootstrap.scss>:
105
106         @import "variables.scss";
107         @import "../cache/github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/bootstrap/mixins";
108         @import "../cache/github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/bootstrap/normalize";
109         @import "../cache/github.com/twbs/bootstrap-sass/raw/master/assets/stylesheets/bootstrap/print";
110         ...
111
112       The file "_variables.scss" should also be copied to "assets/sass".
113
114       (Note that the rest of the example file above is truncated)
115
116   Font awesome
117       <https://fortawesome.github.io/Font-Awesome/> can be included with the
118       snippet below:
119
120         $app->asset->process(
121           "app.css" => (
122             "https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css",
123           )
124         );
125
126       See also Mojolicious::Plugin::AssetPack::Pipe::Fetch for information
127       about automatically fetching related font files.
128
129   Google fonts
130       <https://www.google.com/fonts> can be included with this snippet:
131
132         $app->asset->process(
133           "app.css" => (
134             "https://fonts.googleapis.com/css?family=Roboto:400,700",
135             "your-app.css",
136           )
137         );
138
139   JavaScript polyfills
140       <https://github.com/Modernizr/Modernizr> contains a list of many shims
141       which can be included. Here is just one example:
142
143         $app->asset->process(
144           "app.js" => (
145             "http://cdnjs.cloudflare.com/ajax/libs/es5-shim/2.3.0/es5-shim.js",
146             "http://cdnjs.cloudflare.com/ajax/libs/es5-shim/2.3.0/es5-sham.js",
147             "your-app.js",
148           )
149         );
150
151   jQuery
152       <http://jquery.com> can easily be included by referring to a CDN:
153
154         $app->asset->process(
155           "app.js" => (
156             "http://code.jquery.com/jquery-1.12.0.js",
157             "your-app.js",
158           )
159         );
160
161   Materialize CSS
162       <http://materializecss.com/> can be included by defining it in the
163       assetspack.def file. Mojolicious::Plugin::AssetPack::Pipe::Sass will
164       also discover all the "@import" files and download those recusively as
165       well.
166
167         $ cat - > assets/assetpack.def
168         ! app.css
169         < https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss
170         < https://fonts.googleapis.com/icon?family=Material+Icons
171
172       After that, you might want to customize Materialize. This can then be
173       done by changing "assetpack.def" to:
174
175         ! app.css
176         << https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss
177         < https://fonts.googleapis.com/icon?family=Material+Icons
178         < sass/main.scss
179
180       "assets/sass/main.scss" should then have a modified version of
181       <https://raw.githubusercontent.com/Dogfalo/materialize/master/sass/materialize.scss>:
182
183         @charset "UTF-8";
184         @import "../cache/raw.githubusercontent.com/Dogfalo/materialize/master/sass/components/prefixer";
185         @import "../cache/raw.githubusercontent.com/Dogfalo/materialize/master/sass/components/mixins";
186         @import "../cache/raw.githubusercontent.com/Dogfalo/materialize/master/sass/components/color";
187         @import "variables.scss";
188         ...
189
190       The file "_variables.scss" should also be copied to "assets/sass".
191
192       (Note that the rest of the example file above is truncated)
193

NAME

OVERVIEW

ASSETS FROM CUSTOM DOMAIN

DYNAMIC ASSETS

ONLINE ASSETS

SEE ALSO