Quickstart

In this Quickstart tutorial, I'll be building a simple web application for rendering static web pages. In this tutorial, you'll learn how to:

• Take advantage of the minimally configured vanilla whirlwind application
• Add Controller logic to handle requests from the client
• Add new templates and edit already existing templates for rendering.

1. Installation and Configuration

First, you'll need to install (and maybe configure) whirlwind if you haven't already done so. Please see the installation instructions.

2. Create a new application

Go on to create a new whirlwind application (in this case, called quickstart-app) in your directory of choice:

whirlwind-admin.py --create-application quickstart-app

If you see the message INFO Created True, then creating the app was successful. You can cd into the app: cd quickstart-app.

3. Port Configuration (optional step)

If you are already running another application on the default port 8000, then change the port you want your app to run on: Edit the file config/settings.py. Set the variable port to a different port (maybe 8001).

4. Run the Application and explore

Guess what, you are all set to begin using your application. Just start the server via:

python main.py

You should see the message Ready and listening. Otherwise, refer to our FAQ for more instructions on how to fix the problem.

In your browser, navigate to localhost:8000. You should see a default page. Yeah!

In your terminal, cd into the application sub-directory. You should see models, views, and controllers. These are the three sub-directories we'll be working with in this tutorial. Let's move on!

5. Create and edit the views you wish to display .

In step (4), we displayed the root page. This page was rendered by the IndexHandler class in the application/controllers/site_controller.py. This page looks like this:

@route('/')                                                                   
class IndexHandler(BaseRequest):                                              
   def get(self):                                                            
      #template context variables go in here                                
      template_values = {}                                                  
                                                                               
      self.render_template('/site/index.html',**template_values)

IndexHandler is a subclass of the whirlwind python class BaseRequest. Refer to the documentation here.

What the above code does is just render the mako template defined in views/site/index.html. index.html looks like this:

<%inherit file="/layouts/content.html" />                                     
                                                                         
<%def name="body()">                                                          
  <div id="page-header">                                                        
    <div class="title">                                                   
            Welcome to Whirlwind                                          
    </div>                                                                
    <div class="subtitle">                                                
            You've successfully setup a new whirlwind app!                
    </div>                                                                
  </div>                                                                        
  <div id="page-content">                                                       
    <div class="body">                                                    
      <a href="http://github.com/trendrr/whirlwind" target="new">Check out our docs on github.com to get started</a>                             
    </div>                                                                
  </div>                                                                        
                                                                          
</%def> 

Refer to the documentation on views for more information on how site pages and layout pages. The template is evaluated against a mako template rendering engine. Refer to the mako docs here.

Now create the file mine.html in application/views/site/. It should contain:

<%inherit file="/layouts/content.html" />

<%def name="body()">
    <div id="page-content">
      <div class="body">
       What I put into the template: ${ info if display_info else "no information supplied" }
       ${additional_info}
      </div>
    </div>
</%def>

info, display_info, and additional_info are context variables passed onto the view from the controller.

Next, we'll see how to make the controller set these context variables.

6. Edit the controller

Open the controller file applications/controllers/site_controller.py. Add the new handler DisplayInfoHandler to handle requests to the route /display/info/([\w]+):

@route('/display/info/([\w]+)')
class DisplayInfoHandler(BaseRequest):
    # this could've been post
    def get(self, addition):
        # set up context variables here
        template_values = {'info'            : 'Whirlwind is ',
                           'display_info'    : True,
                           'additional_info' : addition}
        # render the mine template
        self.render_template('/site/mine.html', **template_values)

The handler DisplayInfoHandler just passes in content variables to the template /site/mine.html shown in step (5).

7. Check out your changes

Now navigate (using your browser) to http://localhost:8000/display/info/mvc. You should see the message What I put into the template: Whirlwind is mvc.

---

That's it! That's your first rather trivial usage of the whirlwind framework.

This is the tip of an iceberg, check out our wiki Home page for more advanced usage of whirlwind.

Note: If you encountered any problems during this Quickstart, refer to our FAQ.

Where to go from here?

It'd be easy to add authentication (and session management) to this system. Check out the documentation on whirlwind support for session management here.

There are more links to documentation on other whirlwind features available on the Home page.