view doc/autodoc-header.htmlpart @ 533:b316f1c894ae

Lower-case HTML tag in documentation
author jbe
date Mon Apr 01 19:16:39 2019 +0200 (20 months ago)
parents c8e77723f9cf
children 7ad7023c91df
line source
1 <html>
2 <head>
3 <script type="text/javascript">
4 var expandedSections = {};
5 function toggleSection(ident) {
6 var element = document.getElementById('autodoc_details_' + ident);
7 if (element) {
8 if (expandedSections[ident]) {
9 element.style.display = 'none';
10 delete expandedSections[ident];
11 } else {
12 element.style.display = '';
13 expandedSections[ident] = true;
14 }
15 }
16 }
17 var inProgress = false;
18 window.onload = window.onhashchange = function() {
19 if (inProgress) return;
20 for (var ident in expandedSections) toggleSection(ident);
21 var hash = window.location.hash;
22 if (hash) {
23 toggleSection(hash.replace(/^#/, ''));
24 inProgress = true;
25 window.location.hash = hash; // required after collapsing/expanding
26 inProgress = false;
27 }
28 };
29 </script>
30 <style>
31 body {
32 font-family: "Liberation Sans", sans-serif;
33 font-size: 11pt;
34 padding-bottom: 5ex;
35 }
36 .warning {
37 color: #ff0000;
38 }
39 h1, h2 {
40 font-family: "Liberation Serif", Georgia, serif;
41 }
42 h2 {
43 margin-bottom: 0.3ex;
44 }
45 p {
46 margin-bottom: 1ex;
47 line-height: 130%;
48 }
49 tt, pre {
50 font-size: 10pt;
51 }
52 tt {
53 font-weight: bold;
54 white-space: nowrap;
55 }
56 .autodoc_entry {
57 margin-top: 1ex;
58 margin-bottom: 1ex;
59 }
60 .autodoc_comment_tail {
61 font-style: italic;
62 }
63 .autodoc_entry .short_synopsis {
64 cursor: pointer;
65 }
66 .AUTODOC_details {
67 padding-left: 1em;
68 padding-right: 1em;
69 border: 1px solid #777;
70 }
71 .autodoc_synopsis {
72 font-weight: bold;
73 }
74 .autodoc_synopsis .autodoc_comment_tail {
75 font-weight: normal;
76 color: #008000;
77 }
78 .autodoc_entry .autodoc_comment {
79 color: #400080;
80 }
81 .autodoc_source {
82 color: #505050;
83 }
84 </style>
85 <title>WebMCP 2.1.0 Documentation</title>
86 </head>
87 <body>
88 <h1>WebMCP 2.1.0 Documentation</h1>
89 <p>
90 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>).
91 </p>
92 <h2>Requirements</h2>
93 <p>
94 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.
95 </p>
96 <h2>Installation</h2>
97 <p>
98 Please read the following instructions carefully to avoid problems during installation.
99 </p>
100 <ol>
101 <li>Download and compile the <a href="http://www.public-software-group.org/moonbridge">Moonbridge Network Server for Lua Applications</a> (follow the README file of Moonbridge).</li>
102 <li>Optional: Ensure that the <tt>moonbridge</tt> binary is within the search path for binaries.</li>
103 <li>Optional: Ensure that the <tt>moonbridge_http.lua</tt> file is covered by Lua's <a href="https://www.lua.org/manual/5.3/manual.html#pdf-package.path">package path</a> (see Lua's <a href="https://www.lua.org/manual/5.3/manual.html#pdf-package.searchpath">search path documentation</a> on how to format the <tt>LUA_PATH</tt> environment variable).</li>
104 <li>Download <a href="http://www.public-software-group.org/webmcp">WebMCP</a>.</li>
105 <li>Enter WebMCP's unpacked source code directory and execute the command "<tt>make</tt>".</li>
106 <li>If you experience problems during step&nbsp;3, edit the <tt>Makefile.options</tt> file and repeat step&nbsp;3.</li>
107 <li>The <tt>framework/</tt> directory (or the <tt>framework.precompiled</tt> directory if you want to use precompiled code) is WebMCP's framework base directory now. It may be copied to any other directory of your choice (but make sure to follow links, e.g. using <tt>cp -L -R</tt>, when copying the directory to a different place).</li>
108 <li>If optional step&nbsp;3 has been skipped, ensure that Moonbridge's <tt>moonbridge_http.lua</tt> file is soft-linked or copied to the <tt>lib/</tt> directory of the framework's base directory.</li>
109 </li>
110 </ol>
111 <h2>Configuration, initializers, and request handling</h2>
112 <p>
113 A WebMCP application may consist of several (sub-)applications. Each application sharing the same base directory also shares the database models but may provide different views and actions. The views and actions of an application are found within the "<tt>app/</tt><i>application_name</i><tt>/</tt>" directory, relative to the application base path. When starting WebMCP, the application's base path as well as the desired application name must be provided.
114 </p>
115 <p>
116 In addition to selection of an application, a config file must be chosen when starting the application. This enables to run an application in different contexts, e.g. you may have one configuration file for development purposes and one for productive use. Configuration files are found in the "<tt>config/</tt>" directory, relative to the application base path.
117 </p>
118 <p>
119 WebMCP uses the <a href="http://www.public-software-group.org/moonbridge">Moonbridge Network Server</a> to handle HTTP requests. The Moonbridge Network Server listens to a TCP port and passes control to WebMCP (by invoking <tt>bin/mcp.lua</tt> in the framework's base directory), eventually resulting in a call of <a href="#request.handler"><tt>request.handler(...)</tt></a> for each request. However, before any request is processed, WebMCP will initialize the environment. This initialization includes tasks such as
120 </p>
121 <ul>
122 <li>loading libraries,</li>
123 <li>configuring the database connection or the application,</li>
124 <li>connecting to the database,</li>
125 <li>etc.</li>
126 </ul>
127 <p>
128 For each request, it is also possible to execute filters. Filters can be used to
129 </p>
130 <ul>
131 <li>
132 restrict access for certain requests, e.g. by performing redirects or raising errors,
133 </li>
134 <li>
135 perform tasks that are common for different requests, e.g.
136 <ul>
137 <li>execute certain database requests,</li>
138 <li>prepare a menu on the website,</li>
139 <li>&hellip;</li>
140 </ul>
141 </li>
142 </ul>
143 <p>
144 Filters and initializers are created by adding files in the application's directory structure. The filename determines the execution order (lexicographical order). It is a common idiom to start the filename of a filter or initializer with a two digit number to be easily able to change the execution order when desired. Filters and initializers are wrapping requests, i.e. part of them is executed before and part after the remaining request handling.
145 </p>
146 <p>
147 When an initializer or filter calls <a href="#execute.inner"><tt>execute.inner()</tt></a>, execution of the initializer or filter is suspended and the remaining initializers and/or filters or the requested view or action are executed. Afterwards, the interrupted filters and initializers are resumed in reverse order (from where they called <tt>execute.inner()</tt>). Most often, <tt>execute.inner()</tt> is the last line in an initializer or filter, resulting in all code to be executed prior to request handling (and nothing to be executed afterwards).
148 </p>
149 <p>
150 The Moonbridge server creates forks (i.e. clones) of the application server process (i.e. the whole Lua engine including all libraries and variables) in order to handle concurrent requests. Certain initializations may be performed before forking, other initializations must be performed after forking. For this purpose, WebMCP allows an application to provide so-called "pre-fork" and "post-fork" initializers. 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. WebMCP follows the following execution order (directory structure is explained further down):
151 </p>
152 <ol>
153 <li>
154 Initialization code of <tt>mcp.lua</tt> in the <tt>bin/</tt> directory of the framework, including:
155 <ul>
156 <li>Initialization of WebMCP's autoloader in <tt>mcp.lua</tt> (in the <tt>bin/</tt> directory of the framework),</li>
157 <li>Execution of <tt>env/__init.lua</tt> (both relative to the framework and, if existent, relative to the application base directory)</li>
158 <li>Loading of most of WebMCP's libraries (excluding "multirand" library, which must not be loaded prior to forking);</li>
159 </ul>
160 </li>
161 <li>
162 Executing the selected configuration file: <tt>config/</tt><i>configuration_name</i><tt>.lua</tt>;
163 </li>
164 <li>
165 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;
166 </li>
167 <li>
168 The Moonbridge Network Server forks the process (i.e. cloning the whole Lua machine);<br />
169 <span style="color: red">Note: no file handles or network connections must be opened prior to this point!</span>
170 </li>
171 <li>
172 Loading WebMCP's "multirand" library;
173 </li>
174 <li>
175 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;
176 </li>
177 <li>
178 For each request:
179 <ul>
180 <li>
181 Execution of all applicable filters until call of <tt>execute.inner()</tt> within each filter,
182 </li>
183 <li>
184 Handling of the request by calling the appropriate view or action,
185 </li>
186 <li>
187 Resuming execution of all filters in reverse order from that position where <tt>execute.inner()</tt> had been called;
188 </li>
189 </ul>
190 </li>
191 <li>
192 Resuming execution of all post-fork initializers in reverse order from that position where <tt>execute.inner()</tt> had been called;
193 </li>
194 <li>
195 Resuming execution of all pre-fork initializers in reverse order from that position where <tt>execute.inner()</tt> had been called.
196 </li>
197 </ol>
198 </p>
199 <p>
200 As a minimum configuration, the used configuration file or pre-fork initializer should at least contain a <a href="#listen"><tt>listen{...}</tt></a> call, e.g.:
201 </p>
202 <pre>
203 listen{
204 { proto = "tcp", host = "::", port = 8080 },
205 { proto = "tcp", host = "", port = 8080 }
206 }
207 execute.inner() -- only use this line if done in pre-fork initializer</pre>
208 <h2>Using the atom library</h2>
209 <p>
210 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:
211 </p>
212 <ul>
213 <li><a href="#atom.fraction:new">atom.fraction</a></li>
214 <li><a href="#atom.date:new">atom.date</a></li>
215 <li><a href="#atom.time:new">atom.time</a></li>
216 <li><a href="#atom.timestamp:new">atom.timestamp (date and time combined in one data type)</a></li>
217 </ul>
218 <p>
219 In addition the following pseudo-types are existent, corresponding to Lua's base types:
220 </p>
221 <ul>
222 <li>atom.boolean</li>
223 <li>atom.string</li>
224 <li>atom.integer</li>
225 <li>atom.number</li>
226 </ul>
227 <p>
228 Both atom.integer and atom.number refer to Lua's base type &ldquo;number&rdquo;.
229 </p>
230 <p>
231 New values of atom data types are created by either calling <tt>atom.</tt><i>type</i><tt>:load(string_representation)</tt> or by calling <tt>atom.</tt><i>type</i><tt>{...}</tt>, e.g. <tt>atom.date{year=1970, month=1, day=1}</tt>. Note that <tt>atom.date{...}</tt> is a shortcut for <tt><a href="#atom.date:new">atom.date:new</a>{...}</tt>. You can dump any atom value as a string by calling <a href="#atom.dump"><tt>atom.dump(value)</tt></a> and later reload it with <tt>atom.</tt><i>type</i><tt>:load(string)</tt>.
232 </p>
233 <h2>Using the Object-Relational Mapper &ldquo;mondelefant&rdquo;</h2>
234 <p>
235 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>):
236 </p>
237 <pre>
238 config.db = { engine="postgresql", dbname="webmcp_demo" }</pre>
239 <p>
240 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>):
241 </p>
242 <pre>
243 _G.db = assert(<a href="#mondelefant.connect">mondelefant.connect</a>(config.db))
244 function mondelefant.class_prototype:<a href="#db_class:get_db_conn">get_db_conn</a>() return db end
245 execute.inner()</pre>
246 <p>
247 The parameters for <tt>mondelefant.connect</tt> are directly passed to PostgreSQL's client library libpq. See PostgreSQL's documentation for information about <a href="https://www.postgresql.org/docs/9.6/static/libpq-connect.html#LIBPQ-PARAMKEYWORDS">supported parameters</a>.
248 </p>
249 <p>
250 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:
251 </p>
252 <pre>
253 Movie = <a href="#mondelefant.new_class">mondelefant.new_class</a>()
254 Movie.table = 'movie'</pre>
255 <p>
256 Note: Model classes are always written CamelCase, while the name of the file in <tt>model/</tt> is written lower_case.
257 </p>
258 <p>
259 To select objects from the database, the mondelefant library provides a selector framework:
260 </p>
261 <pre>
262 local s = Movie:<a href="#db_class:new_selector">new_selector</a>()
263 s:<a href="#db_selector:add_where">add_where</a>{ 'id = ?', param.get_id() }
264 s:<a href="#db_selector:single_object_mode">single_object_mode</a>() -- return single object instead of list
265 local movie = s:<a href="#db_selector:exec">exec</a>()</pre>
266 <p>
267 A short form of the above query would be:
268 </p>
269 <pre>
270 local movie = Movie:new_selector():add_where{ 'id = ?', param.get_id() }:single_object_mode():exec()</pre>
271 <p>
272 For more examples about how to use the model system, please take a look at the demo application.
273 </p>
274 <h2>The Model-View-Action (MVA) concept</h2>
275 <p>
276 As opposed to other web application frameworks, WebMCP does not use a Model-View-Controller (MVC) concept, but a Model-View-Action (MVA) concept.
277 </p>
278 <h3>Models</h3>
279 <p>
280 The models in MVA are like the models in MVC; they are used to access data, which is stored in a relational database (PostgreSQL), in an object oriented way. Methods provided by the corresponding classes can be used to alter stored objects or execute any other associated program code. Models are usually defined in a file with a lowercase filename ending with "<tt>.lua</tt>" in the <tt>models/</tt> directory of the application. The corresponding model name (i.e. class name) must be written in CamelCase, e.g. "<tt>models/my_model.lua</tt>" should define a model class named "<tt>MyModel</tt>". The simplest model is created by calling <a href="#mondelefant.new_class"><tt>mondelefant.new_class()</tt></a> and subsequently setting the <a href="#db_class.table"><tt>table</tt></a> attribute of the returned class.
281 </p>
282 <pre>
283 -- filename: model/customer_receipt.lua
284 CustomerReceipt = mondelefant.new_class()
285 CustomerReceipt.table = "custreceipt"</pre>
286 <p>
287 Methods such as <a href="#db_class:add_reference"><tt>:add_reference(...)</tt></a> can be used to further modify or extend the class.
288 </p>
289 <h3>Views</h3>
290 <p>
291 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 of a layout (see <a href="#slot.select"><tt>slot.select(...)</tt></a>, <a href="#slot.put"><tt>slot.put(...)</tt></a>, and <a href="#slot.put_into"><tt>slot.put_into(...)</tt></a> or by calling helper functions for the user interface (those functions beginning with "<tt>ui.</tt>"). Views are stored in files with the file path "<tt>app/</tt><i>application_name</i><tt>/</tt><i>module_name</i><tt>/</tt><i>view_name</i><tt>.lua</tt>". When their corresponding URL, e.g. "<tt>http://</tt><i>hostname</i><tt>:</tt><i>port</i><tt>/</tt><i>module_name</i><tt>/</tt><i>view_name</i><tt>.html</tt>", is requested, the code in that file gets executed (after calling appropriate filters). After the execution of the view has finished (and after all filters have finished their execution too), the slot data will be inserted into placeholder sections in the selected layout file. The layout file defaults to "<tt>app/</tt><i>application_name</i><tt>/_layout/default.html</tt>" but may be changed using the <a href="#slot.set_layout"><tt>slot.set_layout(...)</tt></a> function.
292 </p>
293 <h3>Actions</h3>
294 <p>
295 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 string (via Lua's <tt>return</tt> statement, where <tt>true</tt> can also be used instead of "<tt>ok</tt>", and <tt>false</tt> instead of "<tt>error</tt>"). Depending on the status string 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 string returned by the action. See the <tt>routing</tt> parameter to the <a href="#ui.form"><tt>ui.form{...}</tt></a> function for further details.
296 </p>
297 <h2>Layouts</h2>
298 <p>
299 Templates for HTML documents to be returned by views are stored at the path "<tt>app/</tt><i>application_name</i><tt>/_layout/</tt><i>layout_name</i><tt>.html</tt>", relative to the application base path. The default layout name is "<tt>default</tt>". For system errors, the layout name "<tt>system_error</tt>" is used. A sample layout is given as follows:
300 </p>
301 <pre>
302 &lt;!DOCTYPE HTML&gt;
303 &lt;html&gt;
304 &lt;head&gt;
305 &lt;title&gt;&lt!-- WEBMCP SLOTNODIV title --&gt;&lt;/title&gt;
306 &lt;link rel="stylesheet" type="text/css" media="screen" href="__BASEURL__/static/style.css"/&gt;
307 &lt;/head&gt;
308 &lt;body&gt;
309 &lt;!-- WEBMCP SLOT content --&gt;
310 &lt;/body&gt;
311 &lt;/html&gt;</pre>
312 <p>
313 The following elements in a layout file get replaced automatically:
314 </p>
315 <ul>
316 <li><tt>__BASEURL__</tt> gets replaced with the application's base web address.</li>
317 <li><tt>&lt;!-- WEBMCP SLOT </tt><i>slot_name</i><tt> --&gt;</tt> gets, if the slot is not empty, replaced with a <tt>&lt;div&gt;</tt> element (with the <tt>id</tt> attribute set to "<tt>slot_</tt><i>slotname</i>") that contains the slot's content.</li>
318 <li><tt>&lt;!-- WEBMCP SLOTNODIV </tt><i>slot_name</i><tt> --&gt;</tt> gets replaced with the slot's content (without wrapping it in an additional <tt>&lt;div&gt;</tt> element).</li>
319 </ul>
320 <h2>Internationalization/Localization</h2>
321 <p>
322 To translate certain strings in your application, simply use the <a href="#_">underscore function</a>. A language can be selected with <tt><a href="#locale.set">locale.set</a>{lang = "code"}</tt> where <tt>code</tt> is a language code. The translations for strings are expected to be contained in files "<tt>locale/translations.</tt><i>language_code</i><tt>.lua</tt>". These files should return a table that maps strings to their corresponding translation:
323 </p>
324 <pre>
325 return{
326 ["Are you sure?"] = "Bist Du sicher?";
327 ["User '#{name}' created"] = "Benutzer '#{name}' created";
328 }</pre>
329 <p>
330 Such translation files can be automatically created with the <tt>langtool.lua</tt> program, found in the framework's <tt>bin/</tt> directory.
331 </p>
332 <h2>Global variables and the environment</h2>
333 <p>
334 To avoid accidental programming errors, WebMCP forbids setting of global variables by default. This is overridden by using the prefix "<tt>_G.</tt>" (<a href="#_G">see reference</a>) when setting the variable, e.g. <tt>_G.myvar = 7</tt>, or by setting the variable in a file with the same name of the global varaible (but suffixed with "<tt>.lua</tt>") in the <tt>env/</tt> directory of the framework or application. Note, however, that the lifetime of global variables is not predictable as it depends on process recycling of the Moonbridge webserver (one fork will handle more than one request) and because there may be multiple forks of the Lua machine which all have their own global variable space (there is usually more than one fork).
335 </p>
336 <p>
337 If an application needs to store request related data, the global table <a href="#app"><tt>app</tt></a> should be used (e.g. <tt>app.myvar = true</tt> instead of <tt>_G.myvar = true</tt>). The <tt>app</tt> table gets automatically initialized (i.e. emptied) for each request.
338 </p>
339 <p>
340 Global variables are still useful when providing access to libraries, for example. WebMCP automatically loads certain libraries and functions though an autoloader mechanism. On read-accessing any unknown variable, WebMCP will search the framework's and application's <tt>env/</tt> directories for an appropriate file (e.g. "<tt>my_func.lua</tt> if you invoke "<tt>my_func()</tt>") or a matching directory (e.g. "<tt>my_module/</tt> if you access "<tt>my_module.my_func()</tt>). In case of an existing directory in <tt>env/</tt>, an empty table with autoloading capabilities is automatically created as global variable with the name of the directory. The autoloading mechanism allows directories to contain further files which can be used to initialize variables within that table when accessed. Directories can also contain a special file called "<tt>__init.lua</tt>" that always gets executed when the table is accessed for the first time. The <tt>env/</tt> root directory can also contain a file ("<tt>env/__init__.lua</tt>") which gets executed before any configuration is loaded.
341 </p>
342 <p>
343 A good place to store utility functions is a global table called <tt>util</tt>. This table will be automatically accessible if you create a <tt>env/util/</tt> directory in your WebMCP application. To provide a function <tt>util.myfunc(...)</tt> simply create a file <tt>env/util/myfunc.lua</tt>, with the following function definition:
344 </p>
345 <pre>
346 -- filename: env/util/myfunc.lua
347 function util.myfunc()
348 slot.put_into("hello", "Hello World!")
349 end</pre>
350 <h2>Directory structure of a WebMCP application</h2>
351 <p>
352 Summarizing information from the previous section, we get the following directory structure for a WebMCP application:
353 </p>
354 <ul>
355 <li>
356 Base Directory
357 <ul>
358 <li>
359 <tt>app/</tt>
360 <ul>
361 <li><tt>_prefork/</tt></li>
362 <li><tt>_postfork/</tt></li>
363 <li>
364 <tt>main/</tt> (typically "main" is the only application)
365 <ul>
366 <li><tt>_prefork/</tt></li>
367 <li><tt>_postfork/</tt></li>
368 <li><tt>_filter/</tt></li>
369 <li><tt>_filter_action/</tt></li>
370 <li><tt>_filter_view/</tt></li>
371 <li><tt>_layout/</tt></li>
372 <li>
373 <tt>index/</tt> (module "index" is the default module)
374 <ul>
375 <li>
376 <tt>_action/</tt>
377 <ul>
378 <li><i>action_name</i><tt>.lua</tt></li>
379 <li><i>another_action_name</i><tt>.lua</tt></li>
380 <li>&hellip;</li>
381 </ul>
382 </li>
383 <li><tt>index.lua</tt> (view "index" of module "index" is the default view)</li>
384 <li><i>other_view_name</i><tt>.lua</tt></li>
385 <li>&hellip;</li>
386 </ul>
387 </li>
388 <li>
389 <i>other_module_name</i><tt>/</tt>
390 <ul><li>&hellip;</li></ul>
391 </li>
392 </ul>
393 </li>
394 <li>
395 <i>other_application_name</i><tt>/</tt>
396 <ul>
397 <li>&hellip;</li>
398 </ul>
399 </li>
400 </ul>
401 </li>
402 <li>
403 <tt>config/</tt>
404 <ul>
405 <li><tt>development.lua</tt> (e.g. to be used for development purposes)</li>
406 <li><tt>production.lua</tt> (e.g. to be used for production)</li>
407 <li><i>other_config_name</i><tt>.lua</tt></li>
408 <li>&hellip;</li>
409 </ul>
410 </li>
411 <li>
412 <tt>db/</tt>
413 <ul>
414 <li><tt>schema.sql</tt> (not used by WebMCP, but may be used to initialize a database)</li>
415 </ul>
416 </li>
417 <li>
418 <tt>env/</tt>
419 <ul>
420 <li><tt>__init.lua</tt></li>
421 <li><i>some_global_variable_name</i><tt>.lua</tt></li>
422 <li>
423 <i>another_global_variable_name</i><tt>/</tt>
424 <ul>
425 <li><tt>__init.lua</tt></li>
426 <li><i>attribute_name</i><tt>.lua</tt></li>
427 <li>
428 <i>another_attibute_name</i><tt>/</tt>
429 <ul><li>&hellip;</li></ul>
430 </li>
431 </ul>
432 </li>
433 </ul>
434 <li>
435 <tt>locale/</tt> (translation files used by the <a href="#_">underscore function</a>")
436 <ul>
437 <li>
438 <tt>translations.de.lua</tt>
439 </li>
440 <li>
441 <tt>translations.en.lua</tt>
442 </li>
443 <li>
444 <tt>translations.</tt><i>languagecode</i><tt>.lua</tt>
445 </li>
446 <li>&hellip;</li>
447 </ul>
448 </li>
449 <li>
450 <tt>model/</tt>
451 <ul>
452 <li>
453 <i>model_name</i><tt>.lua</tt> (code must create a model class in camel case, e.g. "<tt>ModelName</tt>" if the file name is "<tt>model_name.lua</tt>")
454 </li>
455 <li>
456 <i>another_model_name</i><tt>.lua</tt>
457 </li>
458 <li>&hellip;</li>
459 </ul>
460 </li>
461 <li>
462 <tt>static/</tt>
463 <ul>
464 <li>&hellip; (images, javascript, ...)</li>
465 </ul>
466 </li>
467 <li>
468 <tt>tmp/</tt> (needs to be writable by the user executing WebMCP)
469 </li>
470 </ul>
471 </li>
472 </ul>
473 <h2>Starting your application</h2>
474 <p>
475 If the <tt>moonbridge</tt> executable is within your system's search path for binaries (i.e. if optional step&nbsp;2 of the installation instructions has been carried out), you can directly call the <tt>mcp.lua</tt> script (found in <tt>framework/bin/mcp.lua</tt>). Pass the following arguments to <tt>mcp.lua</tt>:
476 </p>
477 <ol>
478 <li>Path of the WebMCP framework directory, e.g. <tt>./framework</tt></li>
479 <li>Path of your application's directory, e.g. <tt>./demo-app</tt></li>
480 <li>Name of your application (usually <tt>main</tt>)</li>
481 <li>Name of configuration (e.g. <tt>devel</tt> to use config/devel.lua)</li>
482 </ol>
483 <p>
484 Alternatively, the <tt>moonbridge</tt> binary may be called manually (e.g. by invoking <tt>../moonbridge/moonbridge</tt>). In this case, the following five arguments are required:
485 </p>
486 <ol>
487 <li>Path to <tt>mcp.lua</tt>, e.g. <tt>./framework/bin/mcp.lua</tt></li>
488 <li>Path of the WebMCP framework directory, e.g. <tt>./framework</tt></li>
489 <li>Path of your application's directory, e.g. <tt>./demo-app</tt></li>
490 <li>Name of your application (usually <tt>main</tt>)</li>
491 <li>Name of configuration (e.g. <tt>devel</tt> to use config/devel.lua)</li>
492 </ol>
493 <p>
494 Note that the demo application will require a database to be set up prior to starting. Execute the following shell commands first:
495 </p>
496 <pre>
497 createdb webmcp_demo
498 psql -v ON_ERROR_STOP=1 -f demo-app/db/schema.sql webmcp_demo</pre>
499 <h2>Automatically generated reference for the WebMCP environment</h2>
500 <ul>

Impressum / About Us