The fiftyfive-wicket-js project features JavaScript dependency resolution, merged JavaScript resources, and a clean way to integrate external JavaScript files with Wicket pages and components.
Whenever you reference a JavaScript file using the fiftyfive-wicket-js set of classes and utilities, that JavaScript file is scanned for special dependency markers.
For example, let's say you have a MyPanel component that brings along its
own JavaScript behavior in a file called MyPanel.js
. That
JavaScript, in turn, requires jQuery and a file called common.js
in order to work.
You can document those dependencies and get automatic dependency
resolution by adding these lines to MyPanel.js
:
//= require jquery //= require common
Presto! Now when you whenever you use the MyPanel component in
your application, jquery.js
and common.js
will
automatically be added to the HTML <head>
.
This dependency resolution is unique to fiftyfive-wicket-js, and thus only works when you interact with a JavaScript file through one of the fiftyfive-wicket-js classes. Here are the classes that are dependency-resolution aware:
<head>
from a Wicket page or
component (as in the MyPanel example)JavaScriptDependencySettings has
many methods for tweaking and disabling parts of the dependency resolution
system. You can easily turn the entire thing off by calling
JavaScriptDependencySettings.get().setSprocketsParser(null)
.
The short answer is that fiftyfive-wicket-js searches a set of configurable classpath locations. You can specify these locations using JavaScriptDependencySettings. More specifically:
//= require jquery
or add(new
JavaScriptDependency("jquery"))
– the jQuery.js
file is
loaded from the classpath based on the
JavaScriptDependencySettings#getJqueryResource()
setting. By
default, the latest version of jQuery is bundled with fiftyfive-wicket-js,
so you should be good to go. However, if you prefer a different version, or
if you want to disable auto-inclusion of jQuery, you can change this
setting.<head>
to a jQuery
UI CSS theme. Again, you can change these resources or disable this
behavior through JavaScriptDependencySettings.
.js
extension to the library name and search for that JavaScript file in the
classpath. Use JavaScriptDependencySettings#addLibraryPath()
to specify the
exact search locations. If you use the fiftyfive-wicket-archetype to
bootstrap your project, this will be already set up for you to point to a
location in src/main/resources/<your-package>/
.Within your JavaScript files, declare dependencies like this, and fiftyfive-wicket will scan the classpath to locate them, as described above:
//= require jquery //= require my-library
If you want to include a JavaScript file from the same directory,
prefix the JavaScript file name with ./
, like this
//= require ./another-file-in-this-directory
Some more details:
JavaScriptDependencySettings#setSprocketsParser
for further
explanation.require_tree
are not
supported by fiftyfive-wicket-js.Merging JavaScript can improve the performance of your web application by reducing the number of browser roundtrips required to load individual JavaScript files. You can merge JavaScript easily in fiftyfive-wicket-js. Here's how it works.
A good thing to remember as you proceed: fiftyfive-wicket-js's MergedJavaScriptBuilder tells Wicket how to optimize delivery of JavaScript resources. It is still up to your pages and components to tell Wicket which resources to send.
Therefore, first you should follow the standard Wicket practice of
declaring your JavaScript resources per Wicket page or component. Don't
worry about optimizing how the resources will be served; at this
point just be concerned with what JavaScript files each page of your app
needs to be functional. You can do this with JavaScriptDependency, or in
plain Wicket by overriding Component#renderHead()
.
Once your app is fully functioning, only then should you worry about
resource merging. In your Application#init()
, use
MergedJavaScriptBuilder to list
all of the JavaScript files you would like
merged together. Then, whenever it comes time for Wicket to add a JavaScript
file to the <head>
, the merged version will be used in its
place.
Refer to the MergedJavaScriptBuilder documentation for a complete example.
With fiftyfive-wicket-js you have three powerful options for integrating JavaScript with your Wicket pages and components. Each is designed for a specific purpose.
<head>
. Wicket provides something
like this out of the box with Component#renderHead()
, but
JavaScriptDependency is a more convenient API and also provides the
dependency resolution feature as described above.Component#renderHead()
,
but DomReadyScript has advantages of a convenient behavior-based syntax,
and faster jQuery-based DOM-ready code.<head>
and
will execute on DOM-ready. DomReadyTemplate is the best option for
client-side widgets. JQueryDatePicker is an example
implementation.