-
Notifications
You must be signed in to change notification settings - Fork 65
/
Copy pathdocumentation.scala.html
832 lines (696 loc) · 47.2 KB
/
documentation.scala.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
@this(main: main)
@main("WebJars - Documentation") {
<script>
$(function() {
var frameworkTabs = $('#framework-tabs');
frameworkTabs.find('a').click(function (e) {
e.preventDefault();
$(this).tab('show');
var id = $(e.target).attr("href").substr(1);
window.history.pushState(null, null, '#' + id);
});
frameworkTabs.find('a[href="' + window.location.hash + '"]').tab('show');
});
</script>
<div class="jumbotron" style="margin-bottom: 20px;">
<div class="container">
<h4><strong>WebJars work with most JVM-based containers and web frameworks. Using a WebJar requires:</strong></h4>
<ol>
<li>The WebJar needs to be a dependency of your application</li>
<li>The WebJar needs to be in your application's running CLASSPATH</li>
<li>Your container, web framework, or application needs to serve static assets from Jar files</li>
</ol>
<h4 style="padding-top: 15px;">Public CDN via <a href="http://www.jsdelivr.com" target="_blank">jsDelivr</a></h4>
All of the WebJar contents are available on the public <a href="http://www.jsdelivr.com" target="_blank">jsDelivr</a> CDN.
Just prefix <code>//cdn.jsdelivr.net/webjars/{groupId}</code> in front of your static asset URLs. For instance, if using the <code>org.webjars : jquery</code> WebJar and your local URL to <code>jquery.js</code> is <code>/webjars/jquery/2.1.0/jquery.js</code> then the CDN URL would be: <code>//cdn.jsdelivr.net/webjars/org.webjars/jquery/2.1.0/jquery.js</code>
</div>
</div>
<div class="alert alert-warning" role="alert" style="margin-left: 15px; margin-right: 15px;">
Help improve these docs! <a href="https://github.com/webjars/webjars/blob/master/app/views/documentation.scala.html">Documentation Source</a> | <a href="https://github.com/webjars/webjars/issues/new">Create an Issue</a>
</div>
<div style="padding-left: 15px; padding-right: 15px;">
<div class="row">
<div class="col-sm-3 col-md-2">
<ul id="framework-tabs" class="nav nav-pills nav-stacked">
<li class="active"><a href="#play2" data-toggle="tab">Play Framework 2</a></li>
<li><a href="#xitrum" data-toggle="tab">Xitrum</a></li>
<li><a href="#servlet3" data-toggle="tab">Servlet 3</a></li>
<li><a href="#servlet2" data-toggle="tab">Servlet 2</a></li>
<li><a href="#jsf" data-toggle="tab">JSF</a></li>
<li><a href="#grails" data-toggle="tab">Grails</a></li>
<li><a href="#dropwizard" data-toggle="tab">Dropwizard</a></li>
<li><a href="#springboot" data-toggle="tab">Spring Boot</a></li>
<li><a href="#springmvc" data-toggle="tab">Spring MVC</a></li>
<li><a href="#tapestry" data-toggle="tab">Apache Tapestry</a></li>
<li><a href="#wicket" data-toggle="tab">Apache Wicket</a></li>
<li><a href="#pippo" data-toggle="tab">Pippo</a></li>
<li><a href="#ring" data-toggle="tab">Ring (Clojure)</a></li>
<li><a href="#dandelion" data-toggle="tab">Dandelion</a></li>
<li><a href="#vertx" data-toggle="tab">Vert.x Web</a></li>
<li><a href="#quarkus" data-toggle="tab">Quarkus</a></li>
</ul>
</div>
<div class="col-sm-9 col-md-10 tab-content">
<!-- Play Framework 2 -->
<div class="tab-pane active" id="play2">
<h3>Instructions for Play 2.6 (<a href="https://github.com/webjars/sample-play2">Sample Source</a>)</h3>
WebJars can be added as dependencies to an app by simply adding them to the <span class="label label-info">build.sbt</span> file like:<br>
<pre><code>libraryDependencies += "org.webjars" % "bootstrap" % "3.1.1-2"</code></pre>
<br>
Play automatically extracts the WebJar contents and makes them available via the <span class="label label-info">Assets</span> controller. So, if you have a route like:
<pre><code>GET /assets/*file controllers.Assets.at(path="/public", file)</code></pre>
<br/>
Then a WebJar file like <code>bootstrap.css</code> is available at:
<pre><code>/assets/lib/bootstrap/css/bootstrap.css</code></pre>
<br/>
There is also a helper library named <span class="label label-info">webjars-play</span> that makes it easy to reference WebJar assets. Here is an example <span class="label label-info">build.sbt</span> file with <span class="label label-info">webjars-play</span> and the <span class="label label-info">bootstrap</span> WebJar as dependencies:<br>
<pre><code>libraryDependencies ++= Seq(
"org.webjars" %% "webjars-play" % "2.6.3",
"org.webjars" % "bootstrap" % "3.1.1-2"
)</code></pre>
<br>
After changing the dependencies you will need to restart Play.<br>
<br>
The <span class="label label-info">webjars-play</span> helper library has a wrapper around the Play Static Asset Controller that can locate and serve WebJar assets. A new route import needs to be added to the <span class="label label-info">conf/routes</span> file:
<pre><code>-> /webjars webjars.Routes</code></pre>
<br>
The <span class="label label-info">org.webjars.play.WebJarsUtil</span> class has a number of helpful methods for locating and loading assets. <a href="https://javadoccentral.herokuapp.com/org.webjars/webjars-play_2.12/2.6.3/org/webjars/play/WebJarsUtil.html">Check out the JavaDoc</a>. To use it you need to inject an instance of <span class="label label-info">WebJarsUtil</span> - usually into a template. For example:
<pre><code>@@this(webJarsUtil: org.webjars.play.WebJarsUtil)
... HTML page ...
@@webJarsUtil.locate("bootstrap.min.css").css()
@@webJarsUtil.locate("bootstrap.min.js").script()</code></pre>
<br/>
WebJars have out-of-the-box support for RequireJS. To use it in a template, call the <span class="label label-info">webJarsUtil.requireJs</span> method with a reverse route to the main JavaScript app:
<pre><code>@@webJarsUtil.requireJs(routes.Assets.versioned("javascripts/index.js"))</code></pre>
<br/>
If you need to override the default RequireJS config you can use a lower-level <code>RequireJS</code> API to setup the config, for example:
<pre><code><script>
var require = {
callback: function() {
// default requirejs configs
@@for(webJarJson <- org.webjars.RequireJS.getSetupJson(routes.WebJarAssets.at("").url).values()) {
@@if(webJarJson != null) {
requirejs.config(@@Html(webJarJson.toString));
}
}
// example custom requirejs config
requirejs.config({
paths: {
jquery: "//code.jquery.com/jquery-1.11.1.min"
},
shim: {
bootstrap: []
}
});
}
};
</script>
@@webJarsUtil.locate("requirejs", "require.min.js").script(Map("data-main" -> routes.Assets.versioned("javascripts/index.js").url))</code></pre>
<br>
You can load WebJar assets from a CDN by setting the following config:<br>
<pre><code>webjars.use-cdn=true
play.filters.headers.contentSecurityPolicy = "default-src 'self' https://cdn.jsdelivr.net"</code></pre>
</div>
<!-- Xitrum -->
<div class="tab-pane" id="xitrum">
<h3>Instructions for Xitrum</h3>
<p><a href="http://xitrum-framework.github.io/">Xitrum</a>
from 3.13 has <a href="http://xitrum-framework.github.io/guide/static.html#serve-resource-files-in-classpath-with-webjars-convention">built-in</a>
support for WebJars. If you have a dependency like this:</p>
<pre><code>libraryDependencies += "org.webjars" % "underscorejs" % "1.6.0-3"</code></pre>
<p>In you <a href="http://scalate.fusesource.org/">Scalate</a>
view template file, you can write like this (the below examples
use <a href="http://scalate.fusesource.org/documentation/jade.html">Jade</a>
syntax):</p>
<pre><code>script(src={webJarsUrl("underscorejs/1.6.0", "underscore.js", "underscore-min.js")})</code></pre>
<p>Xitrum will automatically use <code>underscore.js</code> for
development environment and <code>underscore-min.js</code> for
production environment.</p>
<p>The result will look like this:</p>
<pre><code><script src="/webjars/underscorejs/1.6.0/underscore.js?XOKgP8_KIpqz9yUqZ1aVzw"></script></code></pre>
<p>If you want to use the same file for both environments:</p>
<pre><code>script(src={webJarsUrl("underscorejs/1.6.0/underscore.js")})</code></pre>
<p>For examples, see
<a href="https://github.com/xitrum-framework/xitrum-new">xitrum-new</a>
and
<a href="https://github.com/xitrum-framework/xitrum-demos">xitrum-demos</a>
(<a href="http://ec2-54-249-135-186.ap-northeast-1.compute.amazonaws.com:8151/">online</a>).</p>
</div>
<!-- Servlet 3 -->
<div class="tab-pane" id="servlet3">
<h3>Instructions for Servlet 3</h3>
With any Servlet 3 compatible container, the WebJars that are in the <span class="label label-info">WEB-INF/lib</span> directory are automatically made available as static resources. This works because anything in a <span class="label label-info">META-INF/resources</span> directory in a JAR in <span class="label label-info">WEB-INF/lib</span> is automatically exposed as a static resource. Please note that in case of Tomcat the JarScanner should not be configured to skip the WebJars (e.g. when jarsToSkip is set to * add the WebJars to jarsToScan).
<h4>Maven Example (<a href="https://github.com/webjars/sample-jetty_war">example app</a>)</h4>
First add a WebJar as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
Then simply reference the resource like:
<pre><code><link rel='stylesheet' href='webjars/bootstrap/3.1.0/css/bootstrap.min.css'></code></pre>
<h4>Making dependencies version agnostic</h4>
Use the WebjarsServlet to make dependencies version agnostic, see Servlet 2.
</div>
<!-- Servlet 2 -->
<div class="tab-pane" id="servlet2">
<h3>Instructions for Servlet 2</h3>
WebjarsServlet allows Webjars resources to be referenced in legacy apps that are still running on Servlet containers that are not compliant with the Servlet 3 specification (e.g. Tomcat 6). It can also be used to make dependencies version agnostic in both Servlet 2 and Servlet 3 compatible containers.
<h4>Usage</h4>
<ol>
<li>
Register our webjars-servlet-2.x Maven dependency in your web application:
<pre><code><dependency>
<groupId>org.webjars</groupId>
<artifactId>webjars-servlet-2.x</artifactId>
<version>1.1</version>
</dependency></code></pre>
</li>
<li>
Register <strong>WebjarsServlet</strong> in your web.xml:
<pre><code><!--Webjars Servlet-->
<servlet>
<servlet-name>WebjarsServlet</servlet-name>
<servlet-class>org.webjars.servlet.WebjarsServlet</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>WebjarsServlet</servlet-name>
<url-pattern>/webjars/*</url-pattern>
</servlet-mapping></code></pre>
</li>
</ol>
By default the Webjars resources will be cached by your browser. If for whatever reason you need to disable the cache, you can do so by using the <strong>disableCache</strong> configuration property like this:
<pre><code><!--Webjars Servlet-->
<servlet>
<servlet-name>WebjarsServlet</servlet-name>
<servlet-class>org.webjars.servlet.WebjarsServlet</servlet-class>
<init-param>
<param-name>disableCache</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet></code></pre>
It is off course also possible to instantiate the WebjarsServlet programmatically (e.g. with Spring Boot's ServletRegistrationBean).
<h4>Making dependencies version agnostic</h4>
When using WebjarsServlet version 1.6 or higher, it will automatically detect the <code>webjars-locator-core</code> library on the classpath and use it to automatically resolve the version of any WebJar assets for you.
In order to enable this feature, you will need to add the webjars-locator-core library as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>webjars-locator-core</artifactId>
<version>0.48</version>
</dependency>
</dependencies></code></pre>
<br>
Then you may reference a WebJar asset in your template like this:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'></code></pre>
<br>
<div class="alert alert-danger" role="alert">Be sure to remove <strong>ONLY</strong> the version from the path, otherwise relative imports may not work.</div>
<br>
</div>
<!-- JSF -->
<div class="tab-pane" id="jsf">
<h3>Instructions for JSF</h3>
With JSF, the WebJars that are in the <span class="label label-info">WEB-INF/lib</span> directory are automatically made available as resource libraries. This works because WebJars are compatible with the JSF resource identifier format.<br>
<br>
<a href="http://www.mkyong.com/jsf2/resources-library-in-jsf-2-0/">More Information about JSF resources</a>
<h4>Maven Example (<a href="https://github.com/arend-von-reinersdorff/samplejsfwithwebjars">example app</a>)</h4>
First add a WebJar as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
Then simply reference the resource like:
<pre><code><h:outputStylesheet library="webjars" name="bootstrap/3.1.0/css/bootstrap.min-jsf.css" />
<h:outputScript library="webjars" name="jquery/1.11.2/jquery.js" /></code></pre>
</div>
<!-- Grails -->
<div class="tab-pane" id="grails">
<h3>Instructions for Grails (<a href="https://github.com/webjars/sample-grails">example app</a>)</h3>
Grails manages static resources (such as javascript and css files) with the resources plugin. The resources plugin manages static resources via modules, like the Jquery Module, that define via a config file which static resources a module requires. For a more details explanation see the <a href="http://grails.org/doc/latest/guide/theWebLayer.html#resources">Grails docs on using Static Resource</a>.
<br><br>The <a href="https://github.com/groovydev/modules-manager-grails-plugin">Grails Modules Manager plugin</a> allows dependencies on web libraries to be declared in the Grails build configuration file, <span class="label label-info">BuildConfig.groovy</span>. It resolves theses dependencies and creates modules that can be used by the resources plugin. It does this by downloading the jar files from webjars.org and extracting the web libraries from the jar files. It then creates grails specific resource modules from these web libraries.
</br><h4>Steps for using the plugin:</h4>
<ul>
<li>Clone the modules manager plugin from
<pre><code>https://github.com/groovydev/modules-manager-grails-plugin.git</code></pre>
</li>
<br>
<li>Build the plugin:
<pre><code>grails package-plugin</code></pre>
</li>
<br>
<li>Install the plugin into your grails project from the file system - this assumes the plugin is in
the same parent directory as the project:
<pre><code>grails install-plugin ../modules-manager-grails-plugin/grails-modules-manager-0.2.1.zip</code></pre>
</li>
<br>
<li>Define the javascript and css dependencies. In <span class="label label-info">grails-app/config/BuildConfig.groovy</span>
add:
<pre><code>dependencies {
compile 'org.webjars:bootstrap:3.1.0'
}</code></pre>
</li>
<br>
<li>Run the refresh modules command which will download the necessary javascript and css dependencies:
<pre><code>grails refresh-modules</code></pre>
</li>
<br>
<li>Notice how the plugin added the file <span class="label label-info">conf/ModulesBootstrapResources.groovy</span>. This module config file is used by the resources plugin to define the module dependencies and static resources.
</li>
<br>
<li>Add the module dependencies to the web page (see the example in <a href="https://github.com/webjars/sample-grails/blob/master/grails-app/views/index.gsp">views/index.gsp</a>). This is done by adding the require tag to the html page to include the static resource modules. Also note that it is necessary to add the layoutResources tag twice to the page.
<br></br>In the head tag add:
<pre><code><head>
<r:require modules="jquery, bootstrap"/>
<r:layoutResources/></code></pre>
</br>And then at the bottom of the page right before the body add:
<pre><code><r:layoutResources/>
</body></code></pre>
</li>
<br>
<li>The resource manager then optimizes when the javascript is load by when it is need in the page and by default includes the javascript at the bottom of the page. For this reason it is necessary to put the javascript in a <r:script> tag so that the necessary dependencies will be included when the layoutResources tag is called. For example to use a jquery initialization function add the following to the page:
<pre><code><r:script>
$(function (){ ... } </code></pre>
</li>
</ul>
</div>
<!-- Dropwizard -->
<div class="tab-pane" id="dropwizard">
<h3>Instructions for Dropwizard (<a href="https://github.com/webjars/sample-dropwizard">example app</a>)</h3>
With Dropwizard you can easily expose WebJars through the <span class="label label-info">AssetsBundle</span>. In your startup service's constructor setup the <span class="label label-info">AssetsBundle</span> to map static asset requests in a <span class="label label-info">/META-INF/resources/webjars</span> directory in JARs on the CLASSPATH to the <span class="label label-info">/webjars</span> URL, for example:
<pre><code>package org.webjars;
import com.yammer.dropwizard.Service;
import com.yammer.dropwizard.bundles.AssetsBundle;
import com.yammer.dropwizard.config.Configuration;
import com.yammer.dropwizard.config.Environment;
public class MainService extends Service<Configuration> {
public static void main(String[] args) throws Exception {
new MainService().run(args);
}
private MainService() {
super("sample-dropwizard");
addBundle(new AssetsBundle("/META-INF/resources/webjars", 0, "/webjars"));
}
}</code></pre>
<br>
Now you can reference a WebJar asset like:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'></code></pre>
</div>
<!-- Spring Boot -->
<div class="tab-pane" id="springboot">
<h3>Instructions for Spring Boot (<a href="https://github.com/webjars/sample-spring_boot">example app</a>)</h3>
Spring Boot automatically configures Spring to map requests for <span class="label label-info">/webjars</span> to the <span class="label label-info">/META-INF/resources/webjars</span> directory of all the JARs in the CLASSPATH.
<br>
<h4>Maven Example</h4>
First add a WebJar as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
Then reference a WebJar asset like:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'></code></pre>
<h4>Making dependencies version agnostic</h4>
When using Spring Boot, it will automatically detect the <code>webjars-locator-core</code> library on the classpath and use it to automatically resolve the version of any WebJar assets for you.
In order to enable this feature, you will need to add the webjars-locator-core library as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>webjars-locator-core</artifactId>
<version>0.48</version>
</dependency>
</dependencies></code></pre>
<br>
(Spring Boot manages the version if you use its BOM feature.) Then you may reference a WebJar asset in your template like this:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'></code></pre>
<br>
<div class="alert alert-danger" role="alert">Be sure to remove <strong>ONLY</strong> the version from the path, otherwise relative imports may not work.</div>
<br>
<div class="alert alert-danger" role="alert">Customising the web layer with `@@EnableWebMcv` or `@@EnableWebFlux` will result in disabling the static content mapping configured by Spring Boot, including the webjars handling. There are usually other extension points that you can use instead.</div>
<h4>Enhanced support for RequireJS</h4>
<a href="http://www.requirejs.org" target="_blank">RequireJS</a> is a popular implementation of the <a href="https://github.com/amdjs/amdjs-api/wiki/AMD">AMD</a>
specification - a means by which JavaScript applications can be modularised. The easiest way of thinking
about AMD is that it is JavaScript's equivalent of package and import statements (or namespace and
include statements depending on your preferences!). These instructions assume basic knowledge of
RequireJS.
<br><br>
The <span class="label label-info">webjars-locator</span> library has built-in support for RequireJS. To setup RequireJS use the <code>webjars-locator</code> library like this:
<pre><code>@@ResponseBody
@@RequestMapping(value = "/webjarsjs", produces = "application/javascript")
public String webjarjs() {
return RequireJS.getSetupJavaScript("/webjars/");
}</code></pre>
<span class="label label-success">Note</span> The <code>RequestMapping</code> must not be the same as given to the <code>ResourceHandler</code>
<br>
<span class="label label-success">Note</span> The url given to <code>getSetupJavaScript</code> has to be the url given to <code>ResourceHandler</code> and end with a <span>/</span>
<br><br>
This <code>RequestMapping</code> returns the setup code for your webjars and requirejs. It has to be included in your template before loading RequireJS. A basic setup looks like this:
<pre><code><script src="/webjarsjs"></script>
<script data-main="/js/app" src="/webjars/requirejs/require.min.js"></script></code></pre>
This loads the WebJars RequireJS configuration from <span class="label label-info">webjars-locator</span> and the RequireJS with a main JavaScript of <span class="label label-info">js/app</span>.
<br><br>
Underneath the covers each WebJar can have a RequireJS configuration file that sets up the modules, shims, exports, etc. These files is named <span class="label label-info">webjars-requirejs.js</span> and are automatically added to the page via the <code>RequireJS.setup</code> helper.
Some of the WebJars may not be updated to the new WebJars RequireJS syntax so if you experience problems please file issues on the WebJars you are using.
</div>
<!-- Spring MVC -->
<div class="tab-pane" id="springmvc">
<h3>Instructions for Spring MVC</h3>
Spring MVC makes it easy to expose static assets in JAR files using <span class="label label-info">ResourceHandlers</span>.
<h4>Maven Example (<a href="https://github.com/webjars/sample-jetty_war">example app</a>)</h4>
First add a WebJar as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
Then configure Spring to map requests for <span class="label label-info">/webjars</span> to the <span class="label label-info">/META-INF/resources/webjars</span> directory of all the JARs in the CLASSPATH. This can be done either via XML config:
<pre><code><mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/></code></pre>
<br>
<span class="label label-success">Note</span> In a Servlet 3 container this can be simplified to:
<pre><code><mvc:resources mapping="/webjars/**" location="/webjars/"/></code></pre>
<br>
Or Java config:
<pre><code>@@Configuration
@@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}</code></pre>
<br>
<span class="label label-success">Note</span> In a Servlet 3 container the <span class="label label-info">registry.addResourceHandler</span> line can be simplified to:
<pre><code>registry.addResourceHandler("/webjars/**").addResourceLocations("/webjars/");</code></pre>
<br>
Then reference a WebJar asset like:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'></code></pre>
<h4>Making dependencies version agnostic</h4>
When using Spring Framework version 4.2 or higher, it will automatically detect the <code>webjars-locator-core</code> library on the classpath and use it to automatically resolve the version of any WebJar assets for you.
In order to enable this feature, you will need to add the webjars-locator-core library as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>webjars-locator-core</artifactId>
<version>0.30</version>
</dependency>
</dependencies></code></pre>
<br>
And extend your XML config with a resource-chain element:
<pre><code><mvc:resources mapping="/webjars/**" location="/webjars/">
<mvc:resource-chain resource-cache="true"/>
</mvc:resources></code></pre>
<br>
Or in case of Java config add the resourceChain() method and the WebJarsResourceResolver:
<pre><code>registry.addResourceHandler("/webjars/**").addResourceLocations("/webjars/").setCachePeriod(CACHE_PERIOD).resourceChain(true).addResolver(new WebJarsResourceResolver());</code></pre>
<br>
Then you may reference a WebJar asset in your template like this:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'></code></pre>
<br>
<div class="alert alert-danger" role="alert">Be sure to remove <strong>ONLY</strong> the version from the path, otherwise relative imports may not work.</div>
<h4>Enhanced support for RequireJS</h4>
<a href="http://www.requirejs.org" target="_blank">RequireJS</a> is a popular implementation of the <a href="https://github.com/amdjs/amdjs-api/wiki/AMD">AMD</a>
specification - a means by which JavaScript applications can be modularised. The easiest way of thinking
about AMD is that it is JavaScript's equivalent of package and import statements (or namespace and
include statements depending on your preferences!). These instructions assume basic knowledge of
RequireJS.
<br><br>
The <span class="label label-info">webjars-locator</span> library has built-in support for RequireJS. To setup RequireJS use the <code>webjars-locator</code> library like this:
<pre><code>@@ResponseBody
@@RequestMapping(value = "/webjarsjs", produces = "application/javascript")
public String webjarjs() {
return RequireJS.getSetupJavaScript("/webjars/");
}</code></pre>
<span class="label label-success">Note</span> The <code>RequestMapping</code> must not be the same as given to the <code>ResourceHandler</code>
<br>
<span class="label label-success">Note</span> The url given to <code>getSetupJavaScript</code> has to be the url given to <code>ResourceHandler</code> and end with a <span>/</span>
<br><br>
This <code>RequestMapping</code> returns the setup code for your webjars and requirejs. It has to be included in your template before loading RequireJS. A basic setup looks like this:
<pre><code><script src="/webjarsjs"></script>
<script data-main="/js/app" src="/webjars/requirejs/require.min.js"></script></code></pre>
This loads the WebJars RequireJS configuration from <span class="label label-info">webjars-locator</span> and the RequireJS with a main JavaScript of <span class="label label-info">js/app</span>.
<br><br>
Underneath the covers each WebJar can have a RequireJS configuration file that sets up the modules, shims, exports, etc. These files is named <span class="label label-info">webjars-requirejs.js</span> and are automatically added to the page via the <code>RequireJS.setup</code> helper.
Some of the WebJars may not be updated to the new WebJars RequireJS syntax so if you experience problems please file issues on the WebJars you are using.
</div>
<!-- Apache Tapestry -->
<div class="tab-pane" id="tapestry">
<h3>Instructions for Apache Tapestry</h3>
Apache Tapestry makes it easy to expose static assets in JAR files using <span class="label label-info">contributeClasspathAssetAliasManager</span>.
<h4>Maven Example (<a href="https://github.com/webjars/sample-tapestry">example app</a>)</h4>
First add a WebJar as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
Then configure the <span class="label label-info">contributeClasspathAssetAliasManager</span> in your <span class="label label-info">AppModule</span> to look for assets in <span class="label label-info">META-INF/resources/webjars</span> directories:
<pre><code>public class AppModule {
public static void contributeClasspathAssetAliasManager(MappedConfiguration<String, String> configuration) {
configuration.add("webjars", "META-INF/resources/webjars");
}
}</code></pre>
<br>
Then simply reference WebJars assets in your Tapestry templates like:
<pre><code><link rel='stylesheet' media='screen'
href='${asset:classpath:/META-INF/resources/webjars/bootstrap/3.1.0/css/bootstrap.min.css}'></link>
<script type='text/javascript'
src='${asset:classpath:/META-INF/resources/webjars/jquery/1.9.0/jquery.min.js}'></script></pre></code>
</div>
<!-- Apache Wicket -->
<div class="tab-pane" id="wicket">
<h3>Instructions for Apache Wicket</h3>
The Wicket integration of Webjars uses a special <span class="label label-info">IResourceFinder</span> implementation to map
Webjars resources.
<h4>Maven Example (<a href="https://github.com/webjars/sample-wicket">example app</a>)</h4>
First you have to add wicket-webjars as dependency to your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>de.agilecoders.wicket.webjars</groupId>
<artifactId>wicket-webjars</artifactId>
<version>0.3.4</version>
</dependency>
</dependencies></code></pre>
<br>
And a WebJar dependency like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>jquery</artifactId>
<version>1.11.0</version>
</dependency>
</dependencies></code></pre>
<br>
Then configure your wicket application to map requests for <span class="label label-info">/webjars</span> and instances of
<span class="label label-info">IWebjarsResourceReference</span> to the <span class="label label-info">/META-INF/resources/webjars</span>
directory of all the JARs in the CLASSPATH. This can be done in <span class="label label-info">Application.init</span>:
<pre><code>/**
* @@see org.apache.wicket.Application#init()
*/
@@Override
public void init() {
super.init();
WicketWebjars.install(this);
}</code></pre>
<br>
Then simply reference the resource like:
<pre><code><link rel='stylesheet' href='/webjars/jquery/1.11.0/jquery.js'></code></pre>
<br>
Or add a <span class="label label-info">Webjars*ResourceReference</span> to your component:
<pre><code>@@Override
public void renderHead(IHeaderResponse response) {
super.renderHead(response);
response.render(JavaScriptHeaderItem.forReference(
new WebjarsJavaScriptResourceReference("jquery/1.11.0/jquery.js")));
}
</code></pre>
<br>
To always use the most recent version of a WebJar asset, simply replace the version in path with
the <span class="label label-info">"current"</span> string. When a resource name is resolved this string will be replaced with the most recent available version in classpath:
<pre><code>@@Override
public void renderHead(IHeaderResponse response) {
super.renderHead(response);
// current will be replaced with "1.11.0"
response.render(JavaScriptHeaderItem.forReference(
new WebjarsJavaScriptResourceReference("jquery/current/jquery.js")));
}
</code></pre>
</div>
<!-- Pippo -->
<div class="tab-pane" id="pippo">
<h3>Instructions for Pippo</h3>
The <a href="http://www.pippo.ro">Pippo</a> integration of Webjars is pretty straightforward.
<h4>Maven Example (<a href="https://github.com/decebals/pippo-demo/tree/master/pippo-demo-ajax">example app</a>)</h4>
You should first add the dependecies to the webjars in Maven description file like this:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>jquery</artifactId>
<version>2.1.4</version>
</dependency>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.3.4</version>
</dependency>
</dependencies></code></pre>
<br>
Afterwards you have to let Pippo know you are using webjars. This can be done in <span class="label label-info">Application.onInit method</span>:
<pre><code>
public class AjaxApplication extends Application {
@@Override
protected void onInit() {
addWebjarsResourceRoute();
//business code here
}
}</code></pre>
<br>
Then simply reference the resource like
<pre><code><link href="${webjarsAt('bootstrap/3.3.1/css/bootstrap.min.css')}" rel="stylesheet"></code></pre>
for css or
<pre><code><script src="${webjarsAt('intercooler-js/0.4.10/src/intercooler.js')}"></script></code></pre>
for js.
<br>
For examples on using webjars in several template language for Pippo you can check out this link <a href="http://www.pippo.ro/doc/templates.html">here</a>
<br>
</div>
<!-- Ring (Clojure) -->
<div class="tab-pane" id="ring">
<h3>Instructions for Ring (<a href="https://github.com/webjars/sample-clojure">example app</a>)</h3>
Ring makes it easy to expose WebJars through the <span class="label label-info">wrap-resource</span> function.
First add a Webjar as dependency to your application in the <span class="label label-info">project.clj</span> file, like:
<pre><code>:dependencies [[org.webjars/bootstrap "3.1.0"]]</code></pre>
<br>
Then change your wrapper sequence to setup <span class="label label-info">wrap-resource</span> to look for assets in <span class="label label-info">/META-INF/resources</span> directories in JARs on the CLASSPATH:
<pre><code>(def app
(-> handler
(wrap-resource "/META-INF/resources")))
(defn -main []
(run-jetty app {:port (Integer/parseInt (or (System/getenv "PORT") "8080"))}))</code></pre>
<br>
Now you can reference a WebJar asset like:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'></code></pre>
<h3>Using clj-webjars</h3>
Alternatively you can use <a href="https://github.com/jeluard/clj-webjars">clj-webjars</a> to simplify assets integration.
By relying on <span class="label label-info">wrap-webjars</span> ring middleware you can reference a WebJar asset like:
<pre><code><link rel='stylesheet' href='assets/css/bootstrap.min.css'></code></pre>
The right asset will be transparently accessed and served with proper HTTP caching behavior.
</div>
<!-- Dandelion -->
<div class="tab-pane" id="dandelion">
<h3>Instructions for Dandelion</h3>
When writing bundles, you can configure assets to be fetched from multiple locations: <code>webapp</code>, <code>classpath</code> and more.
<br>
<a href="http://dandelion.github.io/">Dandelion</a> also provides a WebJars integration via a dedicated locator for WebJars.
<br><br>
First, you have to add dandelion-webjars as dependency to your application in the <span class="label label-info">pom.xml</span> file:
<pre><code><dependencies>
<dependency>
<groupId>com.github.dandelion</groupId>
<artifactId>dandelion-webjars</artifactId>
<version>1.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
And a WebJar dependency like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>jquery</artifactId>
<version>1.11.3</version>
</dependency>
</dependencies></code></pre>
<br>
Then, in your bundle definition, configure the asset as follows:
<pre><code>{
"assets": [
{
"version": "1.11.3",
"locations": {
"webjar": "jquery.js"
}
}
]
}</code></pre>
<span class="label label-success">Note</span>
Note the usage of the <code>webjar</code> location key, that tells Dandelion to fetch the asset from a WebJar.
<br>
<span class="label label-success">Note</span>
Since Dandelion uses <a href="https://github.com/webjars/webjars-locator/">webjars-locator</a> internally, you just need to specify the name of the asset, path excluded but extension included.
<br><br>
Dandelion will finally generate the following client-side HTML markup:
<pre><code><script src="/[contextPath]/webjars/jquery/1.11.3/jquery.js"></script></code></pre>
<br>
A sample application is available <a href="https://github.com/dandelion/dandelion-core-samples/tree/master/core-thymeleaf-webjars">here</a>.
</div>
<!-- Vert.x Web -->
<div class="tab-pane" id="vertx">
<h3>Instructions for Vert.x Web</h3>
The Vert.x Web <span class="label label-info"><a href="https://vertx.io/docs/vertx-web/java/#_serving_static_resources">StaticHandler</a></span> can resolve file paths from both the filesystem and the classpath.
Therefore, it requires very little configuration to serve assets packaged in a WebJar.
<h4>Maven Example</h4>
First add a WebJar as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
In your code, create a <span class="label label-info">StaticHandler</span> and assign it to a <span class="label label-info">Route</span>:
<pre><code>Router router = Router.router(vertx);
router.route("/assets/lib/*").handler(StaticHandler.create("META-INF/resources/webjars"));</code></pre>
<br>
Then simply reference the resource like:
<pre><code><link rel='stylesheet' href='assets/lib/bootstrap/3.1.0/css/bootstrap.min.css'></code></pre>
</div>
<!-- Quarkus -->
<div class="tab-pane" id="quarkus">
<h3>Instructions for Quarkus</h3>
Quarkus support the use of WebJars by default and also adds a <a href="https://quarkus.io/guides/http-reference#webjar-locator-support">WebJar Locator</a> to reference
WebJars without the version.
<h4>Maven Example</h4>
First add a WebJar as a dependency of your application in the <span class="label label-info">pom.xml</span> file, like:
<pre><code><dependencies>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies></code></pre>
<br>
Then simply reference the resource like:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'></code></pre>
<h4>Maven Example with locator</h4>
If you also want to use the locator, also add this to your <span class="label label-info">pom.xml</span> file :
<pre><code><dependencies>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-webjars-locator</artifactId>>
</dependency>
</dependencies></code></pre>
<br>
Now you can reference the resource without the version:
<pre><code><link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'></code></pre>
</div>
</div>
</div>
</div>
}