This documentation is for an old version of fiftyfive-wicket-all (4.0).

Package fiftyfive.wicket.js

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.


Class Summary
AbstractJavaScriptContribution Base class for fiftyfive-wicket-js JavaScript <head> behaviors.
DomReadyScript Renders a script tag in the <head> that executes specified JavaScript code on DOM ready.
DomReadyTemplate Injects DOM-ready Javascript into the <head> using the interpolated contents of a separate JavaScript template.
JavaScriptDependency Represents a JavaScript file, or group of files, that will be injected into the <head>.
JavaScriptDependencySettings Settings that affect how JavaScript dependencies are located.
MergedJavaScriptBuilder Instructs Wicket to merge a list of JavaScript resources into a single file.

Package fiftyfive.wicket.js Description

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.

Dependency resolution

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>.

Where does this magic happen?

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:

How do I change or disable it?

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

Where do I put my JavaScript files?

The short answer is that fiftyfive-wicket-js searches a set of configurable classpath locations. You can specify these locations using JavaScriptDependencySettings. More specifically:

What's that syntax look like again?

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:

Merged JavaScript resources

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.

Integrating JavaScript with Wicket components

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.

Copyright © 2012 55 Minutes. All Rights Reserved.