Our first Wallaby-App


To start, we need a couchDB. So we´re logging in into Futon and create a new couchDB database. We´ll call our first app firstapp (Note: Wallaby allows only lowercase app names.) hence we´ll give the same name to the corresponding database.

If we´re there, let´s create our first document firstDoc with some some lorem ipsum in content. That´s it for now on Futon.


Let´s run Wallaby

Open a command line in your desired project folder and create the Wallaby-App by

wlby --create firstapp

Notice: the name needs to be the same as your database. If not, you can change the database name in the generated mainWindow.py

Enter the directory and launch the QT-Designer by wlby option --designer

cd wallaby-app-firstapp
wlby --designer

The Wallaby-Widgets are located in the Widget-Box. To load our first document we´ll use an actionButton and a plainTextEdit to display the documents content. Place the widgets in the mainWindow and allocate some layout. Hit save and quit.

  • Wallaby Widgets

  • firstapp with actionButton and plainTextEdit

App-configuration using the Wallaby-Inspector

wlby will start your application, provided your still in the directory. wlby -a firstapp would do the same from any location.

Press ALT-CMD-O to switch in overlay mode. A click on the overlay opens the Wallaby-Inspector which is the fundamental tool in the Wallaby-Framework.

Inspector in Overlay-Mode

Basic concept of Wallaby is a functional grouping of UI-elements due to the underlaying document logic. These groupings provoke name spaces, called Rooms. Each room can provide a document and appropriate document handling logics. These logics are located in so called peers. Document handling is triggered by a multicast messaging within or across room borders.

In this example our goal is displaying an existing CouchDB document in a plainTextEdit-widget by pressing the load-button. Therefor we´re in need of both widgets in the same room communicating with each other. The load-button should be configured to send a "load-Document"-Message into the room where some other logic component should handle this request followed by a "document-loaded" approval. The document-loaded message triggers the displaying widgets to update their content. In the following, these logic components are described as "peers" and mulitcast messages as pillows in analogy to a pillow fight inside a room. The payload of a message is called as feathers. Most common document and database actions are already implemented in peers and can be added into the room easily in the Wallaby-Inspector.

We start by grouping our widgets into the same Room. To configure a Wallaby-Widget click on the unconfigured (red-overlay) widget and press the edit-button in the upper left corner of the Inspector. Then add the rooms name "firstRoom"

Once both widgets are added to "firstRoom" wen need to add the logic components (peers). For this example we do need some components to interact with our CouchDB and due to our plainTextEdit-Widget we need some document show/edit logic.

By changing to the peers-tab and selecting our "firstRoom" we get a list of suggested peers which are commonly used with the widgets in the room.

By double-click the suggested EditDocument-Peer and depending peers are added into the "firstRoom". The next suggest is a DocumentDatabase-Peer and a CouchDB-Peer which we also add into our "firstRoom".

Now that we have the logics all together we switch back to the widgets-tab and select the actionButton. We´ll configure the button to throw a load document pillow when it gets triggered by a click.

Make sure you are still in edit mode then add a triggered pillow and select clicked as trigger. As Pillow you can select out of all pillows provided by all the peers inside "firstRoom". Our Pillow will be a "load" message command provided by EditDocument-Peer: EditDocument.In.Load. And because the peer needs to know which document it should load we add the document's ID (firstDoc) as payload (feather) to the pillow.

Now we need to tell the plainTextEdit what to do if the rooms document is loaded. In this case we want to display the "lorem ipsum..." stored in our firstDoc as value of "content". So the content of content is addressed by the simple path "content". That´s it...

Once the widgets are configured the overlay color changes to a room associated color, green for this case.

To run our app simply press CMD-ALT-O to exit overlay mode and click load.

Whats happens exactly by pressing the load button?

The pillow DocumentEdit.In.Load with the document's ID is thrown into firstRoom. The EditDocument-Peer catches the pillow and throws an additional pillow to ask the DocumentCache-Peer for the requested document which eventually requests it from the DocumentDatabase-Peer. The DocumentDatabase-Peer will then request the document from the CouchDB-Peer. The document will then be passed back through the described message chain in reverse. A second click will trigger the same action which will then stop at the DocumentCache-Peer where the document is charged and possibly updated, triggered by document manipulations.