This guide will walk you through building a simple Pecan web application that uses AJAX to fetch JSON data from a server.
First, you’ll need to install Pecan:
$ pip install pecan
Use Pecan’s basic template support to start a new project:
$ pecan create myajax
$ cd myajax
Install the new project in development mode:
$ python setup.py develop
For this project we will need to add jQuery support. To add jQuery go into the templates folder and edit the layout.html file.
Adding jQuery support is easy, we actually only need one line of code:
<script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
The JavaScript to make the AJAX call is a little more in depth but shouldn’t be unfamiliar if you’ve ever worked with jQuery before.
The layout.html file will look like this:
<html>
<head>
<title>${self.title()}</title>
${self.style()}
${self.javascript()}
</head>
<body>
${self.body()}
</body>
</html>
<%def name="title()">
Default Title
</%def>
<%def name="style()">
<link rel="stylesheet" type="text/css" media="screen" href="/css/style.css" />
</%def>
<%def name="javascript()">
<script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
<script language="text/javascript" src="/javascript/shared.js"></script>
<script>
function onSuccess(data, status, jqXHR) {
// Use a template or something here instead
// Just for demo purposes
$("#result").html("<div>" +
"<p></p><strong>Project Name: " + data.name + "</strong></p>" +
"<p>Project License: " + data.licensing + "</p>" +
"<p><a href='" + data.repository + "'>Project Repository: " + data.repository + "</a></p>" +
"<p><a href='" + data.documentation + "'>Project Documentation: " + data.documentation + "</a></p>" +
"</div>");
}
function onError(jqXHR, textStatus, errorThrown) {
alert('HTTP Status Code: ' + jqXHR.status + ', ' + errorThrown);
}
$(document).ready(function () {
$("#submit").click(function () {
$.ajax({
url: "/projects/",
data: "id=" + $("#projects").val(),
contentType: 'application/json',
dataType: 'json',
success: onSuccess,
error: onError
});
return false;
});
});
</script>
</%def>
What did we just do?
Let’s edit the index.html file next. We will add HTML to support the AJAX interaction between the web page and Pecan. Modify index.html to look like this:
<%inherit file="layout.html" />
<%def name="title()">
Welcome to Pecan!
</%def>
<header>
<h1><img src="/images/logo.png"/></h1>
</header>
<div id="content">
<p>Select a project to get details:</p>
<select id="projects">
<option value="0">OpenStack</option>
<option value="1">Pecan</option>
<option value="2">Stevedore</option>
</select>
<button id="submit" type="submit">Submit</button>
<div id="result"></div>
</div>
What did we just do?
The HTML and JavaScript work is now taken care of. At this point we can add a model to our project inside of the model folder. Create a file in there called projects.py and add the following to it:
class Project(object):
def __init__(self, name, licensing, repository, documentation):
self.name = name
self.licensing = licensing
self.repository = repository
self.documentation = documentation
def __json__(self):
return dict(
name=self.name,
licensing=self.licensing,
repository=self.repository,
documentation=self.documentation
)
What did we just do?
Note
There are other ways to return JSON with Pecan, check out JSON Serialization for more information.
We don’t need to do anything major to the root.py file in the controllers folder except to add support for a new controller we will call ProjectsController. Modify the root.py like this:
from pecan import expose
from myajax.controllers.projects import ProjectsController
class RootController(object):
projects = ProjectsController()
@expose(generic=True, template='index.html')
def index(self):
return dict()
What did we just do?
The final piece is to add a file called projects.py to the controllers folder. This new file will host the ProjectsController which will listen for incoming AJAX GET calls (in our case) and return the appropriate JSON response.
Add the following code to the projects.py file:
from pecan import expose, response
from pecan.rest import RestController
from myajax.model.projects import Project
class ProjectsController(RestController):
# Note: You would probably store this information in a database
# This is just for simplicity and demonstration purposes
def __init__(self):
self.projects = [
Project(name='OpenStack',
licensing='Apache 2',
repository='http://github.com/openstack',
documentation='http://docs.openstack.org'),
Project(name='Pecan',
licensing='BSD',
repository='http://github.com/pecan/pecan',
documentation='http://pecan.readthedocs.org'),
Project(name='stevedore',
licensing='Apache 2',
repository='http://github.com/dreamhost/pecan',
documentation='http://stevedore.readthedocs.org')
]
@expose('json', content_type='application/json')
def get(self, id):
response.status = 200
return self.projects[int(id)]
What did we just do?
Run the application:
$ pecan serve config.py
Open a web browser: http://127.0.0.1:8080/
There is something else we could add. What if an id is passed that is not found? A proper HTTP 404 should be sent back. For this we will modify the ProjectsController.
Change the get function to look like this:
@expose('json', content_type='application/json')
def get(self, id):
try:
response.status = 200
return self.projects[int(id)]
except (IndexError, ValueError) as ex:
abort(404)
To test this out we need to pass an invalid id to the ProjectsController. This can be done by going into the index.html and adding an additional option tag with an id value that is outside of 0-2.
<p>Select a project to get details:</p>
<select id="projects">
<option value="0">OpenStack</option>
<option value="1">Pecan</option>
<option value="2">Stevedore</option>
<option value="3">WSME</option>
</select>
You can see that we added WSME to the list and the value is 3.
Run the application:
$ pecan serve config.py
Open a web browser: http://127.0.0.1:8080/
Select WSME from the list. You should see the error dialog box triggered.