webmcp

view doc/autodoc-header.htmlpart @ 389:a7a335e2db93

Utilize onhashchange event in autodoc output
author jbe
date Thu Dec 03 02:32:20 2015 +0100 (2015-12-03)
parents 29eeba26ff9f
children ed910089a0c5
line source
1 <html>
2 <head>
3 <script type="text/javascript">
4 var openedSection = null;
5 var setSectionDisplay = function(disp) {
6 var element = document.getElementById('autodoc_details_' + openedSection);
7 if (element) element.style.display = disp;
8 };
9 var showSection = function() {
10 openedSection = window.location.hash;
11 if (openedSection) {
12 openedSection = openedSection.replace(/^#/, '').replace(/_/g, '_USC_').replace(/\./g, '_DOT_').replace(/:/g, '_COL_');
13 setSectionDisplay('');
14 }
15 };
16 window.onload = showSection;
17 window.onhashchange = function() {
18 setSectionDisplay('none');
19 showSection();
20 };
21 </script>
22 <style>
23 body {
24 font-family: "Liberation Sans", sans-serif;
25 font-size: 11pt;
26 padding-bottom: 5ex;
27 }
28 .warning {
29 color: #ff0000;
30 }
31 h1, h2 {
32 font-family: "Liberation Serif", Georgia, serif;
33 }
34 h2 {
35 margin-bottom: 0.3ex;
36 }
37 p {
38 margin: 0px;
39 line-height: 130%;
40 }
41 tt, pre {
42 font-size: 10pt;
43 }
44 tt {
45 font-weight: bold;
46 white-space: nowrap;
47 }
48 .autodoc_entry {
49 margin-top: 1ex;
50 margin-bottom: 1ex;
51 }
52 .autodoc_comment_tail {
53 font-style: italic;
54 }
55 .autodoc_entry .short_synopsis {
56 cursor: pointer;
57 }
58 .autodoc_details {
59 padding-left: 1em;
60 padding-right: 1em;
61 border: 1px solid #777;
62 }
63 .autodoc_synopsis {
64 font-weight: bold;
65 }
66 .autodoc_synopsis .autodoc_comment_tail {
67 font-weight: normal;
68 color: #008000;
69 }
70 .autodoc_entry .autodoc_comment {
71 color: #400080;
72 }
73 .autodoc_source {
74 color: #505050;
75 }
76 </style>
77 <title>WebMCP 2.0.4 Documentation</title>
78 </head>
79 <body>
80 <h1>WebMCP 2.0.4 Documentation</h1>
81 <p>
82 WebMCP is a web development framework based on the Lua programming language (read more about Lua <a href="http://www.lua.org/about.html">here</a>).
83 </p>
84 <h2>Requirements</h2>
85 <p>
86 WebMCP has been developed on Linux and FreeBSD. Using it with Mac&nbsp;OS&nbsp;X is untested as of yet; Microsoft Windows is not supported. Beside the operating system, the only mandatory dependencies for WebMCP are the <a href="http://www.lua.org/">programming language Lua</a> version 5.2 or 5.3, the <a href="http://www.public-software-group.org/moonbridge">Moonbridge Network Server for Lua Applications</a> version 1.0.1 or higher, <a href="http://www.postgresql.org/">PostgreSQL</a> version 8.2 or higher, and a C compiler.
87 </p>
88 <h2>Installation</h2>
89 <p>
90 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. 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!
91 </p>
92 <h2>Configuration, pre-fork and post-fork initializers</h2>
93 <p>
94 The Moonbridge Network Server creates forks (i.e. clones) of the application server process in order to handle concurrent requests. Certain initializations may be performed before forking, other initializations must be performed after forking. The application's configuration files as well as its pre-fork initializers are executed before forking. The application's post-fork initializers are executed after forking. In particular, any libraries that open file or network handles during initialization must not be loaded before the server process is forked. Opening database connections must be performed after forking as well. Execution order is as follows:
95 </p>
96 <ol>
97 <li>
98 Loading all WebMCP libraries except the "multirand" library (multirand opens /dev/urandom and thus must not be loaded prior to forking)
99 </li>
100 <li>
101 Executing the selected configuration file: <tt>config/</tt><i>configuration_name</i><tt>.lua</tt>
102 </li>
103 <li>
104 Executing all pre-fork initializers (both those in the <tt>app/_prefork/</tt> and those in the <tt>app/</tt><i>application_name</i><tt>/_prefork/</tt> directory) until call of <tt>execute.inner()</tt> within each initializer
105 </li>
106 <li>
107 The Moonbridge Network Server forks the process (i.e. cloning the whole Lua machine)<br />
108 <span style="color: red">Note: no file handles or network connections must be opened prior to this point!</span>
109 </li>
110 <li>
111 Loading WebMCP's "multirand" library
112 </li>
113 <li>
114 Executing all post-fork initializers (both those in the <tt>app/_postfork/</tt> and those in the <tt>app/</tt><i>application_name</i><tt>/_postfork/</tt> directory) until call of <tt>execute.inner()</tt> within each initializer
115 </li>
116 <li>
117 For each request:
118 <ul>
119 <li>
120 Execution of all applicable filters until call of <tt>execute.inner()</tt> within each filter
121 </li>
122 <li>
123 Handling of the request by calling the appropriate view or action
124 </li>
125 <li>
126 Resuming execution of all filters in reverse order from that position where <tt>execute.inner()</tt> had been called
127 </li>
128 </ul>
129 </li>
130 <li>
131 Resuming execution of all post-fork initializers in reverse order from that position where <tt>execute.inner()</tt> had been called
132 </li>
133 <li>
134 Resuming execution of all pre-fork initializers in reverse order from that position where <tt>execute.inner()</tt> had been called
135 </li>
136 </ol>
137 </p>
138 <h2>Using the atom library</h2>
139 <p>
140 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:
141 </p>
142 <ul>
143 <li>atom.fraction</li>
144 <li>atom.date</li>
145 <li>atom.time</li>
146 <li>atom.timestamp (date and time combined in one data type)</li>
147 </ul>
148 <p>
149 In addition the following pseudo-types are existent, corresponding to Lua's base types:
150 </p>
151 <ul>
152 <li>atom.boolean</li>
153 <li>atom.string</li>
154 <li>atom.integer</li>
155 <li>atom.number</li>
156 </ul>
157 <p>
158 Both atom.integer and atom.number refer to Lua's base type &ldquo;number&rdquo;.
159 </p>
160 <p>
161 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>.
162 </p>
163 <h2>Using the Object-Relational Mapper &ldquo;mondelefant&rdquo;</h2>
164 <p>
165 The library &ldquo;mondelefant&rdquo; shipping with WebMCP can be used to access PostgreSQL databases. It also serves as an Object-Relational Mapper (ORM). The database connection is usually configured in the config file (e.g. in <tt>config/devel.lua</tt>):
166 </p>
167 <pre>
168 config.db = { engine="postgresql", dbname="webmcp_demo" }
169 config.db_trace = true</pre>
170 <p>
171 In addition to configuring the database, it must be opened within a post-fork initializer (e.g. in <tt>app/_postfork/01_database.lua</tt>):
172 </p>
173 <pre>
174 _G.db = assert(mondelefant.connect(config.db))
175 function mondelefant.class_prototype:get_db_conn() return db end</pre>
176 <p>
177 The parameters for <tt>mondelefant.connect</tt> are directly passed to PostgreSQL's client library libpq. See <a href="http://www.postgresql.org/docs/9.4/static/libpq-connect.html">PostgreSQL's documentation on PQconnect</a> for information about supported parameters.
178 </p>
179 <p>
180 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 &ldquo;movie&rdquo; in this example) is:
181 </p>
182 <pre>
183 Movie = mondelefant.new_class()
184 Movie.table = 'movie'</pre>
185 <p>
186 Note: Model classes are always written CamelCase, while the name of the file in <tt>model/</tt> is written lower_case.
187 </p>
188 <p>
189 To select objects from the database, the mondelefant library provides a selector framework:
190 </p>
191 <pre>
192 local s = Movie:new_selector()
193 s:add_where{ 'id = ?', param.get_id() }
194 s:single_object_mode() -- return single object instead of list
195 local movie = s:exec()</pre>
196 <p>
197 A short form of the above query would be:
198 </p>
199 <pre>
200 local movie = Movie:new_selector():add_where{ 'id = ?', param.get_id() }:single_object_mode():exec()</pre>
201 <p>
202 For more examples about how to use the model system, please take a look at the demo application.
203 </p>
204 <h2>The Model-View-Action (MVA) concept</h2>
205 <p>
206 As opposed to other web application frameworks, WebMCP does not use a Model-View-Controller (MVC) concept, but a Model-View-Action (MVA) concept.
207 </p>
208 <h3>Models</h3>
209 <p>
210 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.
211 </p>
212 <h3>Views</h3>
213 <p>
214 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.
215 </p>
216 <h3>Actions</h3>
217 <p>
218 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.
219 </p>
220 <h2>Directory structure of a WebMCP application</h2>
221 <ul>
222 <li>
223 Base Directory
224 <ul>
225 <li>
226 <tt>app/</tt>
227 <ul>
228 <li>
229 <tt>_prefork/</tt>
230 <ul>
231 <li>
232 <tt>10_first_prefork_initializer.lua</tt>
233 </li>
234 <li>
235 <tt>30_third_prefork_initializer.lua</tt>
236 </li>
237 </ul>
238 </li>
239 <li>
240 <tt>_postfork/</tt>
241 <ul>
242 <li>
243 <tt>01_first_postfork_initializer.lua</tt>
244 </li>
245 <li>
246 <tt>03_third_postfork_initializer.lua</tt>
247 </li>
248 </ul>
249 </li>
250 <li>
251 <tt>main/</tt>
252 <ul>
253 <li>
254 <tt>_prefork/</tt>
255 <ul>
256 <li>
257 <tt>20_second_prefork_initializer.lua</tt>
258 </li>
259 </ul>
260 </li>
261 <li>
262 <tt>_postfork/</tt>
263 <ul>
264 <li>
265 <tt>02_second_postfork_initializer.lua</tt>
266 </li>
267 </ul>
268 </li>
269 <li>
270 <tt>_filter/</tt>
271 <ul>
272 <li>
273 <tt>10_first_filter.lua</tt>
274 </li>
275 <li>
276 <tt>30_third_filter.lua</tt>
277 </li>
278 <li>&hellip;</li>
279 </ul>
280 </li>
281 <li>
282 <tt>_filter_action/</tt>
283 <ul>
284 <li>
285 <tt>20_second_filter.lua</tt>
286 </li>
287 <li>&hellip;</li>
288 </ul>
289 </li>
290 <li>
291 <tt>_filter_view/</tt>
292 <ul>
293 <li>&hellip;</li>
294 </ul>
295 </li>
296 <li>
297 <tt>_layout/</tt>
298 <ul>
299 <li>&hellip;</li>
300 </ul>
301 </li>
302 <li>
303 <tt>index/</tt>
304 <ul>
305 <li>
306 <tt>_action/</tt>
307 <ul>
308 <li>
309 <i>action_name</i><tt>.lua</tt>
310 </li>
311 <li>
312 <i>another_action_name</i><tt>.lua</tt>
313 </li>
314 <li>&hellip;</li>
315 </ul>
316 </li>
317 <li>
318 <tt>index.lua</tt>
319 </li>
320 <li>
321 <i>other_view_name</i><tt>.lua</tt>
322 </li>
323 <li>&hellip;</li>
324 </ul>
325 </li>
326 <li>
327 <i>other_module_name</i><tt>/</tt>
328 <ul>
329 <li>&hellip;</li>
330 </ul>
331 </li>
332 </ul>
333 </li>
334 <li>
335 <i>other_application_name</i><tt>/</tt>
336 <ul>
337 <li>&hellip;</li>
338 </ul>
339 </li>
340 </ul>
341 </li>
342 <li>
343 <tt>config/</tt>
344 <ul>
345 <li>
346 <tt>development.lua</tt>
347 </li>
348 <li>
349 <tt>production.lua</tt>
350 <li>
351 <li>
352 <i>other_config_name</i><tt>.lua</tt>
353 </li>
354 <li>&hellip;</li>
355 </ul>
356 </li>
357 <li>
358 <tt>db/</tt>
359 <ul>
360 <li>
361 <tt>schema.sql</tt>
362 </li>
363 </ul>
364 </li>
365 <li>
366 <tt>locale/</tt>
367 <ul>
368 <li>
369 <tt>translations.de.lua</tt>
370 </li>
371 <li>
372 <tt>translations.en.lua</tt>
373 </li>
374 <li>
375 <tt>translations.</tt><i>languagecode</i><tt>.lua</tt>
376 </li>
377 <li>&hellip;</li>
378 </ul>
379 </li>
380 <li>
381 <tt>model/</tt>
382 <ul>
383 <li>
384 <i>model_name</i><tt>.lua</tt>
385 </li>
386 <li>
387 <i>another_model_name</i><tt>.lua</tt>
388 </li>
389 <li>&hellip;</li>
390 </ul>
391 </li>
392 <li>
393 <tt>static/</tt>
394 <ul>
395 <li>&hellip; (images, javascript, ...)</li>
396 </ul>
397 </li>
398 <li>
399 <tt>tmp/</tt> (writable by the web process)
400 </li>
401 </ul>
402 </li>
403 </ul>
404 <h2>Starting your application</h2>
405 <p>
406 Ensure that the <tt>moonbridge</tt> binary is within your system's search path and that the <tt>moonbridge_http.lua</tt> file is included in the LUA_PATH or linked into the framework's <tt>lib/</tt> directory (alternatively the MOONBR_LUA_PATH option might be set accordingly at compile-time of the Moonbridge Network Server). To start an application, call the <tt>mcp.lua</tt> executable (found in <tt>framework/bin/mcp.lua</tt>) with the following arguments:
407 </p>
408 <ol>
409 <li>
410 Path of the WebMCP framework directory, e.g. <tt>./framework</tt>
411 </li>
412 <li>
413 Path of your application's directory, e.g. <tt>./demo-app</tt>
414 </li>
415 <li>
416 Name of your applicaiton (usually <tt>main</tt>)
417 </li>
418 <li>
419 Name of configuration (e.g. <tt>devel</tt> to use config/devel.lua)
420 </li>
421 </ol>
422 <h2>Automatically generated reference for the WebMCP environment</h2>
423 <ul>

Impressum / About Us