3. Getting Started¶

Warning

This documentation is under construction. See the Documentation Status page in wiki for the current status and timeline.

3.1. Introduction¶

This chapter narrates creating a web application project using BlueBream. If you complete this chapter, you should be able to:

Install PasteScript based BlueBream project template
Create a BlueBream application project using the template
Bootstrap the build system (Buildout) and build the application
Run WSGI based web server to serve the application
Run test cases and use the debug shell
Create Hello World applications

Before proceeding, here is an overview of the sections.

Preparations: – Prerequisites and preparations you need to make to start a web application project using BlueBream.
Installation: – Instructions for installing BlueBream.
Creating a sample project: – Explain creating a sample project using bluebream project template.
Building the application: – Explain how to build the application using Buildout.
Basic usage: – Explain the basic usage of BlueBream commands.
Package directory structure: – Show the directory structure and describe the purpose of each directories and files.
At the end, a few hello world examples are also given.

3.2. Preparations¶

This document assume that you have already installed Python 2.6 and setuptools. As an alternative to setuptools, you can install distribute. If setuptools or distribute is installed you will get an easy_install command which you can use to install bluebream distribution.

You can also install BlueBream inside a Python environment created using virtualenv. Although, virtualenv may not be required when you are working on the application itself. Because, Buildout support will available in the application created. Buildout is the recommended approach to create repeatable, isolated working environments. Buildout is a declarative, configuration driven build system created by Jim Fulton.

It is recommended to use a custom built Python for working with BlueBream. You will be required to install a C compiler (gcc) in your system. Internet access to PyPI is required to perform installation of bluebream distribution. Later, to build the application using Buildout and to bootstrap the buildout itself, you need internet access. But for deployment, you can avoid the internet access using zc.sourcerelease package.

3.3. Installation¶

If you have installed setuptools or distribute an easy_install command will be available. Then, you can install BlueBream using easy_install command like this:

$ easy_install bluebream

As mentioned earlier, Internet access to PyPI is required to perform installation of bluebream distribution. If you use any proxy, make sure it works. The easy_install will look for the environment variable named http_proxy in GNU/Linux platforms. You can set it like this:

$ set http_proxy="http://username:password@PROXY-IP-ADDRESS:PORT"

Apart from bluebream distribution, easy_install will download and install its dependencies. The dependencies are:

The installation of bluebream project template package is a one time process. Once the project package is ready, you don’t require the bluebream project template package anymore. Because, the project package you are going to create will be self-bootstrappable.

3.4. Creating a sample project¶

The bluebream distribution provides project templates based on PasteScript template. Once BlueBream is installed, run paster command to create the project directory structure. The create sub-command provided by paster will show a wizard to create the project directory structure.

$ paster create -t bluebream

This will bring a wizard asking details about your new project. If you provide package name, namespace package name and version number, you will get a working application which can be modified further. The project name will be used as the name of egg. You can also change the values provided later.

Here is a screenshot of sample project creation:

The project name can be give given as a command line argument:

$ paster create -t bluebream sampleproject

The name of namespace package also can be given from the command line:

$ paster create -t bluebream sampleproject namespace_package=mycompany

If you provide an option from the command line, it will not be prompted by the wizard. The other variables are give below, you may be give the values from command line, if required:

interpreter – Name of custom Python interpreter
version – Version (like 0.1)
description – One-line description of the package
long_description – Multi-line description (in reST)
keywords – Space-separated keywords/tags
author – Author name
author_email – Author email
url – URL of homepage
license_name – License name
zip_safe – True, if the package can be distributed as a .zip file otherwise False.

If you are in a hurry, you can simply press Enter/Return key and change the values later. But it would be a good idea, if you provide a good name for your project.

Note

Alternate Project Templates

Alternate project templates will be available from 1.0b1 release onwards, and it is documented in the wiki.

3.5. Building the application¶

As mentioned earlier, the generated package is bundled with Buildout configuration (buildout.cfg) and Buildout bootstrap script (bootstrap.py). First you need to bootstrap the buildout itself:

$ cd sampleproject
$ python2.6 bootstrap.py

The bootstrap script will install zc.buildout and setuptools package. Also, it will create the basic directory structure.

Here is a screenshot of bootstrapping the buildout:

Next step is building the application. To build the application, run the buildout:

$ ./bin/buildout

Here is a screenshot of building the application:

The buildout script will download all dependencies and setup the environment to run your application. The next section will show the basic usage.

3.6. Basic usage¶

The most common thing you need while developing application is running the server. BlueBream use paster command provided by PasteScript to run the WSGI server. To run the server, you can pass the PasteDeploy configuration file as the argument to serve sub-command as given here:

$ ./bin/paster serve debug.ini

After running the server, you can access the site from browser here: http://localhost:8080/ . The port number (8080) can be changed from the PasteDeploy configuration file (debug.ini).

When you open the browser, it will look like as given in this screenshot:

The second most common thing must be running the test cases. BlueBream by create a testrunner using the zc.recipe.testrunner Buildout recipe. You can see a test command inside the bin directory. To run test cases, you can run this command:

