Getting Started

This page describes how to quickly set-up and test Woko. It's a step-by-step tutorial, based on a simple library example. You'll find the sources of the domain model (Library, Item (Books and Papers) and Author) in the template.

The class diagram for the Domain Model of our example looks like this :

The goal of this tutorial is to show how you can implement this simple library application wih Woko. It shows how to set up all required stuff, describes the source code for the Domain Model, and demonstrates the basic Wiki-style CRUD features... You may also want to have a look at the first screencast, that more or less cover this tuto.

Here we go !

Installation

You need a few tools in order to play with Woko (a Java5 SDK, Maven and a JEE Web Container is the bare minimum). A fully detailed installation procedure for these tools can be found here.

Once you have Java, maven and tomcat installed, go grab the project template from the sourceforge downloads :
http://sourceforge.net/project/showfiles.php?group_id=194760&package_id=229734

Get the zip template, unpack it in your workspace, and rename the created folder to your project's name.

Project files structure

Here is the default directories that are created when you unpack the template (a regular maven 2 project structure), along with a small description of their contents :

<my-project>
  pom.xml
  src/
    main/
      java/
        * the woko example .java sources
      resources/
        * the application's configuration files and other resources
    test/
      java/
        * some unit tests
      resources/
        * unit tests configuration files
    webapp/
      WEB-INF/
        web.xml

You can edit the pom.xml file and change the name, artifactId and finalName for your project. Same goes for the display-name of your webapp, in web.xml.

Quick testing, Full Defaults !

The full build is controlled by the maven pom, which includes the cargo plugin for launching the server from the command line. Open a command prompt, and type in the following command :

%> mvn install cargo:start

