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

1Mojolicious::Plugin::AsUsseetrPaCMcooknj:to:rlGiiubciuidtoeeusds:::P:TePurltluogrDiionac:lu:(mA3es)nsteattPiaocnk::Guides::Tutorial(3)
2
3
4

NAME

6       Mojolicious::Plugin::AssetPack::Guides::Tutorial - AssetPack tutorial
7

OVERVIEW

9       This guide will give detailed information about how to define assets
10       and include them into your templates.
11
12       See "DESCRIPTION" in Mojolicious::Plugin::AssetPack for a short
13       description of AssetPack.
14

GUIDE

16   Loading the plugin
17       The plugin needs to be installed an loaded before any assets can be
18       defined:
19
20         $app->plugin(AssetPack => \%args);
21
22       Details about %args can be found under "register" in
23       Mojolicious::Plugin::AssetPack, but there is one mandatory argument
24       worth noting: "pipes". "pipes" need to be a list of all the pipes you
25       need to process your assets. Example:
26
27         $app->plugin(AssetPack => {pipes => [qw(Sass Css Combine)]});
28
29       Loading the plugin with the list above will enable AssetPack to process
30       Sass and Css files, minify them and combine them into a single asset in
31       production.
32
33   Optional dependencies
34       AssetPack has only optional dependencies. The reason for that is that
35       the dependencies should only be required while developing, and not for
36       running the application. See
37       <https://github.com/jhthorsen/mojolicious-plugin-assetpack/blob/v2/cpanfile>
38       for a complete list, but here are the current list:
39
40       • CSS::Minifier::XS 0.09
41
42         Used to minify CSS.
43
44       • CSS::Sass 3.3.0
45
46         Used to process and minify CSS.
47
48       • Imager::File::PNG 0.90
49
50         TODO: Used to generate CSS sprites.
51
52       • JavaScript::Minifier::XS 0.11
53
54         Used to minify JavaScript.
55
56   Pipes
57       AssetPack does not do any heavy lifting itself: All the processing is
58       left to the pipe objects.
59
60       • Mojolicious::Plugin::AssetPack::Pipe::CoffeeScript
61
62         Process CoffeeScript coffee files. Should be loaded before
63         Mojolicious::Plugin::AssetPack::Pipe::JavaScript.
64
65       • Mojolicious::Plugin::AssetPack::Pipe::Combine
66
67         Combine multiple assets to one. Should be loaded last.
68
69       • Mojolicious::Plugin::AssetPack::Pipe::Css
70
71         Minify CSS.
72
73       • Mojolicious::Plugin::AssetPack::Pipe::Favicon
74
75         There is a special topic called "favicon.ico", combined with the
76         Mojolicious::Plugin::AssetPack::Pipe::Favicon pipe which can be used
77         to describe favicons, touch icons and tile icons.
78
79       • Mojolicious::Plugin::AssetPack::Pipe::Fetch
80
81         Will look for "url(...)" in CSS files and download the related
82         assets.
83
84       • Mojolicious::Plugin::AssetPack::Pipe::JavaScript
85
86         Minify JavaScript.
87
88       • Mojolicious::Plugin::AssetPack::Pipe::Jpeg
89
90         Used to crush "jpeg" image files.
91
92       • Mojolicious::Plugin::AssetPack::Pipe::Less
93
94         Process Less CSS files. Should be loaded before
95         Mojolicious::Plugin::AssetPack::Pipe::Css.
96
97       • Mojolicious::Plugin::AssetPack::Pipe::Png
98
99         Used to crush "png" image files.
100
101       • Mojolicious::Plugin::AssetPack::Pipe::Riotjs
102
103         Process <http://riotjs.com/> tag files. Should be loaded before
104         Mojolicious::Plugin::AssetPack::Pipe::JavaScript.
105
106       • Mojolicious::Plugin::AssetPack::Pipe::Sass
107
108         Process sass and scss files. Should be loaded before
109         Mojolicious::Plugin::AssetPack::Pipe::Css.
110
111   Where to place source files
112       The source/input files that make up a virtual asset (topic) can come
113       from either...
114
115       On disk
116
117       AssetPack will look for source files in the "assets" directory,
118       relative to the application home. Unlike the "public" directory, this
119       directory is not shared on the internet, but the generated assets will
120       still be available thanks to a custom route.
121
122       Mojolicious::Plugin::AssetPack::Store is a sub class of
123       Mojolicious::Static, allowing it to find files relative to "paths" in
124       Mojolicious::Static. For example, to change asset search paths, you can
125       do:
126
127           $app->asset->store->paths(["/some/new/location", "/other/location"]);
128
129       DATA section
130
131       Mojolicious::Plugin::AssetPack::Store is a sub class of
132       Mojolicious::Static, allowing it to look for files in DATA sections of
133       "classes" in Mojolicious::Static.
134
135       The DATA section can also be used to lookup "@import" files. (Currently
136       only supported by Mojolicious::Plugin::AssetPack::Pipe::Sass)
137
138       Web
139
140       Any file starting with "http" or "https" will be downloaded from web
141       using "ua" in Mojolicious::Plugin::AssetPack.
142
143       It will also parse recursively "@import" files and download those as
144       well.  (Currently only supported by
145       Mojolicious::Plugin::AssetPack::Pipe::Sass)
146
147       Assets from web will be cached locally to prevent downloading new and
148       untested assets on each application startup.
149
150       Current Mojolicious application
151
152       See "DYNAMIC ASSETS" in Mojolicious::Plugin::Assets::Guides::Cookbook.
153
154   Process assets
155       Assets should be defined when you application starts. This can either
156       be done using a definition file or inside you application.
157
158       Defining assets in the application
159
160       Assets can be defined using the "process" in
161       Mojolicious::Plugin::AssetPack method:
162
163         $app->asset->process(
164           "app.css" => (
165             "sass/bar.scss",
166             "foo/bar.css",
167             "https://github.com/Dogfalo/materialize/blob/master/sass/materialize.scss",
168           )
169         );
170
171       In the example above we have defined a topic named "app.css" which
172       later can be included in templates. The list of files following are the
173       source files which will make up the final asset.
174
175       Defining assets in a definition file
176
177       Moving the definition to an external file can be useful for keeping the
178       application code tidy. The definition file should be located in the
179       assets directory, or optionally defined it in the "DATA" section. The
180       default file is called "assetpack.def" and will be looked up if
181       "process" in Mojolicious::Plugin::AssetPack is called without
182       arguments. Example file:
183
184         ! app.css
185         < sass/bar.scss
186         << https://github.com/Dogfalo/materialize/blob/master/sass/materialize.scss
187         < sass/main.scss
188
189       Empty lines and lines starting with "#" will be skipped. Each line
190       starting with "!" will be used to define a topic (virtual asset name),
191       and "<" will define a source file. This means that the file above will
192       result in (almost) the same as in the example above.
193
194       The idea of the line starting with "<<" is to download an external
195       (remote) file for your convenience, which can be imported in your
196       SASS/LESS files. The downloaded file is not included in the output
197       asset. For example, you have "sass/main.scss" which depends on
198       "materialize.scss" (remote file) and you need this "materialize.scss"
199       file locally available to be imported in "sass/main.scss".  If you want
200       to include a remote file in your output asset, use '<' insteaf of '<<'.
201
202       It is also possible to add conditions:
203
204         ! app.css
205         < development.css [mode==development] [minify==0]
206         < production.css  [mode!=development]
207
208       "development.css" will be processed if "mode" in Mojolicious is
209       "development" and "minify" in Mojolicious::Plugin::AssetPack is "0".
210       "production.css" will be processed if "mode" in Mojolicious is
211       something else than "development". This is especially useful if you
212       want to include a JavaScript with debug flags set while developing, but
213       switch to a smaller version without debug in production.
214
215   Using assets
216       Any processed asset can be accessed by referring to a topic.
217
218       Template
219
220       An asset can be included in a template using the "asset" in
221       Mojolicious::Plugin::AssetPack helper:
222
223         <head>
224           %= asset "app.css"
225           %= asset "app.js"
226         </head>
227
228       The "asset" in Mojolicious::Plugin::AssetPack helper takes additional
229       arguments which will be passed on directly to either the "javascript"
230       in Mojolicious::Plugin::TagHelpers helper or "stylesheet" in
231       Mojolicious::Plugin::TagHelpers helper. Example:
232
233           %= asset "app.css", media => "print"
234
235       In production mode, the helper above will just result in one "link"
236       tag. On the other hand, if you are in "development" mode, it will
237       result in on "link" tag per source asset.
238
239       Asset objects
240
241       It is also possible to retrieve the processed asset objects. The
242       example below will retrieve a Mojo::Collection object holding zero or
243       more Mojolicious::Plugin::AssetPack::Asset objects:
244
245         my $collection = $app->asset->processed("app.css");
246         print $collection->map("checksum")->join(", ");
247
248       This can also be used to inline assets in a template:
249
250         %= stylesheet sub { asset->processed('app.css')->map('content')->join }
251
252   Application mode
253       The application mode will define if the assets should be combined and
254       minified. The "minify" in Mojolicious::Plugin::AssetPack attribute can
255       also be set manually if you have special needs.
256
257       Development
258
259       The assets will be processed, but not minified/combined if MOJO_MODE or
260       "mode" in Mojolicious is set to "development". This is to make it
261       easier to map JavaScript or CSS bugs to a specific file and line.
262       "development" is the default mode while running morbo:
263
264         $ morbo -w assets/ -w lib/ -w templates/ script/myapp
265
266       Any other mode
267
268       Any "production" mode will result in one combined and minified asset.
269       This will save bandwidth and roundtrip time to the server.
270
271   Caching
272       Processed assets will be cached to disk when possible. The process step
273       is run so if such a processed asset exists, the process step will not
274       be run again.  Again, the external tools (less, coffee, ...) and
275       modules (JavaScript::Minifier::XS, CSS::Sass) will only be required
276       while developing, but can be skipped when installing an already built
277       application.
278
279   Assets without topics
280       One nifty feature is to use Mojolicious::Plugin::AssetPack for assets
281       which do not have any pipe to process them. The reason why this comes
282       in handy is to avoid cache issues, since changing the file on disk will
283       generate a new URL.
284
285       These assets can also be defined directly in the templates, without
286       having to be defined in the application startup process. Examples:
287
288         # <img src="/asset/52e98718f0/foo.gif">
289         %= asset "/image/foo.gif"
290
291         # <img src="/asset/87652910af/baz.svg">
292         %= asset "/image/baz.svg"
293
294         # <link rel="icon" href="/asset/65428718f1/bar.ico">
295         %= asset "/image/bar.ico"
296
297         # <source src="/asset/87652718f0/baz.mp3" type="audio/mpeg">
298         %= asset "/audio/baz.mp3"
299
300         # <source src="/asset/52e87652f0/foo.mp4" type="video/mp4">
301         %= asset "/video/foo.mp4"
302
303         # <source src="/asset/52eaz7613a/bar.ogg" type="audio/ogg">
304         %= asset "/audio/bar.ogg"
305
306         # <source src="/asset/baf72618f1/foo.ogv" type="audio/ogv">
307         %= asset "/video/foo.ogv"
308
309         # <source src="/asset/92118711f0/bar.webm" type="audio/webm">
310         %= asset "/video/bar.webm"
311

NAME

OVERVIEW

GUIDE

SEE ALSO