pyjamas
build AJAX apps in Python (like Google did for Java)

## 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.

## Setting up

First, download Pyjamas 0.5 or above, and unpack it. Or, preferably, obtain the latest subversion code from following the instructions at the pyjamas sourceforge page.

If you are using Pyjamas 0.5: in the main subdirectory, run "python bootstrap.py" to create the "buildout" application, which you will find has been created in the bin/ subdirectory. Run buildout, and it will create bin/pyjsbuild and bin/pyjscompile. You now have a development environment that is tailored specifically to your system (known as a developer sandbox).

If you are using Pyjamas 0.6: run "python bootstrap.py" and it will create bin/pyjsbuild and bin/pyjscompile, directly. You now have a development environment that is tailored specifically to your system (known as a developer sandbox).

## 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 ../../bin/pyjsbuild 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.RootPanel import RootPanel
    from pyjamas.ui.Button import Button

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

    if __name__ == '__main__':
        b = Button("Click me", greet)
        RootPanel().add(b)

Pyjamas "emulates" the standard python convention of apps having an "__name__" variable which you can - and should always - detect in any python app that you write. The whole application is 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). This is purely mentioned to illustrate to you that you do not need to care about the "usual" javascript "stuff", you can just get on with developing as if it was a real python application environment.

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.HTML 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.

Additionally, Pyjamas's Documentation is auto-generated from the source code, and there are two locations where this is available. The first is simply a python gendoc-generated version, here. A second version, which uses a modified version of python pydoc.py, will be available later, but if you want to explore it yourself, download pyjamas-desktop from github, cd into the pyjamas directory, and run "../pydoc.py -w ./" to have the code auto-generated into a docs/ directory. Then, on each of the modules auto-generated, run build.py on each of them. The most useful of those has been done already: docui can be seen, here, which you may find useful.

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.