Preface

WebWork is a popular, easy-to-use MVC framework, for more information on the WebWork project, please visit WebWork.
This site is geared towards developers that have an understanding towards certain technologies. Before diving into how Webwork works and running demos, it is recommended that you review the concepts below:

Java
Servlets, JSP, and Tag Libraries
JavaBeans
HTML and HTTP
Web Containers (ex. Tomcat)
XML

Distribution Download and Information Resources

Download Webwork Distribution

You can download the full WebWork distribution here. It contains the webwork.jar file as well as full documentation, sources, all required and optional dependent libraries and examples. For more information on how to build WebWork from source or even checkout from CVS, please refer to Building Webwork.

Online Information and Project Resources

There are many online sources of information, support and project resources around. Here are links to help you find your way:

Download Webwork - download Webwork Distribution
Join the WebWork Forums - The forums are full of active developers, contributors, and power users - often even available for chat. This is the best and quickest way to get a question answered.
Subscribe to Mailing List or browse Mail Archive or post a question. All posts from the forum are posted to the mailing lists, as well as your posts to the list will make it to the forum.
CVS - Browse CVS and source at java.net
Webwork Wiki - Powered by Confluence, the professional J2EE wiki
Webwork Bugs & Issues - Powered by JIRA:Bug & Issue Traking System
OpenSymphony Home

Distribution Quickstart

Overview

The distribution contains the following directory layout:

dist/
docs/
lib/
src/
src/java/template/
webapps/
README.txt
build.properties
build.xml
ivy.xml
osbuild.xml
pom.xml
webwork-(VERSION).jar
webwork-(VERSION).zip
webwork-(VERSION)-src.jar

The docs directory contains the current Javadocs, the full user documentation including the document you are reading, taglib documentation, as well as Clover, JUnit and dependency reports for the build.

The dist directory contains a different WebWork packaging:

webwork-nostatic-<version>.jar: containing only WebWork without the static content
webwork-static-<version>.zip: containing the required WebWork static dependencies

The lib directory contains the required as well as the optional dependencies for Webwork, organized in subdirectories to represent different optional configurations and thereby induced Dependencies:

lib/
      ajax
      bootstrap
      build
      cewolf
      default
      fileupload
      fileupload-cos
      fileupload-pell
      hibernate
      jasperreports
      jfree
      pico
      plexus
      portlet
      quickstart
      sitemesh
      source
      spring
      tiger
      tiles
      velocity
      xslt

Note that none of the optional packages are required to use Webwork. If you wish to use certain features such as JasperReports or Java 5 (Tiger) genercis and annotation support, you must include the optional packages.

Webwork also comes packaged with all the source files and the templates for the JSP tags.

Running demos with QuickStart

WebWork provides a quick way to get started called QuickStart. QuickStart is essentially a combination of a few technologies, including the possibility to run web applications such as the provided examples out of the box with a stripped Jetty container.

With that, running the demos is as easy as can be. You just need to call

java -jar webwork.jar quickstart:<application-name>

from the distribution's top directory, whereby <application-name> is to be replaced by one of the subdirectory names under webapps/, representing the various supplied demo applications. So if you want to start the shopping cart example, just type on your commandline

java -jar webwork.jar quickstart:shopping-cart

After starting an example in that way, you will simply need to point your browser to http://localhost:8080/shopping-cart to view the results.

The packaged examples are:

blank	Not really an example, but a blank web application template for creating your own application
portlet	Demonstration of WebWork porlet integration (to be deployed in a Portal Server)
shopping-cart	Nice example application demostrating various aspects of WebWork
showcase	Demonstration of all tag and AJAX features, along with other examples and some best practices
starter	Basic web application, meant as an easy starting point for experimenting with WebWork's features

Read Quickstart documentation to learn more about how it works and how you can utilize it for your own applications.

The blank web application

As said before, the webapps directory contains a blank web application template. It is meant to be left untouched, instead you will want to make a copy of it as a starting point for your own new WebWork based application. Although you can perform such a copy operation yourself, there is a much easier way around: You will find an build.xml in the webapps directory, which if called with ant new will provide you with a fresh empty webapp with a name you will be prompted for.

Running Demos with Your Favorite Webcontainer

To Quickstart or not to Quickstart?

The previous section described the Quickstart mechanism for trying the supplied example webapps, but also as a handy tool for development of your own WebWork based applications. We recommend you using the said mechanism unless you are familiar with standalone servlet containers and have good reasons to switch, such as preparing a production system etc.

