Wallaby Application Framework by FreshX

Getting started 01

Posted Mon, 14 Jan 2013 14:37:53 GMT wallaby first steps

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.

Installing Wallaby

Posted Mon, 14 Jan 2013 12:08:02 GMT Installation

OS X 10.8

Basic Setup

First, we need to install XCode + GCC and Homebrew. You can download XCode for free in the Apple AppStore. After installation, the command line tools can be installed under Preferences > Downloads > Components.

For homebrew create /usr/local and change the permissions to rwx for your OS X user. Then install homebrew by running:

ruby -e "$(curl -fsSkL raw.github.com/mxcl/homebrew/go)"

Package installation

The homebrew package for Qt does not depend on all available graphic libraries. If want support for a specific format you need to install the library for this format first.

brew install libtiff libjpeg libpng

Now you can install pyqt or pyside. This takes on my machine approx. 20 minutes.

brew install pyqt


brew install pyside pyside-tools

Important: you need to add /usr/local/lib/python2.7/site-packages to your PYTHONPATH!

If you do not have access to a couchdb or elasticsearch server, you now need to install couchdb and/or elasticsearch. With homebrew this is very easy:

brew install couchdb elasticsearch

To start couchdb automatically in system startup, copy the startup script of couchdb to your LaunchAgents path.

mkdir -p ~/Library/LaunchAgents 
cp /usr/local/Cellar/couchdb/1.2.0/Library/LaunchDaemons/org.apache.couchdb.plist ~/Library/LaunchAgents/ 
launchctl load -w ~/Library/LaunchAgents/org.apache.couchdb.plist

If you want to start couchdb manually, just open a terminal and type


Windows 7

Basic Setup

The easiest way to install all libraries on windows, are binary installers. You get them for most libraries, especially if the need to be compiled, on the projects homepages. If you have a working python /w c-compiler setup on your machine, you can also use pip to install the required python packages.

Binary Installers

Python packages

After installation you should update your environment varible for the PYTHONPATH and PATH

PYTHONPATH="<installation path>/Python27/Lib/;<installation path>/Python27/Lib/site-packages/"
PATH="%PATH%;<installation path>/Python27/;<installation path>/Python27/Scripts"

Now install pip with easy_install

cd <installation path>/Python27/Scripts
easy_install pip

If you do not have access to a couchdb or elasticsearch server, you now need to install couchdb and/or elasticsearch.

For java you should add the JAVA_HOME environment variable.

JAVA_HOME="<path to java>/jre/"

Generate a win32 installer

First we need to install py2exe

pip install py2exe

Because of our dependency to zope.interface and the fact, that the zope interface is not a real package, we needto create a empty init.py in our installed zope package folder.

touch <path to python>/lib/site-packages/zope/__init__.py

After that, you should be able to create a binary distribution by

cd deploy
python setup.py py2exe

The exceutable is created in the dist folder. You can start the executable by


or create a installer with InnoSetup

Activate support for image formats

PyQt has a plugin system for the different supported image formats. Those plugins are not automatically included to the generated bundle. To include those plugins you need to copy the imageformats folder from your QT/PyQt installationto the dist folder, manually.

cp -a <path to python>/Lib/site-packages/PyQt4/plugins/imageformats deploy/dist/imageformats

RedHat Enterprise Linux 6.x (CentOS 6.x / Scientific Linux 6.x)


First we need to install a default EL6 system*. Then enable the required repositories.

rpm -ivh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm
wget http://wallaby.freshx.de/repo/binary/Linux/RPM/wallaby.repo -O /etc/yum.repos.d/wallaby.repo

If you have qt-devel or qt3-devel installed, you should remove them, because they conflict with the qt48-devel package wich we install later

rpm -e qt-devel
rpm -e qt3-devel

Now install wallaby (this automatically installs updated versions of Qt (V4.8.3), PyQt (4.8.3) sip (4.12.1), Twisted (V12.2.0), CouchDB (1.2) and Elasticsearch (0.19))

yum install wallaby

and start the couchdb and elasticsearch server

service couchdb start
service elasticsearch start


Based on some of the following howto's the rpm files were created:

Our source RPMs can be found here

Debian 6.x Installation

Until now only the server backend (couchdb + elasticsearch is supported). as soon as qt48 + pyqt is ready for Debian wallaby will be fully running.

First you need to enable the unstable source (see apt-pinning). Then you can install CouchDB 1.2 with

apt-get install couchdb

Get elasticsearch >= 0.19 from here and install it

wget https://github.com/downloads/elasticsearch/elasticsearch/elasticsearch-0.19.11.deb 
dpkg -i elasticsearch-0.19.11.deb

Ubuntu Installation

apt-get install python-qt4 pyqt4-dev-tools qt4-designer

Platform independent Setup

CouchDB Config

To use any app, you first need to bootsrap the database. For example to bootstrap the inspector app use the following command:

wlby -a inspector --push default

Elasticsearch / River

Once the basic dependencies are installed you will need to enable the elasticsearch plugins river-couchdb and (optional) elasticsearch-lang-javascript.

<path to elasticsearch>/bin/plugin -install elasticsearch/elasticsearch-river-couchdb/1.1.0

Also needful plugins are the lang-javascript plugin (js support in river filters) and the head plugin (management web-frontend for elasticsearch)

<path to elasticsearch>/bin/plugin -install elasticsearch/elasticsearch-lang-javascript
<path to elasticsearch>/bin/plugin -install Aconex/elasticsearch-head

The web-frontend can be accessed with http://localhost:9200/_plugin/head/

To activate the new plugins you need to restart elasticsearch!

Wallaby components

Twisted 12.x is part of Mac OS X as well as RedHat (if installed by the docu above) If you want a clean installation, it is recommended to use virtualenv.

pip install virtualenv ...

Wallaby dependencies

Install all wallaby dependencies with

pip install wallaby


Once you successfully installed wallaby you can run

wlby -a inspector

Use wallaby

Once Walllaby is installed the wallaby command is available in command line.

Use wlby --help to get a list of the options:

wlby --help
  -h, --help            show this help message and exit
  -a APP                The application name. If you are in a wallaby
                        application folder, this option could be omitted.
  --username=USERNAME   The user to authenticate with the backends.
  --password=PASSWORD   The password to authenticate with the backends.
  --create=CREATE       Create a new application with the given name. This
                        option creates a new folder wallaby-app-<name>
  --push=PUSH           Push the couchapp to the given target. The targets
                        could be configered in the <app>/couchapp/.couchapprc
                        configuration file
  --script=SCRIPT       Execute an application script. The scripts are located
                        in the <app>/scripts folder
  --server=SERVER       The URL of the backend server (without port)
                        The port of the CouchDB backend
  --es-port=ESPORT      The port of the elasticsearch backend
  --db=DB               The name of the database. Defaults to the application
  -p PREF               Special option for the designer. Open the preference
                        sheet with the given name.
  -i ISHEET             Special option for the designer. Open the inspector
                        sheet with the given name.
  -c CHECK              Check the pillow consistency of the given room-name
  -s                    Output the suggestions for all room
  --fx                  Use the backends of FreshX.
  --designer            Launch the Qt designer.
  --designerLog         Output the designer log to the current folder.
  --debug=DEBUG         Debug the given rooms. Multiple room are seperated by
Fork me on GitHub

Last posts: