µWeb

h1. µWeb

!>uweb_inernals.png!

µWeb is a Python software package designed to provide a flexible, lightweight, but powerful base to build web applications on top of. It can tie in to mod_python for Apache, or run stand-alone, using Python's included @BaseHTTPServer@ package.

µWeb provides an "MVP":http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93presenter MVC like environment, built around three core philosophies:
# as little "boilerplate":http://en.wikipedia.org/wiki/Boilerplate_code as possible;
# as little Magic™ as possible;
# and separation by convention, not brute force.

These philisophies overlap more than a little with the "Zen of Python":http://www.python.org/dev/peps/pep-0020/#content, which is not a coincidence.

h2. Installation

Details on how to install µWeb can be found on the [[installation]] page.

h2. Components

µWeb is a framework that consists of mix of components building from a low-level standalone server on top of @BaseHTTPServer@ to a refined template parser and database abstraction model.

h3. Request Router

The *[[Request Router]]* is the entry point of the µWeb framework. Any HTTP request seen by the server is passed through here, from which it is delegated to the proper handler.

h3. PageMaker and Response (_Presenter_) (_Controller_)

*[[PageMaker]]* provides the presenter controller part of the MVP MVC approach. Each web request ends on a specific method of the PageMaker. From here, request information can be viewed (cookies, query arguments and POST data), and databases used to gather data to fulfill the request. Upon completion, a raw string or a more complex *[[Response]]* object may be returned.

h3. TemplateParser (_View_)

Templates allow for a separation of presentation and logic, allowing you to move large parts of HTML or other output to a separate file. The *[[TemplateParser]]* replaces all the tags left in the template with the given output, which can be simple variables, or the use of multi-level database objects. Also, as an added benefit, the default output of TemplateParser is such that any text fed into the template, is automatically made safe for HTML output.

h3. Database abstraction (_Model_)

The *[[Model|µWeb database model]]* provides a Record class which provides for a smart interaction with your database tables. Creating a simple Record subclass for each of your (main) database tables allows you:
* to load database record by their primary key value;
* automatic retrieval of 1-1 or n-1 relations;
* creating, updating or deleting of records.

h3. HTTP Request abstraction

The *[[Request]]* class ensures that, no matter the server that accepts the request (Apache or BaseHTTPServer), the various parts further on in the framework have access to header information, query arguments, cookies and POST data in a structured manner. More information on the client, server and other environment variables is also available here.

h3. µWeb Standalone Server

*[[Standalone]]* is a module that allows µWeb to function outside the presence of Apache and mod_python. This is easy for local testing, or low volume websites.

h3. Common errors when building uweb projects

[[FAQ|As with any software package, some things tend to go awry for most new users, so we've made a list of them, and their solution.]]

h2. Implementation

h3. Initialize uweb project

The easy way to initialize uweb is to type

<pre>
uweb init [your project name]
</pre>

This creates a folder in your current directory with the project name.
When you don't pick a name uweb uses 'uweb_project' by default.
You probably want pick a nice name because this is what makes your project unique like a little snow flake.

<pre>
uweb init snowflake
</pre>

<pre>
--------------------------------------------
initializing uweb
--------------------------------------------
cloning uweb source
setting up router
setting up apache config
--------------------------------------------
initialization complete - have fun with uweb
--------------------------------------------
</pre>

This generates the snowflake uweb project and generates a folder named 'snowflake' in your current directory. The snowflake project contains multiple folders and files.
In the next chapter we'll activate our project locally.

If you already have a project with the same name, uweb gives you a warning and cancels initialization.

<pre>
Project already excist, use -f (force) to wipe project.
</pre>

If you somehow completely ruined your project and want a clean start add the 'f' (force) flag to remove your project and execute a clean initialization.

<pre>
uweb init snowflake -f
</pre>

The same effect can be recreated by deleting the project and initializing uweb as usual.

h3. Start/stop local webserver

uweb works with router files. A router usually represents a domain. To start a webserver navigate to your router (in the project's router folder) and type 'start'.

<pre>
python /home/user/snowflake/router/snowflake.py start
</pre>

Next you can open up your browser and navigate to:

<pre>
http://localhost:8082/
</pre>

Uweb uses port 8082 locally by default.
This brings you to the default uweb page which contains the text 'Hello µWeb'.
This means you have successfully setup and started your own uweb project.

To stop you local server, replace the 'start' command with 'stop'

<pre>
python /home/user/snowflake/router/snowflake.py stop
</pre>

When you make updates in your router, uweb usually don't update your changes manually.
Type 'restart' to restart your local server with the new configurations.

<pre>
python /home/user/snowflake/router/snowflake.py restart
</pre>

h3. Setting up uweb in apache

To setup uweb in apache, copy the apache.conf (in the root of your project) to your available apache sites.
Uweb its default domain is your project name followed by local.

<pre>
ServerName [project_name].local
</pre>

change this to the desired domain name.

<pre>
ServerName snowflake.com
</pre>

Next add this domain to your hosts and reload apache.
Now your uweb project should work in Apache.

***Warning***
Renaming/moving your project will result in a broken apache config file.
When you rename your project, please also adjust the apache.conf file to the new name / location

h3. Quick router controls

Starting and stopping uweb routers stakes some time.
That's why uweb does have some nifty functionallity which makes navigating to routers obsolete.

<pre>
uweb [sites|start|stop|restart|add|remove] -n [project name]
</pre>

Each project you create is added to je uweb router location file.
This file contains the router locations of all your uweb project.
Calling the sites argument will display all projects and there route locations

<pre>
$ uweb sites
snowflake: /home/codehunger/snowflake/router/snowflake.py
</pre>

In this example you see only one uweb project.
This project is called 'snowflake' and the router location is '/home/codehunger/snowflake/router/snowflake.py'

To start the 'snowflake' router you can simpely call uweb to start the snowflake router.

<pre>
$ uweb start -n snowflake
Starting ...
</pre>

The n option should contain the name of your project.
This could also be used to

restart the router:
<pre>
$ uweb restart -n snowflake
Stopping ...
Starting ...
</pre>

stop the router:
<pre>
$ uweb stop -n snowflake
Stopping ...
</pre>

When you add a uweb website (from a repository for example), uweb need to be updated.
To add a path to the uwebsites use the 'add' argument.

<pre>
$ uweb sites
snowflake: /home/codehunger/snowflake/router/snowflake.py
$ uweb add -n foreign_snowflake -r /home/codehunger/foreign_snowflake/router/snowflake.py
$ uweb sites
foreign_snowflake: /home/codehunger/foreign_snowflake/router/snowflake.py
snowflake: /home/codehunger/snowflake/router/snowflake.py
</pre>

The -n option contains the project name.
The -r is the router location.

In this example a project is added to the uweb sites.
As you can see 'uweb sites' first printed 1 record and after adding a new site it printed 2 records.

When you move your project the router links are not directing to your router anymore.
You can update your router location with the -f (force) flag.

<pre>
$ uweb add -f -n foreign_snowflake -r /home/bob/snowflake/router/snowflake.py
</pre>

This updates the 'foreign_snowflake' record with a new router location.
The previous router location is overwritten by the new location.