This will kick the maven build on your project (compile / run unit tests / install) and run tomcat via the cargo maven plugin (make sure your maven settings include the tomcat home property, as explained here, otherwose cargo won't be able to launch tomcat).

Now, point your browser to http://localhost:8080/project_name

Guest Home Page

That's what you see as a guest (unauthenticated) user. Of course, this is a default page, and you'll change it later on.

NOTE : Woko can also present all or part of your objects to guest users, but this feature is disabled by default.

Nothing really exciting to see here, let's log-in using the navbar link !

Logging in

Woko ships with a fully functional implementation for users and roles. For convenience reasons, there's users of the default woko roles (ROLE_WOKO_USER and ROLE_WOKO_DEVELOPER) in there :

• wuser, wuser : user with role WOKO_ROLE_USER
• wdevel, wdevel : user with role WOKO_ROLE_DEVELOPER

Of course, you can add your own users and roles later on (or even completely replace the built-in system). For now, you can log-in and test stuff with those default users...

NOTE : Default users are provided for convenience reasons, and they allow you to directly have Wiki style CRUD (and more) enabled, for free. It allows to test and prototype quickly, and to perform admin/development tasks. More infos about the default Woko roles can be found here.

Since you have nothing in the database at the moment excepted your users and roles, it's preferable for now to create some instances if we want to actually see something !

So let's log-in as wuser,wuser...

Enter Woko !

Here's what you should see just after you've logged in as a user of role ROLE_WOKO_USER :

As you can see, a few things have been added to the page for this user profile :

1. Search form : this allows to search in your objects (we'll get back to this later)
2. Username + logout link : know who you are, log-out, the usual stuff
3. Navbar Links

1/ and 2/ are available to all authenticated users by default, only guests don't see that.

The navbar items (3/) are specific to the ROLE_WOKO_USER. They allows to :

• get back to this page (Home Page)
• create new instances of the model objects

Of course, this nav bar, as the other parts of what is displayed, is fully configurable on a per-profile basis (via facet override, as explained in [ExtensionPoints].

For now, let's create a few instances...

Creating objects

Click create object in the nav bar. You'll be prompted for the type of the object you want to create :

Select e.g. Book, and submit. Woko will then create a new instance of Book, and display a page inviting you to fill in all required fields (at minimum) :

At the moment, the object is not saved in the database. The instance is "transient", and will be saved when you press the "save" button.
So fill in the required fields, and press save. Your Book is now into the database.

Repeat the operation for various types of objects (Paper, Author, Library). Don't play too much yet, as we're gonna walk through the other features now...

Finding objects

Now that we have objects, let's try to find them !

Full text, Google-like search

You can find instances easily by simply entering a query in the search box, in the header. Woko includes the wonderful Compass object indexation and search framework seamlessly, so that you objects are automatically indexed and available for search when you save or update them. You simply have to annotate your domain classes with Compass annotations, and that's all !

So enter a query, and hit the search button. You now see a list of matching objects grouped by classes, along with their score.

NOTE : You can try a few searches, Compass is awesome ! It's yet a very powerful, flexible and intuitive way to find objects, and it embraces the concepts of simplicity carried by Woko. Also, you can easily write your own text analyzers if you want to enhance the search capabilities of your application (port stemming, expressions etc.).

Browsing objects

Now that you know how to find objects, simply click them in order to browse them. Woko dynamically introspects your object and uses facets in order to display its properties :

All "basic" types are handled (Strings, Numbers, Booleans, Dates etc.), automatically. If the object has associations with other persistent objects (x-to-one or x-to-many), those ones are rendered as hyperlinks, and you can navigate the instances graph very easily ! For the moment, you should not have associated objects yet (unless you played too much in previous step, you curious ;-P), but you'll see this in a moment.

For now, the interesting thing is the "edit object" link, on the top of the object...

Editing objects

When you're logged in as a ROLE_WOKO_USER user (or DEVELOPER, as it inherits from USER), you can edit every instances by default. Like in a regular wiki, simply click the edit link... the object is now represented in a FORM that allows to edit its properties :

Woko dynamically introspects the properties and their annotations, so that the widgets are sized, marked as required etc. All this can be completely customized, but it includes everything needed to edit simple types and associations by default.

Input validation

Of course, Hibernate validation annotations (e.g. NotNull, Length etc.) in your model are used, validation errors are displayed, fields highlighted etc :

Associations

Woko also allows easy edition of associations when possible (this depends on the directionality defined in the JPA mapping - "mappedBy" attribute in the @XToMany annotations).
When an association is found (x-to-many - e.g. Book.authors, or x-to-one - e.g. Book.library), a "change" link is generated aside the value of the assocation. This link displays an "Editing assocation end" page that allows the user to select the item(s) that have to be associated with the current object. Depending on the nature of the relation (to-many or to-one), slighly different screens are provided :

x-to-one :

x-to-many :

The available choices displayed in the list(s) are obtained dynamically based on the association end's real type. Woko simply does a HQL select to fetch objects of the appropriate type and propose them for association.

You can also create new objects when editing an association. This way, you create graphs of objects easier : you don't have to create the new object, come back to the object you were editing and associate the new one. All the process of creating, persisting and associating the new object to the one you were editing is transparent, and done from the same page.

This default behavior is fine for an admin section or in simple cases. Of course, Woko allows you to customize this too, by writing dedicated facets in order to populate those lists with the data you want for some associations (and some profiles, of course !).
Also, you could even completely change the rendering for a given property of a given object, so you could imagine other means to change the associations between objects (probably sexy AJAX stuff).

Conclusion

As you've seen in this tuto, Woko can dynamically generate pages that allow users to create, find, browse, edit persistent objects and edit their properties (even associations). It also includes default support for users and roles (ROLE_WOKO_USER and ROLE_WOKO_DEVELOPER, explained here).
Part of the contract is fulfilled : we clearly have the basis for our Object Oriented Wiki :-)

Now, looking at the default screens, okay, it's cool but how can I customize this ? I mean, what if I don't want all properties to be listed ? What if I want to completely change the pages for some objects ? How can I invoke some business methods on my objects ? ...

That's where it begins to get really exciting ! For the moment we've only talked about a "CRUD app on hibernate POJOs", which isn't big deal. The challenge is precisely in the way everything can be extended and customized. If you think about it, that's where it often gets crappy with regular CRUD stuff...

Woko heavily relies on facets to structure and organize the application. Basically, every action (view, update, change association, search, generate a RSS feed, etc.) that is done on an object and for a given user profile is encapsulated in a dedicated facet. As explained in the extension points, you can tweak many things in Woko in order to change the generated pages, without touching a single JSP, by extending a few facets here and there...

Now that you have a better overview of what Woko does out-of-the-box, check out the [UsersAndRoles] and [ExtensionPoints] pages to learn more about how to plug your own users and roles in, extend and customize things, etc !

If you want to know exactly how Woko works internally, have a look at the Architecture page.

Happy Wokoding !