webmcp

changeset 509:6c819040ef6f

Further improvements to WebMCP documentation
author jbe
date Mon Aug 21 01:33:17 2017 +0200 (2017-08-21)
parents f5d2d0ccb94a
children 696d7e5f2bcb
files doc/autodoc-header.htmlpart framework/env/slot/set_layout.lua libraries/mondelefant/mondelefant.lua
line diff
     1.1 --- a/doc/autodoc-header.htmlpart	Sun Aug 20 23:27:20 2017 +0200
     1.2 +++ b/doc/autodoc-header.htmlpart	Mon Aug 21 01:33:17 2017 +0200
     1.3 @@ -1,4 +1,4 @@
     1.4 -<html>
     1.5 +<HTML>
     1.6    <head>
     1.7      <script type="text/javascript">
     1.8        var expandedSections = {};
     1.9 @@ -172,7 +172,7 @@
    1.10      </ol>
    1.11      </p>
    1.12      <p>
    1.13 -      As a minimum configuration, the used configuration file or pre-fork initializer should at least contain a <tt>listen{...}</tt> call, e.g.:
    1.14 +      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.:
    1.15      </p>
    1.16      <pre>
    1.17  listen{
    1.18 @@ -185,10 +185,10 @@
    1.19        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.20      </p>
    1.21      <ul>
    1.22 -      <li>atom.fraction</li>
    1.23 -      <li>atom.date</li>
    1.24 -      <li>atom.time</li>
    1.25 -      <li>atom.timestamp (date and time combined in one data type)</li>
    1.26 +      <li><a href="#atom.fraction:new">atom.fraction</a></li>
    1.27 +      <li><a href="#atom.date:new">atom.date</a></li>
    1.28 +      <li><a href="#atom.time:new">atom.time</a></li>
    1.29 +      <li><a href="#atom.timestamp:new">atom.timestamp (date and time combined in one data type)</a></li>
    1.30      </ul>
    1.31      <p>
    1.32        In addition the following pseudo-types are existent, corresponding to Lua's base types:
    1.33 @@ -203,7 +203,7 @@
    1.34        Both atom.integer and atom.number refer to Lua's base type &ldquo;number&rdquo;.
    1.35      </p>
    1.36      <p>
    1.37 -      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.38 +      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 <a href="#atom.dump"><tt>atom.dump(value)</tt></a> and later reload it with <tt>atom.<i>type</i>:load(string)</tt>.
    1.39      </p>
    1.40      <h2>Using the Object-Relational Mapper &ldquo;mondelefant&rdquo;</h2>
    1.41      <p>
    1.42 @@ -215,8 +215,8 @@
    1.43        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>):
    1.44      </p>
    1.45      <pre>
    1.46 -_G.db = assert(mondelefant.connect(config.db))
    1.47 -function mondelefant.class_prototype:get_db_conn() return db end
    1.48 +_G.db = assert(<a href="#mondelefant.connect">mondelefant.connect</a>(config.db))
    1.49 +function mondelefant.class_prototype:<a href="#db_class:get_db_conn">get_db_conn</a>() return db end
    1.50  execute.inner()</pre>
    1.51      <p>
    1.52        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.
    1.53 @@ -225,7 +225,7 @@
    1.54        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:
    1.55      </p>
    1.56      <pre>
    1.57 -Movie = mondelefant.new_class()
    1.58 +Movie = <a href="#mondelefant.new_class">mondelefant.new_class</a>()
    1.59  Movie.table = 'movie'</pre>
    1.60      <p>
    1.61        Note: Model classes are always written CamelCase, while the name of the file in <tt>model/</tt> is written lower_case.
    1.62 @@ -234,10 +234,10 @@
    1.63        To select objects from the database, the mondelefant library provides a selector framework:
    1.64      </p>
    1.65      <pre>
    1.66 -local s = Movie:new_selector()
    1.67 -s:add_where{ 'id = ?', param.get_id() }
    1.68 -s:single_object_mode()  -- return single object instead of list
    1.69 -local movie = s:exec()</pre>
    1.70 +local s = Movie:<a href="#db_class:new_selector">new_selector</a>()
    1.71 +s:<a href="#db_selector:add_where">add_where</a>{ 'id = ?', param.get_id() }
    1.72 +s:<a href="#db_selector:single_object_mode">single_object_mode</a>()  -- return single object instead of list
    1.73 +local movie = s:<a href="#db_selector:exec">exec</a>()</pre>
    1.74      <p>
    1.75        A short form of the above query would be:
    1.76      </p>
    1.77 @@ -252,15 +252,22 @@
    1.78      </p>
    1.79      <h3>Models</h3>
    1.80      <p>
    1.81 -      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.82 +      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.83 +    </p>
    1.84 +    <pre>
    1.85 +-- filename: model/customer_receipt.lua
    1.86 +CustomerReceipt = mondelefant.new_class()
    1.87 +CustomerReceipt.table = "custreceipt"</pre>
    1.88 +    <p>
    1.89 +      Methods such as <a href="#db_class:add_reference"><tt>:add_reference(...)</tt></a> can be used to further modify or extend the class.
    1.90      </p>
    1.91      <h3>Views</h3>
    1.92      <p>
    1.93 -      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.94 +      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.95      </p>
    1.96      <h3>Actions</h3>
    1.97      <p>
    1.98 -      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.99 +      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.
   1.100      </p>
   1.101      <h2>Directory structure of a WebMCP application</h2>
   1.102      <ul>
     2.1 --- a/framework/env/slot/set_layout.lua	Sun Aug 20 23:27:20 2017 +0200
     2.2 +++ b/framework/env/slot/set_layout.lua	Mon Aug 21 01:33:17 2017 +0200
     2.3 @@ -6,7 +6,7 @@
     2.4  
     2.5  This function selects which layout should be used when calling slot.render_layout() (as done by request.handler(...)). If nil is selected as layout, then no layout will be used, but the slot named "data" is used plainly. The second argument to slot.set_layout is the content-type which is sent to the browser.
     2.6  
     2.7 -The default layout for views is "default". Actions have no default layout, but an explicit call of slot.set_layout(...) (even with nil as first argument) during request handling will cause subsequent calls of slot.layout_is_set() to return true which indicates that content (e.g. via slot.put_into("data", ...)) is available and should be rendered instead of using the action's return value to forward or redirect the user agent.
     2.8 +The default layout for views is "default" (but errors get a default layout named "system_error"). Actions have no default layout, but an explicit call of slot.set_layout(...) (even with nil as first argument) during request handling will cause subsequent calls of slot.layout_is_set() to return true which indicates that content (e.g. via slot.put_into("data", ...)) is available and should be rendered instead of using the action's return value to forward or redirect the user agent.
     2.9  
    2.10  --]]--
    2.11  
     3.1 --- a/libraries/mondelefant/mondelefant.lua	Sun Aug 20 23:27:20 2017 +0200
     3.2 +++ b/libraries/mondelefant/mondelefant.lua	Mon Aug 21 01:33:17 2017 +0200
     3.3 @@ -929,6 +929,24 @@
     3.4  ------------------
     3.5  
     3.6  --[[--
     3.7 +<db_class>.schema
     3.8 +
     3.9 +Can be set if the underlying table is not in the default "public" schema of the PostgreSQL database. Leave untouched (i.e. nil) otherwise.
    3.10 +
    3.11 +--]]--
    3.12 +class_prototype.schema = nil
    3.13 +--//--
    3.14 +
    3.15 +--[[--
    3.16 +<db_class>.table
    3.17 +
    3.18 +Name of the table in the PostgreSQL database. Should be set in the model file of each model.
    3.19 +
    3.20 +--]]--
    3.21 +class_prototype.table = nil
    3.22 +--//--
    3.23 +
    3.24 +--[[--
    3.25  <db_class>.primary_key
    3.26  
    3.27  Primary key of a database class (model). Defaults to "id".

Impressum / About Us