Extensible Calendar
This page documents an example of using the Extensible Calendar Pro API with Django as the back end.
REST
The Extensible Calendar is going to connect to your server via AJAX calls. These calls conform to a web application paradigm known as REST, or REpresentational State Transfer. In particular, the application will automatically send requests with the following HTTP methods:
- GET when it wants to read something
- POST when it wants to create something
- PUT when it wants to change something
- DELETE when it wants to remove something
You recognize GET and POST from Module 2. All along, there were actually more than just these two request methods. REST simply takes advantage of all of them.
Note: In practice, since older browsers do not support the additional HTTP request methods required by REST, the actual implementation of PUT and DELETE will most likely be POST with an additional header defining the request type. The frameworks takes care of this difference under the hood.
The Back End
First, we will set up the back end.
Creating the App with Source Control
Start by making a new Django project and app.
$ django-admin.py startproject cse330calendar
$ cd cse330calendar
$ python manage.py startapp cal
Right now would be a good time to set up your IDE and source control. Create a new Komodo project in the "cse330calendar" directory, and set up a repo on the "cse330calendar" in SourceTree. Make frequent commits after each step of the process.
Initial Configuration
Go into settings.py and configure your database.
Enable the admin panel, which requires editing both settings.py and urls.py. Add the cal application to the admin panel by creating cal/admin.py with the following content:
from django.contrib import admin
# We will create these models in the next step
from cal.models import Cal, Event
admin.site.register(Cal)
admin.site.register(Event)
Finally, add "cal" to the INSTALLED_APPS list in settings.py.
Creating the Models
Set up the models required for the Extensible Calendar. We have already done this work for you. Copy the following code into your cal/models.py file.
from django.db import models
# Extensible wants two models: a "calendar" model and an "event" model.
# The "calendar" model represents a collection of events. Note that the end
# application supports multiple calendars in the same view, with the events
# in each calendar having a different background color.
#
# First we will define our calendar model, `Cal`, and then we will define
# our event model, `Event`.
class Cal(models.Model):
# Title of the calendar
title = models.CharField(max_length=50)
# Text description of the calendar
description = models.CharField(max_length=200)
# Color ID (1-32)
color = models.IntegerField(default=1)
# Boolean for whether the calendar is hidden by default
hidden = models.BooleanField(default=False)
class Event(models.Model):
# Declare a one-to-many relationship with Cal
cal = models.ForeignKey(Cal)
# Title of the event
title = models.CharField(max_length=50)
# DateTime of event start
start = models.DateTimeField()
# DateTime of event end
end = models.DateTimeField()
# Additional information that can be associated with an event:
loc = models.CharField(max_length=50) # Location
notes = models.CharField(max_length=200) # Notes
url = models.CharField(max_length=100) # URL
ad = models.BooleanField(default=False) # Is this an all-day event
rem = models.CharField(max_length=200) # Reminder
Finally, sync the db. After you do this, run the Django server and play around with the admin panel to make sure everything is in working order.
$ python manage.py syncdb
Tastypie
Django does not come with REST support out of the box, so we need to install an additional framework. I have so far had success with Tastypie, and I will be using Tastypie throughout this tutorial.
Start by installing Tastypie. There are instructions on the above link.
Your cal/api.py file can contain simply:
from tastypie.resources import ModelResource
from tastypie.paginator import Paginator
from cal.models import Cal, Event
from tastypie.fields import ToOneField
class CalResource(ModelResource):
class Meta:
queryset = Cal.objects.all()
paginator_class = Paginator
class EventResource(ModelResource):
cid = ToOneField(CalResource, "cal", full=True)
class Meta:
queryset = Event.objects.all()
paginator_class = Paginator
always_return_data = True
def dehydrate_cid(self, bundle):
return bundle.obj.cal.id
In the above snippet, we also are installing the Paginator utility. The Extensible Calendar requires that your data have pagination.
You will be modifying this file later on in this tutorial.
I also recommend making JSON the default output format for Tastypie. To do this, add the following line to your settings.py file:
TASTYPIE_DEFAULT_FORMATS = ['json']
While you're inside settings.py, go ahead and add the following line as well. It may save you headaches down the road.
APPEND_SLASH=False
Routing
Let's create an empty index.html for our site. We will be modifying it later. Create the file in cal/templates/cal/index.html. Then add it to cal/views.py:
from django.shortcuts import render
def index(request):
return render(request, 'cal/index.html', {})
Also add it to cal/urls.py:
from django.conf.urls import patterns, url
from cal import views
urlpatterns = patterns('',
url(r'^$', views.index, name='index')
)
Finally, add cal to your core urls.py file, which by now should look something like this:
from django.conf.urls import patterns, include, url
from cal.api import CalResource, EventResource
# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()
# RESTful setup:
cal_resource = CalResource()
event_resource = EventResource()
urlpatterns = patterns('',
# Admin page
url(r'^admin/', include(admin.site.urls)),
# Templates
url(r'^', include('cal.urls')),
# RESTful URLs
url(r'^', include(cal_resource.urls)),
url(r'^', include(event_resource.urls)),
)
Try launching http://localhost:8000/cal/ in your browser. If everything is working properly, you should see a JSON representation of the data in your calendar.
Additional Work on the Back End
In the above example, we have implemented a read-only API for your calendar. You will need to use Django Auth to add users and to only reveal those calendars associated with a user. You will also need to implement the writing site of Tastypie. Almost all of these steps are in the Tastypie documentation.
The Front End
So far, all of our work has been setting up our database, models, and server API. Now, we need to set up the front end that takes the JSON data and displays it in a GUI for the end user.
Installing Extensible
Start by downloading the Extensible library from the official web site. Save the download in cal/static/vendor/extensible.
Extensible Config File
Copy the file at cal/static/vendor/extensible/Extensible-config.js into the cal/static/cal directory. Make the following changes:
- Change the Ext JS version on line 59 from 4.2.0 to 4.1.1
- Comment out the line that includes the examples.js file (around line 179)
The Core Extensible Code
The examples on the Extensible documentation are helpful, but if you have never used Ext.JS before, it is easy to get lost. We have therefore written an index.html file and an app.js file to get you started.
Put the following code in cal/templates/cal/index.html:
<!DOCTYPE html>
{% load staticfiles %}
<html>
<head>
<title>Calendar</title>
<script type="text/javascript" src="{% static 'cal/Extensible-config.js' %}"></script>
<script type="text/javascript" src="{% static 'cal/app.js' %}"></script>
</head>
<body>
<div id="calbox" style="width:600px; height:400px;"></div>
<span id="app-msg" class="x-hidden"></span>
</body>
</html>
Put the following code in cal/static/cal/app.js:
// Demo Extensible Calendar App
// Created for CSE 330S by Shane Carr
// Washington University in St. Louis
// Ext.JS wants you to use `Ext.define` when making a custom component.
Ext.define("CSE330.Calendar", {
// List the classes we use inside this component. This enables Ext.JS to load
// the files containing the definitions for these classes more efficiently.
requires: [],
// Main code for our component
constructor: function(){
// Set up the calendar store
this.calendarStore = Ext.create("Extensible.calendar.data.MemoryCalendarStore", {
autoLoad: true,
storeId: "Calendars",
proxy: {
type: "rest",
url: "/cal/",
startParam: "offset",
reader: {
type: "json",
root: "objects"
},
writer: {
type: "json",
nameProperty: "mapping"
}
}
});
// Set up the event store
this.eventStore = Ext.create("Extensible.calendar.data.MemoryEventStore", {
autoLoad: true,
storeId: "Events",
proxy: {
type: "rest",
url: "/event/",
startParam: "offset",
reader: {
type: "json",
root: "objects",
},
writer: {
type: "json",
nameProperty: "mapping"
}
}
});
// Set up the panel (view)
this.container = Ext.create('Extensible.calendar.CalendarPanel', {
renderTo: Ext.get("calbox"),
title: "My CSE330 Calendar",
width: "100%",
height: "100%",
id: "ext-calendar-main",
eventStore: this.eventStore,
calendarStore: this.calendarStore,
monthViewCfg: {
showHeader: true // show the days of the week
}
});
}
});
Ext.onReady(function(){
Ext.create("CSE330.Calendar");
});
You should be able to load http://localhost:8000/ and see an empty calendar with all events you have thusfar put in your database. Exciting!
Additional Work on the Front End
Again, right now you have a read-only calendar without any sort of authentication. You need to tie these two pieces together.
If you look at the web inspector, you can see the requests that Extensible sends to your server when you try to create or modify an event using the front-end GUI. You need to make sure that your server and Extensible work together, both sending and receiving compatible formats.
You can implement log in and log out over AJAX via the Tastypie API. There are examples of how to do this in the documentation.
Help with Debugging
Wrapping your head around Extensible, Django-Tastypie, and how to make the two frameworks talk to each other is a daunting task. The goal of this section is to help you learn how to debug this process.
Tutorial for Debugging the Create Event Mechanism
Let's first take a look at what happens when you try to add a new event via the Extensible GUI. When you click somewhere on the calendar, a little dialog opens, and in it you can specify the details of your event. However, when you press "Save", you see the following error in the console:
Whoopsy daisy, we got a 401 Unauthorized from the server! This means that Django-Tastypie thinks that we don't have enough permissions to edit this resource. We need to tell Tastypie that we do indeed have such permissions.
Let's temporarily open up the event to be globally editable. Refer to this section of the Tastypie guide for an example of how to do this. Try figuring it out on your own before reading on.
You may have figured out that we need to specify these changes inside the cal/api.py file. In particular, if we add the following line to the Meta of the EventResource class, we in effect open up the resource to be globally editable.
# Add to the Event meta
authorization = Authorization()
# don't forget to put an import statement at the top of your file!
# from tastypie.authorization import Authorization
Great! Now let's try sending our request again. You'll see that you get a 400 Bad Request error. That sounds scary! What's happening?
Let's head on over to the "Network" panel of the web inspector. Scroll to the bottom of the page to find the latest network request. Click it, and then choose the "Response" tab. You'll see something like this:
Hey, look! There's an error that we can fix. Let's look at it in more detail.
The 'cid' field was given data that was not a URI, not a dictionary-alike and does not have a 'pk' attribute: 1.
It sounds like Tastypie doesn't like whatever we're sending as the cid field. Let's go check on what we're actually sending. To do this, click on the "Headers" tab in the web inspector, and scroll down to "Request Payload".
So we're clearly sending an integer calendar ID in the cid field. Why wouldn't Tastypie like this? I don't know; let's google the error!
Note that when we google something, we need to take specific field names out of our search. In our case, this is the "cid" field name as well as the value of "1". With that in mind, here are the hits:
Look at that! We're clearly not the first people to run into this error.
The first Stack Overflow question looks verbose. Let's try the second one.
Hey, you find something that might provide you a clue!
So we need to make our data field resemble one of those two options: either a dictionary with a "pk" field or a resource URL.
But how can we change the data format? We could do it from the Extensible side, or we could do it from the Tastypie side. Since we have greater control over Tastypie than Extensible, let's do it on the Tastypie side.
The Resources guide for Tastypie seems like a reasonable place to start. Read it and try to find the method that enables you to modify incoming data before Tastypie puts it into the model.
If you pinpointed the hydrate_FOO method, you were right! We simply need to define this method to transform the incoming data into the format that Tastypie wants.
Based on the "simple example" under hydrate_FOO, the following definition seems reasonable.
# Part of the EventResource class
def hydrate_cid(self, bundle):
bundle.data["cid"] = "/cal/%d/" % bundle.data["cid"]
return bundle
Here, we are transforming the incoming cid number to a resource URL. For example, 3 will be transformed into /cal/3/, the format that Tastypie wants according to the Stack Overflow post.
Okay, great! Let's save and see where we stand. Try creating an event through the GUI.
Hey, it looks like something happened! We received a 201 request back from the server! Let's take a peek at our database. Enter a Django shell and enter the following commands.
# Run these commands inside a Django shell
from cal.models import Cal, Event
map(lambda v: "%d %s" % (v.id, v.title), Event.objects.all())
The first line imports your modules into the shell, and the second line queries them via ORM and displays a list of the events with an ID and a title.
What do you see that's interesting? Hey, the "Banana Event" that I just added has ID 0! That's not cool. How do we fix it?
You may remember from the Django tutorial that Django will automatically assign the next available ID if you leave the id field empty in the new model. So, let's go ahead and transform all 0 IDs in Tastypie to None.
Try writing the necessary hydrate_id method. You should get something like the following:
# Part of the EventResource class
def hydrate_id(self, bundle):
if bundle.data["id"] == 0:
bundle.data["id"] = None
return bundle
Save and try again. What do you know, it works now! Each new event is now assigned a unique ID.
Next Steps
So hopefully you now have the knowledge you need to complete the module. In summary, when you need help, do the following:
- Look at the web inspector console
- Look at the network activity
- Look at the server log
- When you find an error that looks useful, google it (remove application-specific terms)
- When fixing the problem, refer to documentation
- When the problem is fixed, commit your code!
If you still need help, ask in class or come to office hours.
