search

55minutes / fiftyfive-wicket

Bootstrap Apache Wicket with testing utilities, Apache Shiro security, JS dep management, and more
Apache License 2.0
68 stars 24 forks source link

readme

55 Minutes Wicket Project

The 55 Minutes Wicket project is a set of tools and libraries we use for enhancing our productivity with the Apache Wicket Java web framework. We've made our code available as open source to share with the Wicket community.

This project requires JDK 6 and Wicket 1.5. Refer to the fiftyfive-wicket-2.x project if you need an older release that can be used with Wicket 1.4.

Please note that this project is not compatible with Wicket 6. Currently there is no ETA for Wicket 6 compatibility.

Quick start

The quickest way to get started with the 55 Minutes Wicket library is use our Maven archetype. This assumes that you have maven installed, preferably version 3.0.

First, make sure you have compass and its related ruby gems installed.

gem install compass compass-colors sassy-buttons

Then run the following command:

mvn archetype:generate -U \
    -DarchetypeGroupId=com.55minutes \
    -DarchetypeArtifactId=fiftyfive-wicket-archetype \
    -DarchetypeRepository=http://opensource.55minutes.com/maven-snapshots \
    -DarchetypeVersion=4.0-SNAPSHOT

This creates a project directory with all the Java, Maven POM and web.xml scaffolding you need for a Wicket application with Compass, Shiro and Spring integration, plus high-quality starters for your HTML5, CSS and JavaScript. As with most maven archetypes, you'll be prompted for the project name, group ID, artifact ID, version and package.

Next, to run the resulting project, simply change into the project directory and run:

mvn jetty:run

That's it! Your project is up and running at http://localhost:8080/. Explore the code included with the archetype and then continue reading this page to learn about what is included in fiftyfive-wicket.

Compass

The fiftyfive-wicket archetype includes stylesheets that are written in Sass using the SCSS syntax, which are then compiled down to standard CSS using Compass. This gives you powerful tools like variables and mixins, and improves browser performance by merging separate CSS files into a single response.

We've integrated Compass with the Maven build process, meaning mvn compile also compiles SCSS to CSS, and mvn clean also deletes the compiled CSS. We recommend stylesheet authors run compass watch as part of their workflow so that CSS files are automatically regenerated the instant you save an SCSS file.

Read more about how we use Compass by visiting our css3-foundation project.

Shortcuts

We've identified the most commonly reused patterns when authoring Wicket pages and created static helper methods for making this code much more concise. We call these Shortcuts.

For example, often you will want to specify a CSS class for a Wicket component in Java. Here's how you normally would do this in Wicket:

add(new AttributeAppender("class", foo).setSeparator(" "));

With Shortcuts:

add(cssClass(foo));

Or maybe you want your component to include a CSS file? Typical Wicket:

@Override
public void renderHead(IHeaderResponse response)
{
    response.renderCSSReference(
        new PackageResourceReference(Application.get().getClass(), "screen.css"));
}

With Shortcuts:

add(cssReference("screen.css"));

Or creating a LoadableDetachableModel? Normally in Wicket:

new LoadableDetachableModel<User>() {
    @Override
    protected User load()
    {
        return userService.currentUser();
    }
};

With Shortcuts:

loadedModel(userService, "currentUser");

Handy components

The fiftyfive-wicket-core library includes a bunch of small but useful components for making Wicket development much easier. Here are some examples:

Testing tools

The fiftyfive-wicket-test library contains extra tools for writing good unit tests for Wicket pages and components. Here are some highlights:

Apache Shiro Security

The fiftyfive-wicket-shiro library provides simple and powerful login, logout and authorization features by integrating Wicket with the Apache Shiro security framework. The fiftyfive-wicket archetype generates a project with two hard-coded user accounts, one of which has the "admin" role. See the security system in action by trying to visit the administration page in the sample project.

Projects generated by the fiftyfive-wicket archetype include:

Refer to the fiftyfive-wicket-shiro documentation for more information.

JavaScript

We've streamlined how JavaScript works with Wicket by building the fiftyfive-wicket-js library. This library focuses on solving three big problems that Wicket developers encounter:

  1. Components: Wicket components that use JavaScript need an elegant way to glue the Java and JavaScript sides together. How do we accomplish this without mixing JavaScript strings into our Java code?
  2. Dependencies: Components will often require a JavaScript library be present on the page. That library in turn may require other JavaScript libraries, and so on. How do we keep track of these dependencies and ensure the right files are included on the page in the correct order?
  3. Merging: Now assuming we've got all the right JavaScript references on the page, how do we deliver them efficiently to the browser as a single merged file?

Here are the solutions we offer:

  1. DomReadyTemplate for linking but cleanly separating Java and JavaScript
  2. Sprockets-like syntax with JavaScriptDependency for declaring library dependencies
  3. MergedJavaScriptBuilder for declaratively merging JavaScript without needing to modify your component code

Jetty

Our archetype includes the necessary Jetty magic in the pom.xml file, enabling you to run the project with a simple mvn jetty:run. Plus:

Spring Framework

The dependency injection pattern is a key part of making Wicket applications easy to test and maintain. Spring is well supported by Wicket and is our framework of choice for this purpose. You'll find the following Spring integration in the fiftyfive-wicket archetype:

See the official Wicket wiki for a good explanation of how Spring and Wicket work together.

Version Numbers Explained

The latest, bleeding-edge source code for fiftyfive-wicket is developed in the master branch at GitHub. The version number of code in the master branch will always end with -SNAPSHOT.

Stable releases follow the semantic versioning pattern and are made available as tags at GitHub. Unstable -SNAPSHOT code contains the latest ongoing patches to each X.Y version, following the conventions of the Apache Wicket project. Here are some examples:

Maven Dependencies

If you aren't using the fiftyfive-wicket archetype (as described in the quick start section above), you can add the core 55 Minutes Wicket library to an existing project using the following maven dependency:

<dependency>
  <groupId>com.55minutes</groupId>
  <artifactId>fiftyfive-wicket-core</artifactId>
  <version>4.0-SNAPSHOT</version>
</dependency>

Repeat for the other artifacts of fiftyfive-wicket you wish to use:

Note that since our artifacts aren't in the central maven repository, you'll need to include the following snippet:

<repository>
  <id>fiftyfive-opensource-snapshots</id>
  <name>55 Minutes Open Source Maven Snapshots Repository</name>
  <url>http://opensource.55minutes.com/maven-snapshots</url>
  <releases><enabled>false</enabled></releases>
  <snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
  <id>fiftyfive-opensource-releases</id>
  <name>55 Minutes Open Source Maven Releases Repository</name>
  <url>http://opensource.55minutes.com/maven-releases</url>
  <releases><enabled>true</enabled></releases>
  <snapshots><enabled>false</enabled></snapshots>
</repository>