Fork me on GitHub

The TodoApp archetype will generate a reasonably complete application for tracking to-do items, based around a single domain class ToDoItem and repository, ToDoItems.

While not quite a "kitchen-sink" example (there is, after all, just a single domain class), the app nevertheless demonstrates a good number of Isis' capabilities. In particular, the use of contributed actions etc is demonstrated by ToDoItemContributions; view models are demonstrated by ToDoItemsByCategoryViewModel and ToDoItemsByDateRangeViewModel; a dashboard is demonstrated by ToDoAppDashboard.

The archetype also demonstrates Isis' support for in-built profiling, auditing, event publishing and background actions. The last of these integrates with the Quartz scheduler, executing queued-up actions every 10 seconds.

Running this archetype is a good way to get familiar with the structure of a not-too-complex Isis application. However, to get started with your own application, we generally recommend that you run the alternative simple archetype. This will generate a completely stripped back and minimal application for you to refactor and extend; you can then use this ToDo app to guide your own development.


How to use the TodoApp archetype...

How to use the Apache Isis TodoApp archetype to generate your first Apache Isis application.

nb: previously the TodoApp archetype was called the 'quickstart archetype', which is how it is referred to in the screencast)

... and what it generates

A run-through of the main features of the todo application generated by the Apache Isis TodoApp archetype (as of v1.4.0).

nb: previously the TodoApp archetype was called the 'quickstart archetype', which is how it is referred to in the screencast)

An earlier screencast, relating to v1.2.0, is available here.>

Generating the App (stable release)

Create a new directory, and cd into that directory.

Then run the following command:

mvn archetype:generate  \
    -D archetypeGroupId=org.apache.isis.archetype \
    -D archetypeArtifactId=todoapp-archetype \
    -D archetypeVersion=1.7.0 \
    -D groupId=com.mycompany \
    -D artifactId=myapp \
    -D version=1.0-SNAPSHOT \


The archetype generation process will then run; it only takes a few seconds.

Generating the App (snapshot release)

We also maintain the archetype for the most current -SNAPSHOT; an app generated with this archetype will contain the latest features of Isis, but the usual caveats apply: some features still in development may be unstable.

The process is almost identical to that for stable releases, however the archetype:generate goal is called with slightly different arguments:

mvn archetype:generate  \
    -D archetypeGroupId=org.apache.isis.archetype \
    -D archetypeArtifactId=todoapp-archetype \
    -D archetypeVersion=1.8.0-SNAPSHOT \
    -D groupId=com.mycompany \
    -D artifactId=myapp \
    -D version=1.0-SNAPSHOT \
    -D archetypeRepository= \

where as before:

but also:

The archetype generation process will then run; it only takes a few seconds.

Building the App

Switch into the root directory of your newly generated app, and build your app:

cd myapp
mvn clean install

where myapp is the artifactId entered above.

Running the App

The todoapp archetype generates a single WAR file, configured to run both the Wicket viewer and the Restful Objects viewer. The archetype also configures the JDO Objectstore to use an in-memory HSQLDB connection.

Once you've built the app, you can run the WAR in a variety of ways.

The recommended approach when getting started is to run the self-hosting version of the WAR, allowing Isis to run as a standalone app; for example:

java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar

This can also be accomplished using an embedded Ant target provided in the build script:

mvn -P self-host antrun:run

prior to v1.5.0, this was simply: mvn antrun:run

The first is to simply deploying the generated WAR (webapp/target/myapp-webapp-1.0-SNAPSHOT.war) to a servlet container.

Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to cd into the webapp module:

cd webapp
mvn jetty:run -D jetty.port=9090

In the above, we've passed in a property to indicate a different port from the default port (8080).

Note that if you use mvn jetty:run, then the context path changes; check the console output (eg http://localhost:9090/myapp-webapp).

Finally, you can also run the app by deploying to a standalone servlet container such as Tomcat.

Running the App with Fixtures (1.7.0)

It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing. This is done by specifying a fixture script on the command line:

java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
     --initParam isis.persistor.datanucleus.install-fixtures=true  \
     --initParam isis.fixtures=fixture.todo.scenarios.RecreateToDoItemsAndCompleteSeveralForCurrent

where (in the above example) fixture.todo.scenarios.RecreateToDoItemsAndCompleteSeveralForCurrent is the fully qualified class name of the fixture script to be run.

Using the App

The archetype provides a welcome page that explains the classes and files generated, and provides detailed guidance and what to do next.

The app itself is configured to run using shiro security, as configured in the WEB-INF/shiro.ini config file. To log in, use sven/pass.

Modifying the App

Once you are familiar with the generated app, you'll want to start modifying it. There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main documentation page first).

If you use Eclipse, do also install the Eclipse templates; these will help you follow the Isis naming conventions.

App Structure

As noted above, the generated app is a reasonably complete application for tracking to-do items. It consists of the following modules:

myappThe parent (aggregator) module
myapp-domThe domain object model, consisting of ToDoItem and ToDoItems (repository) domain service.
myapp-fixtureDomain object fixtures used for initializing the system when being demo'ed or for unit testing.
myapp-integtestsEnd-to-end integration tests, that exercise from the UI through to the database
myapp-webappRun as a webapp (from web.xml) using either the Wicket viewer or the RestfulObjects viewer

If you run into issues, please don't hesitate to ask for help on the users mailing list.