In order to deploy WebWork applications and demos to your favorite servlet container (also called web container) such as Apache Tomcat or Caucho Resin, you will need to build war files from within the webapps directory. You will find an ant build file there which will provide you with an easy way to accomplish that.

To build a webapp war archive, simply run:

ant build -Dwebapp=XXX

where XXX is the name of the webapp you want to build. After the build is finished, the fully-built war file can be found in the dist directory. You may deploy this file to any servlet container.

For example:
ant build -Dwebapp=showcase
To deploy the built showcase.war to Tomcat, just place it into <TOMCAT_HOME>/webapps/ or use the Tomcat Manager Application to upload and deploy the war. After the war is deployed (and your server is started), point your browser to
http://SERVER:PORT/APPLICATIONNAME, according to your setup and the application you deployed.

Your first WebWork Application

Using the Starter Template

The distribution contains a simple webapp called starter in meant as a template for your webapplications. Just copy starter directory to a newly named destination and edit the configuration files as needed.

Setting up from Scratch

Structure of your Webapplication

The following illustrates how your web application should be set up. Copy the webwork-(VERSION).jar, all the *.jar files in /lib/core and any necessary optional *.jar files in /lib/(optional configuration) to your webapp/lib directory. If you need to customize your own templates (how HTML is rendered from webwork UI tags), copy the /src/java/template directory into your webapp/ directory. Your webapp should look similar to this:

/mywebapp/
/mywebapp/template/
/mywebapp/META-INF/
/mywebapp/WEB-INF/
/mywebapp/WEB-INF/classes/
/mywebapp/WEB-INF/lib/
/mywebapp/WEB-INF/lib/CORE&OPTIONAL *.jar
/mywebapp/WEB-INF/web.xml

Minimum Set of Libraries and Config Files

The following files are a minium requirement for your application.

Filename	Description
webwork.jar	WebWork library itself, found in distribution root directory
xwork.jar	XWork library on which WebWork is built
oscore.jar	OSCore, a general-utility library from OpenSymphony
ognl.jar	Object Graph Navigation Language (OGNL), the expression language used throughout WebWork
commons-logging.jar	Commons logging, which WebWork uses to support transparently logging to either Log4J or JDK 1.4+
javamail by sun	for mail
rife-continuations by rife	for continuations feature
web.xml	J2EE web application configuration file that defines the servlets, JSP tag libraries, and so on for your web application
xwork.xml	WebWork configuration file that defines the actions, results, and interceptors for your application

The library files (*.jar) needs to be copied to your /mywebapp/WEB-INF/lib/ directory. If you need optional functionalities inducing dependencies to optional jars, they need to be copied to this directory, too.

web.xml:

Create the following web.xml file in [webapp]/WEB-INF. If you already have a web.xml file, just add the content of the <web-app> tag below to your existing <web-app> tag.

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  <display-name>My WebWork Application</display-name>
  <filter>
    <filter-name>webwork</filter-name>
    <filter-class>com.opensymphony.webwork.dispatcher.FilterDispatcher</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>webwork</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
  <!-- As of 2.2, Spring is the preferred IoC container rather than XWork,
       so you'll have to include the spring jars if you want to use 
       Spring's IoC capabilities in WebWork / Thank you, Hani 
  -->
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>

  <taglib>
    <taglib-uri>/webwork</taglib-uri>
    <taglib-location>/WEB-INF/lib/webwork.jar</taglib-location>
  </taglib>
</web-app>

This registers FilterDispatcher to induce webwork functionality in your requests. The ContextLoaderListener will take care of setting up Spring as your IoC container for WebWork. The taglib entry will help you use Tags in your JSP pages.

xwork.xml:

Create the following file xwork.xml in [webapp]/WEB-INF/classes/.

<!DOCTYPE xwork PUBLIC "-//OpenSymphony Group//XWork 1.1.1//EN"
"http://www.opensymphony.com/xwork/xwork-1.1.1.dtd">

<xwork>
	<!-- Include webwork defaults (from WebWork JAR). -->
	<include file="webwork-default.xml" />

	<!-- Configuration for the default package. -->
	<package name="default" extends="webwork-default">
	</package>
</xwork>

For now, this xwork.xml does only two things:

It informs WebWork that it should import the configuration information from webwork-default.xml. (This file is located at the root of the webwork.jar, so it is sure to be found.)

It defines a default package (with the <package> section) where WebWork elements like actions, results and interceptors are registered.

Child pages

Getting Started