webmcp
diff doc/autodoc-header.htmlpart @ 0:9fdfb27f8e67
Version 1.0.0
| author | jbe/bsw |
|---|---|
| date | Sun Oct 25 12:00:00 2009 +0100 (2009-10-25) |
| parents | |
| children | 985024b16520 |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/doc/autodoc-header.htmlpart Sun Oct 25 12:00:00 2009 +0100 1.3 @@ -0,0 +1,306 @@ 1.4 +<html> 1.5 + <head> 1.6 + <style> 1.7 + body { 1.8 + font-family: "Liberation Sans", sans-serif; 1.9 + font-size: 11pt; 1.10 + padding-bottom: 5ex; 1.11 + } 1.12 + .warning { 1.13 + color: #ff0000; 1.14 + } 1.15 + h1, h2 { 1.16 + font-family: "Liberation Serif", Georgia, serif; 1.17 + } 1.18 + h2 { 1.19 + margin-bottom: 0.3ex; 1.20 + } 1.21 + p { 1.22 + margin: 0px; 1.23 + line-height: 130%; 1.24 + } 1.25 + tt, pre { 1.26 + font-size: 10pt; 1.27 + } 1.28 + tt { 1.29 + font-weight: bold; 1.30 + white-space: nowrap; 1.31 + } 1.32 + .autodoc_entry { 1.33 + margin-top: 1ex; 1.34 + margin-bottom: 1ex; 1.35 + } 1.36 + .autodoc_comment_tail { 1.37 + font-style: italic; 1.38 + } 1.39 + .autodoc_entry .short_synopsis { 1.40 + cursor: pointer; 1.41 + } 1.42 + .autodoc_details { 1.43 + padding-left: 1em; 1.44 + padding-right: 1em; 1.45 + border: 1px solid #777; 1.46 + } 1.47 + .autodoc_synopsis { 1.48 + font-weight: bold; 1.49 + } 1.50 + .autodoc_synopsis .autodoc_comment_tail { 1.51 + font-weight: normal; 1.52 + color: #008000; 1.53 + } 1.54 + .autodoc_entry .autodoc_comment { 1.55 + color: #400080; 1.56 + } 1.57 + .autodoc_source { 1.58 + color: #505050; 1.59 + } 1.60 + </style> 1.61 + <title>WebMCP 1.0.0 Documentation</title> 1.62 + </head> 1.63 + <body> 1.64 + <h1>WebMCP 1.0.0 Documentation</h1> 1.65 + <p> 1.66 + WebMCP is a completely new web development framework, and has not been extensively tested yet. The API might change at any time, but in future releases there will be a list of all changes, which break downward compatibility. 1.67 + </p> 1.68 + <h2>Requirements</h2> 1.69 + <p> 1.70 + WebMCP has been developed on Linux and FreeBSD. Using it with Mac OS X is completely untested; Microsoft Windows is not supported. Beside the operating system, the only mandatory dependencies for WebMCP are the programming language <a href="http://www.lua.org/">Lua</a> version 5.1, <a href="http://www.postgresql.org/">PostgreSQL</a> version 8.2 or higher, a C compiler, and a Webserver like Lighttpd or Apache. 1.71 + </p> 1.72 + <h2>Installation</h2> 1.73 + <p> 1.74 + After downloading the tar.gz package, unpack it, enter the unpacked directory and type <tt>make</tt>. If you use Mac OS X or if you experience problems during compilation, you need to edit the <tt>Makefile.options</tt> file prior to compilation. The framework itself will be available in the <tt>framework/</tt> directory, while a demo application is available in the <tt>demo-app/</tt> directory. The <tt>framework.precompiled/</tt> and <tt>demo-app.precompiled/</tt> directories will contain a version with all Lua files being byte-code pre-compiled, which can be used instead. You may copy these directories (with <tt>cp -L</tt> to follow links) to any other place you like. Use the files <tt>doc/lighttpd.sample.conf</tt> or <tt>doc/apache.sample.conf</tt> to setup your webserver appropriatly. Don't forget to setup a database, and make the <tt>tmp/</tt> directory of the application writable for the web server process. Good luck and have fun! 1.75 + </p> 1.76 + <h2>Using the atom library</h2> 1.77 + <p> 1.78 + Lua itself has only very few built-in data types. The atom library gives support for extra data types. Currently the following extra data types are provided: 1.79 + </p> 1.80 + <ul> 1.81 + <li>atom.fraction</li> 1.82 + <li>atom.date</li> 1.83 + <li>atom.time</li> 1.84 + <li>atom.timestamp (date and time combined in one data type)</li> 1.85 + </ul> 1.86 + <p> 1.87 + In addition the following pseudo-types are existent, corresponding to Lua's base types: 1.88 + </p> 1.89 + <ul> 1.90 + <li>atom.boolean</li> 1.91 + <li>atom.string</li> 1.92 + <li>atom.integer</li> 1.93 + <li>atom.number</li> 1.94 + </ul> 1.95 + <p> 1.96 + Both atom.integer and atom.number refer to Lua's base type “number”. 1.97 + </p> 1.98 + <p> 1.99 + New values of atom data types are created by either calling <tt>atom.<i>type</i>:load(string_representation)</tt> or by calling <tt>atom.<i>type</i>{...}</tt>, e.g. <tt>atom.date{year=1970, month=1, day=1}</tt>. You can dump any atom value as a string by calling <tt>atom.dump(value)</tt> and later reload it with <tt>atom.<i>type</i>:load(string)</tt>. 1.100 + </p> 1.101 + <h2>Using the Object-Relational Mapper “mondelefant”</h2> 1.102 + <p> 1.103 + The library “mondelefant” shipping with WebMCP can be used to access PostgreSQL databases. It also serves as an Object-Relational Mapper (ORM). Opening a connection to a database is usually done in a config file in the following way: 1.104 + </p> 1.105 + <pre> 1.106 +db = assert( mondelefant.connect{ engine='postgresql', dbname='webmcp_demo' } ) 1.107 +at_exit(function() 1.108 + db:close() 1.109 +end) 1.110 +function mondelefant.class_prototype:get_db_conn() return db end 1.111 + 1.112 +function db:sql_tracer(command) 1.113 + return function(error_info) 1.114 + local error_info = error_info or {} 1.115 + trace.sql{ command = command, error_position = error_info.position } 1.116 + end 1.117 +end</pre> 1.118 + <p> 1.119 + Overwriting the <tt>sql_tracer</tt> method of the database handle is optional, but helpful for debugging. The parameters for <tt>mondelefant.connect</tt> are directly passed to PostgreSQL's client library libpq. See <a href="http://www.postgresql.org/docs/8.4/interactive/libpq-connect.html">PostgreSQL's documentation on PQconnect</a> for information about supported parameters. 1.120 + </p> 1.121 + <p> 1.122 + To define a model to be used within a WebMCP application, create a file named with the name of the model and <tt>.lua</tt> as extension in the <tt>model/</tt> directory of your application. The most basic definition of a model (named “movie” in this example) is: 1.123 + </p> 1.124 + <pre> 1.125 +Movie = mondelefant.new_class() 1.126 +Movie.table = 'movie'</pre> 1.127 + <p> 1.128 + Note: Model classes are always written CamelCase, while the name of the file in <tt>model/</tt> is written lower_case. 1.129 + </p> 1.130 + <p> 1.131 + To select objects from the database, the mondelefant library provides a selector framework: 1.132 + </p> 1.133 + <pre> 1.134 +local s = Movie:new_selector() 1.135 +s:add_where{ 'id = ?', param.get_id() } 1.136 +s:single_object_mode() -- return single object instead of list 1.137 +local movie = s:exec()</pre> 1.138 + <p> 1.139 + A short form of the above query would be: 1.140 + </p> 1.141 + <pre> 1.142 +local movie = Movie:new_selector():add_where{ 'id = ?', param.get_id() }:single_object_mode():exec()</pre> 1.143 + <p> 1.144 + For more examples about how to use the model system, please take a look at the demo application. 1.145 + </p> 1.146 + <h2>The Model-View-Action (MVA) concept</h2> 1.147 + <p> 1.148 + As opposed to other web application frameworks, WebMCP does not use a Model-View-Controller (MVC) concept, but a Model-View-Action (MVA) concept. 1.149 + </p> 1.150 + <h3>Models</h3> 1.151 + <p> 1.152 + The models in MVA are like the models in MVC; they are used to access data stored in a relational database (PostgreSQL) in an object oriented way. They can also be used to provide methods for working with objects representing the database entries. 1.153 + </p> 1.154 + <h3>Views</h3> 1.155 + <p> 1.156 + The views in the MVA concept are different from the views in the MVC concept. As WebMCP has no controllers, the views are responsible for processing the GET/POST parameters from the webbrowser, fetching the data to be displayed, and creating the output by directly writing HTML to slots in a layout or by calling helper functions for the user interface. 1.157 + </p> 1.158 + <h3>Actions</h3> 1.159 + <p> 1.160 + Actions are similar to views, but supposed to change data in the database, hence only callable by HTTP POST requests. They are also responsible for processing the POST parameters from the webbrowser. They can modify the database, but instead of rendering a page to be displayed, they just return a status code. Depending on the status code there will be an internal forward or an HTTP 303 redirect to a view. When calling an action via a POST request, additional POST parameters, which are usually added by hidden form fields, determine the view to be displayed for each status code returned by the action. 1.161 + </p> 1.162 + <h2>Directory structure of a WebMCP application</h2> 1.163 + <ul> 1.164 + <li> 1.165 + Base Directory 1.166 + <ul> 1.167 + <li> 1.168 + <tt>app/</tt> 1.169 + <ul> 1.170 + <li> 1.171 + <tt>main/</tt> 1.172 + <ul> 1.173 + <li> 1.174 + <tt>_filter/</tt> 1.175 + <ul> 1.176 + <li> 1.177 + <tt>10_first_filter.lua</tt> 1.178 + <li> 1.179 + </li> 1.180 + <tt>30_third_filter.lua</tt> 1.181 + </li> 1.182 + <li>…</li> 1.183 + </ul> 1.184 + </li> 1.185 + <li> 1.186 + <tt>_filter_action/</tt> 1.187 + <ul> 1.188 + <li> 1.189 + <tt>20_second_filter.lua</tt> 1.190 + </li> 1.191 + <li>…</li> 1.192 + </ul> 1.193 + </li> 1.194 + <li> 1.195 + <tt>_filter_view/</tt> 1.196 + <ul> 1.197 + <li>…</li> 1.198 + </ul> 1.199 + </li> 1.200 + <li> 1.201 + <tt>_layout/</tt> 1.202 + <ul> 1.203 + <li>…</li> 1.204 + </ul> 1.205 + </li> 1.206 + <li> 1.207 + <tt>index/</tt> 1.208 + <ul> 1.209 + <li> 1.210 + <tt>_action/</tt> 1.211 + <ul> 1.212 + <li> 1.213 + <i>action_name</i><tt>.lua</tt> 1.214 + </li> 1.215 + <li> 1.216 + <i>another_action_name</i><tt>.lua</tt> 1.217 + </li> 1.218 + <li>…</li> 1.219 + </ul> 1.220 + </li> 1.221 + <li> 1.222 + <tt>index.lua</tt> 1.223 + </li> 1.224 + <li> 1.225 + <i>other_view_name</i><tt>.lua</tt> 1.226 + </li> 1.227 + <li>…</li> 1.228 + </ul> 1.229 + </li> 1.230 + <li> 1.231 + <i>other_module_name</i><tt>/</tt> 1.232 + <ul> 1.233 + <li>…</li> 1.234 + </ul> 1.235 + </li> 1.236 + </ul> 1.237 + </li> 1.238 + <li> 1.239 + <i>other_application_name</i><tt>/</tt> 1.240 + <ul> 1.241 + <li>…</li> 1.242 + </ul> 1.243 + </li> 1.244 + </ul> 1.245 + </li> 1.246 + <li> 1.247 + <tt>config/</tt> 1.248 + <ul> 1.249 + <li> 1.250 + <tt>development.lua</tt> 1.251 + </li> 1.252 + <li> 1.253 + <tt>production.lua</tt> 1.254 + <li> 1.255 + <li> 1.256 + <i>other_config_name</i><tt>.lua</tt> 1.257 + </li> 1.258 + <li>…</li> 1.259 + </ul> 1.260 + </li> 1.261 + <li> 1.262 + <tt>db/</tt> 1.263 + <ul> 1.264 + <li> 1.265 + <tt>schema.sql</tt> 1.266 + </li> 1.267 + </ul> 1.268 + </li> 1.269 + <li> 1.270 + <tt>locale/</tt> 1.271 + <ul> 1.272 + <li> 1.273 + <tt>translations.de.lua</tt> 1.274 + </li> 1.275 + <li> 1.276 + <tt>translations.en.lua</tt> 1.277 + </li> 1.278 + <li> 1.279 + <tt>translations.</tt><i>languagecode</i><tt>.lua</tt> 1.280 + </li> 1.281 + <li>…</li> 1.282 + </ul> 1.283 + </li> 1.284 + <li> 1.285 + <tt>model/</tt> 1.286 + <ul> 1.287 + <li> 1.288 + <i>model_name</i><tt>.lua</tt> 1.289 + </li> 1.290 + <li> 1.291 + <i>another_model_name</i><tt>.lua</tt> 1.292 + </li> 1.293 + <li>…</li> 1.294 + </ul> 1.295 + </li> 1.296 + <li> 1.297 + <tt>static/</tt> 1.298 + <ul> 1.299 + <li>… (images, javascript, ...)</li> 1.300 + </ul> 1.301 + </li> 1.302 + <li> 1.303 + <tt>tmp/</tt> (writable by the web process) 1.304 + </li> 1.305 + </ul> 1.306 + </li> 1.307 + </ul> 1.308 + <h2>Automatically generated reference for the WebMCP environment</h2> 1.309 + <ul>