Google App Engine test application explained

The sample application uses Django. Django is a Python web framework that allows you to quickly create a web application. Django generally follows the MVC (Model-View-Controller) design pattern. Django version 0.96 is included with the Google App Engine SDK, but there are still a few steps required to make it work.

The main.py and settings.py files are created/edited using the instructions provided by Google at http://code.google.com/appengine/articles/django.html. I won't explain the code here as the Google page has a decent explanation.

The urls.py file contains the code necessary to map a URL (like http://mytestgae.appspot.com) to a Django view (the V in MVC) function. In the sample application there is one such mapping defined:

(r'^$', 'myapp.views.index')

The first element in the tuple is a regular expression that matches a URL. In this case the URL we are matching is the blank root URL. The ^ character defines the start of the URL, and the $ character defines the end of the URL. So the regular expression "^$" means an empty URL.

The seconds part of the tuple is the function that will be called when this URL is viewed. In our case we want to run the myapp.views.index function.

The end result of this is that when someone clicks a link like http://mytestgae.appspot.com the system will run the myapp.views.index function and display the result.

The myapp\models.py file contains the model definitions (the M in MVC). You'll see that we have defined one model called BrowserType. This model represents the data that is saved in the Google App Engine database.

Inside the BrowserType model we have two properties: userAgent and browserCount. Both are created using one of the classes exposed by the Google App Engine SDK. In our case userAgent property is a string, and browserCount is an integer, set to zero by default.

The myapp\views.py file contains the functions that will be called when a URL is opened. It's in here that we define the index function that we mapped to the enpty URL inside the urls.py file.

Strictly speaking in a MVC application the view functions would be very simple functions with only a few lines of code calling controller functions (the C in MVC). Controller functions are where the application logic resides. However in such a simple application I have put the application logic directly into the view function.

The first thing we do in the index function is get a record in the database with the same HTTP_USER_AGENT as the current browser.

myBrowser = models.BrowserType.all().filter('userAgent =', request.META['HTTP_USER_AGENT']).get()

models.BrowserType.all() creates Query that represents all the BrowserType records stored in the database.

.filter('userAgent =', request.META['HTTP_USER_AGENT']) filters the query looking for those records that match the current browsers HTTP_USER_AGENT.

.get() retrieves the first such record, or None if none exist.

if myBrowser == None:
myBrowser = models.BrowserType(userAgent=request.META['HTTP_USER_AGENT']) creates a new BrowserType record id the previous line failed to find any matches.

myBrowser.browserCount = myBrowser.browserCount + 1 takes the record and increments the browserCount property to reflect the fact that a browser of that type has just viewed the page.

myBrowser.put() saves the record back to the database.

browsers = models.BrowserType.all().fetch(100) fetches the first 100 BrowserType records that exist in the database.

payload = dict(browsers = browsers) creates a dictionary that will be sent to the Django page rendering funtion to populate a base HTML template page with the data we just recovered from the database.

return render_to_response('main.html', payload) tells Django to render the template main.html with the data stored in the payload dictionary.

The templates\main.html file is a Django template. It is mostly standard HTML, except for a few lines that display information sent to the page by Django.

The code payload = dict(browsers = browsers) in the index function basically creates an object called browsers which is available to the template when rendering. The template code {% for browser in browsers %} loops through the records in browsers. We then use {{browser.userAgent}} and {{browser.browserCount}} to add this dynamic data to rows in a HTML table.

And there you have it. A quick and dirty introduction to using Django with the Google App Engine service.