Project

General

Profile

Wiki » History » Version 14

Jacko Hoogeveen, 2012-07-11 17:09

1 1 Elmer de Looff
h1. µWeb
2 8 Jan Klopper
3 8 Jan Klopper
!>uweb_inernals.png!
4 1 Elmer de Looff
5 1 Elmer de Looff
µ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.
6 1 Elmer de Looff
7 1 Elmer de Looff
µWeb provides an MVC like environment, built around three core philosophies:
8 11 Jan Klopper
# as little "boilerplate":http://en.wikipedia.org/wiki/Boilerplate_code as possible;
9 1 Elmer de Looff
# as little Magic™ as possible;
10 1 Elmer de Looff
# and separation by convention, not brute force.
11 3 Elmer de Looff
12 1 Elmer de Looff
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.
13 1 Elmer de Looff
14 12 Elmer de Looff
h2. Installation
15 12 Elmer de Looff
16 12 Elmer de Looff
Details on how to install µWeb can be found on the [[installation]] page.
17 12 Elmer de Looff
18 1 Elmer de Looff
h2. Components
19 1 Elmer de Looff
20 1 Elmer de Looff
µ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.
21 1 Elmer de Looff
22 1 Elmer de Looff
h3. Request Router
23 1 Elmer de Looff
24 5 Elmer de Looff
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.
25 1 Elmer de Looff
26 1 Elmer de Looff
27 1 Elmer de Looff
h3. PageMaker and Response (_Controller_)
28 1 Elmer de Looff
29 5 Elmer de Looff
*[[PageMaker]]* provides the controller part of the 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.
30 1 Elmer de Looff
31 1 Elmer de Looff
h3. TemplateParser (_View_)
32 1 Elmer de Looff
33 5 Elmer de Looff
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.
34 1 Elmer de Looff
35 1 Elmer de Looff
h3. Database abstraction (_Model_)
36 1 Elmer de Looff
37 5 Elmer de Looff
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:
38 1 Elmer de Looff
* to load database record by their primary key value;
39 1 Elmer de Looff
* automatic retrieval of 1-1 or n-1 relations;
40 1 Elmer de Looff
* creating, updating or deleting of records.
41 1 Elmer de Looff
42 1 Elmer de Looff
h3. HTTP Request abstraction
43 1 Elmer de Looff
44 5 Elmer de Looff
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.
45 1 Elmer de Looff
46 1 Elmer de Looff
h3. µWeb Standalone Server
47 1 Elmer de Looff
48 5 Elmer de Looff
*[[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.
49 9 Jan Klopper
50 9 Jan Klopper
h3. Common errors when building uweb projects
51 9 Jan Klopper
52 9 Jan Klopper
[[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.]]
53 13 Jacko Hoogeveen
54 13 Jacko Hoogeveen
h2. Implementation
55 13 Jacko Hoogeveen
56 13 Jacko Hoogeveen
h3. Initialize uweb project
57 13 Jacko Hoogeveen
58 13 Jacko Hoogeveen
The easy way to initialize uweb is to type
59 13 Jacko Hoogeveen
60 13 Jacko Hoogeveen
<pre>
61 13 Jacko Hoogeveen
uweb init [your project name]
62 13 Jacko Hoogeveen
</pre>
63 13 Jacko Hoogeveen
64 13 Jacko Hoogeveen
This creates a folder in your current directory with the project name. 
65 13 Jacko Hoogeveen
When you don't pick a name uweb uses 'uweb_project' by default. 
66 13 Jacko Hoogeveen
You probably want pick a nice name because this is what makes your project unique like a little snow flake.
67 13 Jacko Hoogeveen
68 13 Jacko Hoogeveen
<pre>
69 13 Jacko Hoogeveen
uweb init snowflake
70 13 Jacko Hoogeveen
</pre>
71 13 Jacko Hoogeveen
72 13 Jacko Hoogeveen
This generates the snowflake uweb project and generates a folder named 'snowflake' in your current directory. The snowflake project contains multiple folders and files. 
73 13 Jacko Hoogeveen
In the next chapter we'll activate our project locally.
74 13 Jacko Hoogeveen
75 13 Jacko Hoogeveen
If you already have a project with the same name, uweb gives you a warning and cancels initialization.
76 13 Jacko Hoogeveen
77 13 Jacko Hoogeveen
<pre>
78 13 Jacko Hoogeveen
Project already excist, use -f (force) to wipe project.
79 13 Jacko Hoogeveen
</pre>
80 13 Jacko Hoogeveen
81 13 Jacko Hoogeveen
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.
82 13 Jacko Hoogeveen
83 13 Jacko Hoogeveen
<pre>
84 13 Jacko Hoogeveen
uweb init snowflake -f
85 13 Jacko Hoogeveen
</pre>
86 13 Jacko Hoogeveen
87 14 Jacko Hoogeveen
The same effect can be recreated by deleting the project and initializing uweb as usual.
88 14 Jacko Hoogeveen
89 13 Jacko Hoogeveen
h3. Start/stop local webserver
90 13 Jacko Hoogeveen
91 13 Jacko Hoogeveen
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'.
92 13 Jacko Hoogeveen
93 13 Jacko Hoogeveen
<pre>
94 13 Jacko Hoogeveen
python /home/user/snowflake/router/snowflake.py start
95 13 Jacko Hoogeveen
</pre>
96 13 Jacko Hoogeveen
97 13 Jacko Hoogeveen
Next you can open up your browser and navigate to:
98 13 Jacko Hoogeveen
99 13 Jacko Hoogeveen
<pre>
100 13 Jacko Hoogeveen
http://localhost:8082/
101 13 Jacko Hoogeveen
</pre>
102 13 Jacko Hoogeveen
103 13 Jacko Hoogeveen
Uweb uses port 8082 locally by default. 
104 13 Jacko Hoogeveen
This brings you to the default uweb page which contains the text 'Hello µWeb'. 
105 13 Jacko Hoogeveen
This means you have successfully setup and started your own uweb project.
106 13 Jacko Hoogeveen
107 13 Jacko Hoogeveen
To stop you local server, replace the 'start' command with 'stop'
108 13 Jacko Hoogeveen
109 13 Jacko Hoogeveen
<pre>
110 13 Jacko Hoogeveen
python /home/user/snowflake/router/snowflake.py stop
111 13 Jacko Hoogeveen
</pre>
112 13 Jacko Hoogeveen
113 13 Jacko Hoogeveen
When you make updates in your router, uweb usually don't update your changes manually. 
114 13 Jacko Hoogeveen
Type 'restart' to restart your local server with the new configurations.
115 13 Jacko Hoogeveen
116 13 Jacko Hoogeveen
<pre>
117 13 Jacko Hoogeveen
python /home/user/snowflake/router/snowflake.py restart
118 13 Jacko Hoogeveen
</pre>
119 13 Jacko Hoogeveen
120 13 Jacko Hoogeveen
121 13 Jacko Hoogeveen
h3. Setting up uweb in apache
122 13 Jacko Hoogeveen
123 13 Jacko Hoogeveen
To setup uweb in apache, copy the apache.conf (in the root of your project) to your available apache sites. 
124 13 Jacko Hoogeveen
Uweb its default domain is your project name followed by local.
125 13 Jacko Hoogeveen
126 13 Jacko Hoogeveen
<pre>
127 13 Jacko Hoogeveen
ServerName  [project_name].local
128 13 Jacko Hoogeveen
</pre>
129 13 Jacko Hoogeveen
130 13 Jacko Hoogeveen
change this to the desired domain name.
131 13 Jacko Hoogeveen
132 13 Jacko Hoogeveen
<pre>
133 13 Jacko Hoogeveen
ServerName  snowflake.com
134 13 Jacko Hoogeveen
</pre>
135 13 Jacko Hoogeveen
136 13 Jacko Hoogeveen
Next add this domain to your hosts and reload apache.
137 13 Jacko Hoogeveen
Now your uweb project should work in Apache.
138 13 Jacko Hoogeveen
139 13 Jacko Hoogeveen
***Warning***
140 13 Jacko Hoogeveen
Renaming/moving your project will result in a broken apache config file.
141 13 Jacko Hoogeveen
When you rename your project, please also adjust the apache.conf file to the new name / location