In this tutorial you will learn how to build a simple website using CherryPy, much like this very website you are visiting right now.
The source code for this tutorial is available here
What is CherryPy?
CherryPy is a pythonic, object-oriented web development framework. If you are already experienced in creating Python programs, you will feel right at home. Building a web application is done much in the same way as any other Python program as you will see in this tutorial.
You can get CherryPy here.
Please refer to the CherryPy website if you want to learn how to install and configure on your webserver, running behind Apache or not. I will use "http://localhost:8080" for running the CherryPy application described here. By the way, this is a great way of building stand alone Python apps on a local machine!
And what about CherryTemplate?
CherryPy is an open-ended Web framework that integrates with a wide variety of templating systems, see this page. For this tutorial we will use CherryTemplate because of its simplicity (and I mean that in a positive sense!).
The result
The result of this tutorial will be a simple website with one index page and one extra page. It looks something like depicted below:
The directory structure
I suggest the following directory structure for your files:
| 1 | /html |
| 2 | | |
| 3 | |-/cgi-bin |
| 4 | | |
| 5 | |-/static |
| view plain | print | copy to clipboard | ? |
The html directory will hold all the html files and the cgi-bin and static directory. The cgi-bin is where the actual CherryPy file and CherryPy's configuration file live and the static directory is for the image we will use on the webpages.
Before we start, something about the template
The templating system builds the page from several html files, schematically it looks something like this:
The mainbody.html file holds the CherryTmeplate commands ("You, there! leftmenu.html! Stand to the left of me! And you, footer.htlm! Stand below me! Header.html, come here immediately! Above me, now!!"). More about this later first we'll delve into the main script, start.py. Besides that, the mainbody also includes the 'content' files.
Start the CherryPy server
| 1 | import cherrypy |
| 2 | from cherrytemplate import renderTemplate |
| 3 | class Pages: |
| 4 | def index(self, page='home'): |
| 5 | return renderTemplate(file='../mainbody.html') |
| 6 | index.exposed = True |
| 7 | def pageone(self, page='pageone'): |
| 8 | return renderTemplate(file='../mainbody.html') |
| 9 | pageone.exposed = True |
| 10 | |
| 11 | cherrypy.root = Pages() |
| 12 | cherrypy.config.update(file = 'project.conf') |
| 13 | cherrypy.server.start() |
| view plain | print | copy to clipboard | ? |
If you are already familiair with Python, you will have no trouble reading this. The 'pages' class has two functions (using the def statements): index and pageone. Each function represents a webpage and the exposed method is there to make sure the page is accessible via your webbrowser. In the last three lines a instance of the Pages class is created, the configuration file is loaded and CherryPy's webserver is started. Of course, this is a simple example, but it shows the beauty (beauty of simplicity) of using CherryPy.
Now, create this script and put it into the appropriate directory. If you will try to run it, it won't work. You'll need some more stuff to get it working. Not much, though...
The configuration file
| 1 | [global] |
| 2 | base_url_filter.on = True |
| 3 | server.thread_pool = 10 |
| 4 | |
| 5 | [/static] |
| 6 | staticFilter.on = True |
| 7 | staticFilter.dir = "/home/yourdirectory/html/static" |
| view plain | print | copy to clipboard | ? |
This is a very basic configuration, for more options got to the CherryPy website.
The HTML stuff
In this section we will create the html files that make up the website:
The 'skeleton' files:
- mainbody.html
- leftmenu.html
- header.html
- footer.html
The 'content' files:
- contenthome.html
- contentpageone.html
mainbody.html
| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | ||||||
| 2 | <html> | ||||||
| 3 | <head> | ||||||
| 4 | </head> | ||||||
| 5 | <body> | ||||||
| 6 | <py-include="../header.html"> | ||||||
| 7 | <table style="text-align: left; width: 100%;" border="0" | ||||||
| 8 | cellpadding="2" cellspacing="2"> | ||||||
| 9 | <tbody> | ||||||
| 10 | <tr> | ||||||
| 11 | <td style="vertical-align: top; width: 160px;"><py-include="../leftmenu.html"></td> | ||||||
| 12 | <py-if="page=="home""> | ||||||
| 13 | <td style="vertical-align: top; width: 787px;"><py-include="../contenthome.html"></td> | ||||||
| 14 | </py-if> | ||||||
| 15 | <py-if="page=="pageone""> | ||||||
| 16 | <td style="vertical-align: top; width: 787px;"><py-include="../contentpageone.html"></td> | ||||||
| 17 | </py-if> | ||||||
| 18 | </tr> | ||||||
| 19 | </tbody> | ||||||
| 20 | </table> | ||||||
| 21 | <py-include="../footer.html"> | ||||||
|
|
The most interesting code in mainbody.html is the CherryTemplate specific code. This allows you to embed Python code into the html code. In this example I use the well known 'if' statement, the 'real' Python code would be something like:
| 1 | if page =="home": |
| 2 | print contenthome |
| view plain | print | copy to clipboard | ? |
CherryTemplate allows you to inject Python syntax into your html code:
- py-eval: evaluate a Python expression
- py-exec: execute one line of Python code
- py-code: execute a block of Python code
- py-if/py-else: exactly like if/else in Python
- py-for: like a for loop in Python
- py-include: include an external file in the template
leftmenu.html
| 1 | <a href="../">home</a><br> |
| 2 | <a href="../pageone">page one</a><br> |
| home page one " originalcode="home page one ">view plain | print | copy to clipboard | ? |
header.html
| 1 | Hello, I am the header! |
| 2 | <img style="width: 100px; height: 50px;" alt="" src="../static/banana.png"> |
" originalcode="Hello, I am the header!
">view plain | print | copy to clipboard | ? |
footer.html
| 1 | Hello, I am the footer |
| 2 | </body> |
| 3 | </html> |
| view plain | print | copy to clipboard | ? |
contenthome.html
| 1 | This is the homepage of the purple, flying bananas! |
| view plain | print | copy to clipboard | ? |
contentpageone.html
| 1 | Yep, page one it is |
| view plain | print | copy to clipboard | ? |
Run Py, run
After you have created all your files, and saved them in the appropriate directories, you can run the start.py script. Issue the command 'python start.py', and the CherryPy webserver should start (watch the terminal). Now start your browser, and point to 'http://localhost:8080'. And there it is, your CherryPy based website!
This tutorial is just a starting point learning to work with CherryPy. There is much, much more you can do than just building a website. Just browse the CherryPy website and be sure to check out the recipes section.
The source code for this tutorial is available here
Comments:
| 2007-08-11 | Good Tutorial! This gave me some ideas how to organize my CherryPy application, Thanx alot! |
|---|---|
| 2007-07-31 | Hello! great idea of color of this siyte! |
| 2007-06-26 | great to start |
| 2007-06-11 | this is pretty cool. Is it still useful today with the use of CSS? |
| 2007-04-24 | Nice one... is this an open source project? - RK |
| 2006-08-28 | thank you very much! --TBYang |
| 2006-05-02 | is there a way to import other classes that contain page definitions in this main file? i would like to seperate the pages to keep the source to a minimal. Thanks! |
| 2006-01-03 | Nice tutorial -- just enough to make it usable, open enough to make it flexible. Good balance, I think. Ron |
| 2005-12-23 | As requested by one of the posters below, the source code of this tutorial is now available. Dimitri |
| 2005-12-19 | Hi. I have enjoyed the tutorials on this site. A question about starting up cherrypy. When you start the cherrypy server as in your tutorial does it spin off the thread so as to free the terminal - or is your terminal tied up until you send an interrupt or kill it some other way? I am interested in starting the server on the command line so it does not tie up the terminal. Many thanks. |
| 2005-12-18 | It would nice or wonderful if this tutorial were written in spanish.. |
| 2005-12-17 | very nice .. Thank you ! --zh00yi |
| 2005-12-16 | Nice tutorial! I like the use of cherrytemplate, maybe you can use more it, with "py-for" statements, and more... Just a spelling correction: "If you are already familair with Python"... |
discuss this topic to forum
For comments on this tutorial, please use the comment textbox below. Feedback is very welcome!