webmcp

changeset 513:74463f7af123

Further improvements to WebMCP's documentation including instructions for demo application
author jbe
date Mon Aug 21 05:40:28 2017 +0200 (2017-08-21)
parents 8579adac1cc6
children 297bedede137
files doc/autodoc-header.htmlpart
line diff
     1.1 --- a/doc/autodoc-header.htmlpart	Mon Aug 21 05:40:09 2017 +0200
     1.2 +++ b/doc/autodoc-header.htmlpart	Mon Aug 21 05:40:28 2017 +0200
     1.3 @@ -124,7 +124,7 @@
     1.4        </li>
     1.5      </ul>
     1.6      <p>
     1.7 -      Filters and initializers are created by adding files in the application's directory structure. The filename determins the execution order of otherwise equally ranked initializers and/or filters. 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 executed both before and after a request. Each file must contain a command <a href="#execute.inner"><tt>execute.inner()</tt></a>. The part before that command is executed before the request, and the part after that command is executed after the request.
     1.8 +      Filters and initializers are created by adding files in the application's directory structure. The filename determins the execution order of otherwise equally ranked initializers and/or filters. 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 executed both before and after a request. Each file must contain an <a href="#execute.inner"><tt>execute.inner()</tt></a> command. The part before that command is executed before the request, and the part after that command is executed after the request.
     1.9      </p>
    1.10      <p>
    1.11        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):
    1.12 @@ -252,7 +252,7 @@
    1.13      </p>
    1.14      <h3>Models</h3>
    1.15      <p>
    1.16 -      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 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.
    1.17 +      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.
    1.18      </p>
    1.19      <pre>
    1.20  -- filename: model/customer_receipt.lua
    1.21 @@ -263,7 +263,7 @@
    1.22      </p>
    1.23      <h3>Views</h3>
    1.24      <p>
    1.25 -      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.
    1.26 +      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.
    1.27      </p>
    1.28      <h3>Actions</h3>
    1.29      <p>
    1.30 @@ -305,7 +305,9 @@
    1.31        Such translation files can be automatically created with the <tt>langtool.lua</tt> program, found in the framework's <tt>bin/</tt> directory.
    1.32      </p>
    1.33      <h2>Directory structure of a WebMCP application</h2>
    1.34 -    Summarizing information from the previous section, we get the following directory structure for a WebMCP application:
    1.35 +    <p>
    1.36 +      Summarizing information from the previous section, we get the following directory structure for a WebMCP application:
    1.37 +    </p>
    1.38      <ul>
    1.39        <li>
    1.40          Base Directory
    1.41 @@ -410,21 +412,29 @@
    1.42      </ul>
    1.43      <h2>Starting your application</h2>
    1.44      <p>
    1.45 -      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:
    1.46 +      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 four arguments:
    1.47 +    </p>
    1.48 +    <ol>
    1.49 +      <li>Path of the WebMCP framework directory, e.g. <tt>./framework</tt></li>
    1.50 +      <li>Path of your application's directory, e.g. <tt>./demo-app</tt></li>
    1.51 +      <li>Name of your applicaiton (usually <tt>main</tt>)</li>
    1.52 +      <li>Name of configuration (e.g. <tt>devel</tt> to use config/devel.lua)</li>
    1.53 +    </ol>
    1.54 +    <p>
    1.55 +      Alternatively, the <tt>moonbridge</tt> binary may be called directly with the following five arguments:
    1.56      </p>
    1.57      <ol>
    1.58 -      <li>
    1.59 -        Path of the WebMCP framework directory, e.g. <tt>./framework</tt>
    1.60 -      </li>
    1.61 -      <li>
    1.62 -        Path of your application's directory, e.g. <tt>./demo-app</tt>
    1.63 -      </li>
    1.64 -      <li>
    1.65 -        Name of your applicaiton (usually <tt>main</tt>)
    1.66 -      </li>
    1.67 -      <li>
    1.68 -        Name of configuration (e.g. <tt>devel</tt> to use config/devel.lua)
    1.69 -      </li>
    1.70 +      <li>Path to <tt>mcp.lua</tt>, e.g. <tt>./framework/bin/mcp.lua</tt></li>
    1.71 +      <li>Path of the WebMCP framework directory, e.g. <tt>./framework</tt></li>
    1.72 +      <li>Path of your application's directory, e.g. <tt>./demo-app</tt></li>
    1.73 +      <li>Name of your applicaiton (usually <tt>main</tt>)</li>
    1.74 +      <li>Name of configuration (e.g. <tt>devel</tt> to use config/devel.lua)</li>
    1.75      </ol>
    1.76 +    <p>
    1.77 +      Note that the demo application will require a database to be set up prior to starting. Execute the following shell commands first:
    1.78 +    </p>
    1.79 +    <pre>
    1.80 +createdb webmcp_demo
    1.81 +psql -v ON_ERROR_STOP=1 -f demo-app/db/schema.sql webmcp_demo</pre>
    1.82      <h2>Automatically generated reference for the WebMCP environment</h2>
    1.83      <ul>

Impressum / About Us