Getting Started with pyjamas

Programming with pyjamas needs a little bit of rethinking about the way that you do Web application development. Primarily, you need to forget virtually everything you've ever learned and come to expect Web development to be. The reason for this is very simple: Pyjamas is pure javascript. Although written in python, not javascript, it is essential to bear in mind that virtually 100% of your web application will be javascript - not HTML. The programming style you may be accustomed to for HTML programming involves placing as much HTML into one page as you can stand, and making the minimum number of exceptions and allowances for dynamic content that you can manage, without making the HTML page "too complicated" to be readable.

Pyjamas makes it possible for you to break pages down into concepts. classes. widgets. maybe some CSS styling is added, almost as an afterthought, on top of the "real" functionality. In other words, Pyjamas is actually more like Desktop application development than it is Web development.

With that in mind, the best possible starting point has to be the examples, most of which were ported from Google Web Toolkit. They will make it really clear just how "not" Web that pyjamas - and incidentally GWT - really are.

Examples

The simplest example is of course the traditional Hello World or, in this case, Hello AJAX. If you've downloaded pyjamas, you will be able to browse, with your browser, to the examples directory and see this in action for yourself. Type "file://home/yourusername/pyjamas/examples" into your URL bar - or wherever you have unpacked pyjamas to and continue to browse to the helloworld output directory.

Once you have played with the example, online, try it on your local machine. Remember to run the "build.sh" script (if you have linux or MacOS, or execute python.exe ../../build/build.py Hello.py if you have windows). Then, take a look at the source code that generated it, which is shown here:

from pyjamas import Window
from pyjamas.ui import RootPanel, Button

def greet(sender):
    Window.alert("Hello, AJAX!")

class Hello:
    def onModuleLoad(self):
        b = Button("Click me", greet)
        RootPanel().add(b)

The most important thing to note is that, firstly, you're declaring a class (Hello), which must match the name of the HTML file in the same subdirectory (in this case, Hello.html), and the second thing to note is that it has an "onModuleLoad()" function. This is the function which gets called, indirectly, via the browser's body.onload javascript system (Pyjamas provides a convenience library including an onload function which goes hunting, automatically, for your module).

The second important thing to note is that everything gets added to RootPanel. RootPanel() gives you access to the Browser's DOM model (starting of course at body). To illustrate, try adding this, and see what happens:

        RootPanel().add(HTML("Hello <b>World</b>"))

You should get nothing - and if you look in your Javascript console for an error message, you should find an error indicating that HTML does not exist. This is correct - because you needed to add this to the top of the module, along with the other imports:

from pyjamas.ui import HTML

Now if you re-run build.sh, you should see both a button and next to it the words "Hello World". Congratulations, you've just successfully developed your first pyjamas application.

Documentation

Now you've started on a simple example, and have seen some of the more involved ones, you might want to see a little bit more about what can actually be achieved, so that you can start making your own application. Whilst the kitchen sink example covers every single widget in existence, you may find that browsing the source code of this example to be rather inconvenient.

The showcase, however, contains documentation on each of the main classes in the ui module. It describes how to use each of the classes, what they are for, and, crucially, it includes a working example and the source code for that example.

So, there is quite a lot for you to be able to get started on your application. A recommended approach is, like as with any programming, to find a working example that is close to what you want, and cut and paste it into your own code, step-by-step. Both the showcase and the examples make that much easier to do.

Create your own Widget Tutorial

All of the above covers how to use widgets: it doesn't explain how to write one - how to make your own widget. Fortunately, there's a tutorial on how to do exactly that. It was inspired by the pygtk2 create-a-widget tutorial, and you may find it interesting to compare just how easy it is to create a widget in pyjamas with how complex it is in pygtk.