$ ./bin/test

Sometimes you may want to get the debug shell. BlueBream provides a Python prompt with your application object. You can invoke the debug shell like this:

$ ./bin/paster shell debug.ini

More about the test runner and debug shell will be exaplained in the BlueBream Manual.

3.7. Package directory structure¶

The default directory structure created by the bluebream paster project template will look like this:

myproject/
|-- bootstrap.py
|-- buildout.cfg
|-- debug.ini
|-- deploy.ini
|-- etc/
|   |-- site.zcml
|   `-- zope.conf
|-- setup.py
|-- src/
|   |-- mynamespace.egg-info/
|   `-- mynamespace/
|       |-- __init__.py
|       `-- main/
|           |-- application.zcml
|           |-- app.py
|           |-- configure.zcml
|           |-- debug.py
|           |-- ftesting.zcml
|           |-- __init__.py
|           |-- interfaces.py
|           |-- README.txt
|           |-- securitypolicy.zcml
|           |-- startup.py
|           |-- tests.py
|           |-- views.py
|           `-- static/
|               |-- logo.png
|               `-- style.css
|-- templates/
|   `-- zope_conf.in
|-- var/
`-- versions.cfg

The name of top-level directory will be always what you gave as project name in the wizard. The name of egg also will be same as that of package name by default. But if you want, you can change it to something else from setup.py. Here are the details about other files inside the project.

3.7.1. Files & Purpose¶

bootstrap.py – Bootstrap script for Buildout
buildout.cfg – The buildout configuration
debug.ini – The PasteDeploy configuration for development
deploy.ini – The PasteDeploy configuration for deployment
etc/ – A location to add configuration files
etc/site.zcml – The main ZCML file
etc/zope.conf – The main Zope configuration file (generated from template)
setup.py – Project meta-data for creating distribution
src/ – All source code will be residing inside this directory
src/mynamespace.egg-info/ – This is where all distribution related info residing
src/mynamespace/ – The namespace package
src/mynamespace/__init__.py – This file with default content would be enough to make this a namespace package.
src/mynamespace/main/ – This is the main package which contains your application code.
src/mynamespace/main/application.zcml – Boiler plate ZCML to include other application specific ZCMLs. Now only the main package is included, you can add other ZCMLs from here.
src/mynamespace/main/app.py – The main application object implementation. Replace the sample implementation with your application.
src/mynamespace/main/configure.zcml – You can customize this ZCML which is included from application.zcml
src/mynamespace/main/debug.py – The debug application object. The class given here will be registered from an entry point.
src/mynamespace/main/ftesting.zcml – ZCML for functional testing
src/mynamespace/main/__init__.py – The main package
src/mynamespace/main/interfaces.py – Interface definitions
src/mynamespace/main/README.txt – main packages’ README
src/mynamespace/main/securitypolicy.zcml – security policy declarations which is included from site.zcml
src/mynamespace/main/startup.py This script is called by WSGI server to start the application. (Mostly boiler plate code)
src/mynamespace/main/tests.py – Boiler plate to register tests.
src/mynamespace/main/views.py – An example view.
src/mynamespace/main/static/ – Static resource files (images, CSS etc.)
templates/ – Buildout specific templates used by “collective.recipe.template”
templates/zope_conf.in – Zope conf template, modify this file for any change in zope.conf
var/ – A place holder directory for storing all ZODB files, log files etc.
versions.cfg – All versions of files can be pinned down here.

The next few sections will explain how to create hello world applications.

3.8. Example 1: Hello World without page template¶

You can watch the video creating hello world application here:

To create a web page which displays Hello World!, you need to create a view class and register it using browser:page ZCML directive. In BlueBream, this is called as Browser Page. Sometimes more generic term, View is used instead of Browser Page which can be used to refer to HTTP, XMLRPC, REST and other views. By default, the default page which you are getting when you access: http://localhost:8080 is a page registered like this. You can see the registration inside configure.zcml, the name of view will be index. You can access the default page by explicitly mentioning the page name in the URL like this: http://localhost:8080/@@index. You can refer the Default view for objects HOWTO for more details about how the default view for a container object is working.

First you need to create a Python file named myhello.py at src/mynamespace/main/myhello.py:

$ touch src/mynamespace/main/myhello.py

You can define your browser page inside this module. All browser pages should implement zope.publisher.interfaces.browser.IBrowserView interface. An easy way to do this would be to inherit from zope.publisher.browser.BrowserView which is already implementing the IBrowserView interface.

The content of this file could be like this:

from zope.publisher.browser import BrowserView

class HelloView(BrowserView):

    def __call__(self):
        return "Hello World!"

Now you can register this page for a particular interface. So that it will be available as a browser page for any object which implement that particular interface. Now you can register this for the root folder, which is implementing zope.site.interfaces.IRootFolder interface. So, the registration will be like this:

<browser:page
   for="zope.site.interfaces.IRootFolder"
   name="hello"
   permission="zope.Public"
   class=".myhello.HelloView"
   />

Since you are using the browser XML namespace, you need to advertise it in the configure directive:

<configure
   xmlns="http://namespaces.zope.org/zope"
   xmlns:browser="http://namespaces.zope.org/browser">

You can add this configuration to: src/mynamespace/main/configure.zcml. Now you can access the view by visiting this URL: http://localhost:8080/@@hello

Note

The @@ symbol for view

@@ is a shortcut for ++view++. (Mnemonically, it kinda looks like a pair of goggle-eyes)

To specify that you want to traverse to a view named bar of content object foo, you could (compactly) say .../foo/@@bar instead of .../foo/++view++bar.

Note that even the @@ is not necessary if container foo has no element named bar - it only serves to disambiguate between views of an object and things contained within the object.

3.9. Example 2: Hello World with page template¶

In this example, you will create a hello world using a page template.

3.9.1. Create a page template¶

First you need to create a page template file inside your package. You can save it as src/mynamespace/main/helloworld.pt, with the following content:

<html>
  <head>
    <title>Hello World!</title>
  </head>
  <body>
    <div>
      Hello World!
    </div>
  </body>
</html>

3.9.2. Register the page¶

Update configure.zcml to add this new page registration.

<browser:page
  name="hello2"
  for="*"
  template="helloworld.pt"
  permission="zope.Public" />

This declaration means: there is a web page called hello2, available for any content, rendered by the template helloworld.pt, and this page is public. This kind of XML configuration is very common in BlueBream and you will need it for every page or component.

In the above example, instead of using zope.site.interfaces.IRootFolder interface, * is used. So, this view will be available for all objects.

Restart your application, then visit the following URL: http://127.0.0.1:8080/@@hello2

3.10. Example 3: A dynamic hello world¶

This section explain creating a dynamic hello world application.

3.10.1. Python class¶

In the src/mynamespace/main/hello.py file, add few lines of Python code like this:

class Hello(object):

    def getText(self):
      name = self.request.get('name')
      if name:
        return "Hello %s !" % name
      else:
        return "Hello ! What's your name ?"

This class defines a browser view in charge of displaying some content.

3.10.2. Page template¶

Now you need a page template to render the page content in html. So let’s add a hello.pt in the src/mynamespace/main directory:

<html>
  <head>
    <title>hello world page</title>
  </head>
  <body>
    <div tal:content="view/getText">
      fake content
    </div>
  </body>
</html>

The tal:content directive tells zope to replace the fake content of the tag with the output of the getText method of the view class.

3.10.3. ZCML registration¶

The next step is to associate the view class, the template and the page name. This is done with a simple XML configuration language (ZCML). Edit the existing file called configure.zcml and add the following content before the final </configure>:

<browser:page name="hello3"
    for="*"
    class=".hello.Hello"
    template="hello.pt"
    permission="zope.Public" />

This declaration means: there is a web page called hello3, available for any content, managed by the view class Hello, rendered by the template hello.pt, and this page is public.

Since you are using the browser XML namespace, you need to declare it in the configure directive. Modify the first lines of the configure.zcml file so it looks like this (You can skip this step if the browser namespace is already there from the static hello world view):

<configure
  xmlns="http://namespaces.zope.org/zope"
  xmlns:browser="http://namespaces.zope.org/browser">

Restart your application, then visit the following URL: http://127.0.0.1:8080/@@hello3

You should then see the following text in your browser:

Hello ! What's your name ?

You can pass a parameter to the Hello view class, by visiting the following URL: http://127.0.0.1:8080/@@hello3?name=World

You should then see the following text:

Hello World !

3.11. Conclusion¶

This chapter walked through the process of getting started with web application development with BlueBream. Also introduced few simple Hello World example applications. The Tutorial — Part 1 chapter will go through a bigger application to introduce more concepts.

blog comments powered by Disqus

3. Getting Started¶

3.1. Introduction¶

3.2. Preparations¶

3.3. Installation¶

3.4. Creating a sample project¶

3.5. Building the application¶

3.6. Basic usage¶

3.7. Package directory structure¶

3.7.1. Files & Purpose¶

3.8. Example 1: Hello World without page template¶

3.9. Example 2: Hello World with page template¶

3.9.1. Create a page template¶

3.9.2. Register the page¶

3.10. Example 3: A dynamic hello world¶

3.10.1. Python class¶

3.10.2. Page template¶

3.10.3. ZCML registration¶

3.11. Conclusion¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

3. Getting Started¶

3.1. Introduction¶

3.2. Preparations¶

3.3. Installation¶

3.4. Creating a sample project¶

3.5. Building the application¶

3.6. Basic usage¶

3.7. Package directory structure¶

3.7.1. Files & Purpose¶

3.8. Example 1: Hello World without page template¶

3.9. Example 2: Hello World with page template¶

3.9.1. Create a page template¶

3.9.2. Register the page¶

3.10. Example 3: A dynamic hello world¶

3.10.1. Python class¶

3.10.2. Page template¶

3.10.3. ZCML registration¶

3.11. Conclusion¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation