webmcp

changeset 510:696d7e5f2bcb

Added "Layouts" section to WebMCP documentation and cleaned "Directory structure" section up
author jbe
date Mon Aug 21 03:58:33 2017 +0200 (2017-08-21)
parents 6c819040ef6f
children bb1f3e7c65d1
files doc/autodoc-header.htmlpart
line diff
     1.1 --- a/doc/autodoc-header.htmlpart	Mon Aug 21 01:33:17 2017 +0200
     1.2 +++ b/doc/autodoc-header.htmlpart	Mon Aug 21 03:58:33 2017 +0200
     1.3 @@ -269,7 +269,31 @@
     1.4      <p>
     1.5        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.6      </p>
     1.7 +    <h2>Layouts</h2>
     1.8 +    <p>
     1.9 +      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:
    1.10 +    </p>
    1.11 +    <pre>
    1.12 +&lt;!DOCTYPE HTML&gt;
    1.13 +&lt;html&gt;
    1.14 +  &lt;head&gt;
    1.15 +    &lt;title&gt;&lt!-- WEBMCP SLOTNODIV title --&gt;&lt;/title&gt;
    1.16 +    &lt;link rel="stylesheet" type="text/css" media="screen" href="__BASEURL__/static/style.css"/&gt;
    1.17 +  &lt;/head&gt;
    1.18 +  &lt;body&gt;
    1.19 +    &lt;!-- WEBMCP SLOT content --&gt;
    1.20 +  &lt;/body&gt;
    1.21 +&lt;/html&gt;</pre>
    1.22 +    <p>
    1.23 +      The following elements in a layout file get replaced automatically:
    1.24 +    </p>
    1.25 +    <ul>
    1.26 +      <li><tt>__BASEURL__</tt> gets replaced with the application's base web address.</li>
    1.27 +      <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>
    1.28 +      <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>
    1.29 +    </ul>
    1.30      <h2>Directory structure of a WebMCP application</h2>
    1.31 +    Summarizing information from the previous section, we get the following directory structure for a WebMCP application:
    1.32      <ul>
    1.33        <li>
    1.34          Base Directory
    1.35 @@ -277,109 +301,36 @@
    1.36            <li>
    1.37              <tt>app/</tt>
    1.38              <ul>
    1.39 +              <li><tt>_prefork/</tt></li>
    1.40 +              <li><tt>_postfork/</tt></li>
    1.41                <li>
    1.42 -                <tt>_prefork/</tt>
    1.43 -                <ul>
    1.44 -                  <li>
    1.45 -                    <tt>10_first_prefork_initializer.lua</tt>
    1.46 -                  </li>
    1.47 -                  <li>
    1.48 -                    <tt>30_third_prefork_initializer.lua</tt>
    1.49 -                  </li>
    1.50 -                </ul>
    1.51 -              </li>
    1.52 -              <li>
    1.53 -                <tt>_postfork/</tt>
    1.54 +                <tt>main/</tt> (typically "main" is the only application)
    1.55                  <ul>
    1.56 -                  <li>
    1.57 -                    <tt>01_first_postfork_initializer.lua</tt>
    1.58 -                  </li>
    1.59 -                  <li>
    1.60 -                    <tt>03_third_postfork_initializer.lua</tt>
    1.61 -                  </li>
    1.62 -                </ul>
    1.63 -              </li>
    1.64 -              <li>
    1.65 -                <tt>main/</tt>
    1.66 -                <ul>
    1.67 -                  <li>
    1.68 -                    <tt>_prefork/</tt>
    1.69 -                    <ul>
    1.70 -                      <li>
    1.71 -                        <tt>20_second_prefork_initializer.lua</tt>
    1.72 -                      </li>
    1.73 -                    </ul>
    1.74 -                  </li>
    1.75 +                  <li><tt>_prefork/</tt></li>
    1.76 +                  <li><tt>_postfork/</tt></li>
    1.77 +                  <li><tt>_filter/</tt></li>
    1.78 +                  <li><tt>_filter_action/</tt></li>
    1.79 +                  <li><tt>_filter_view/</tt></li>
    1.80 +                  <li><tt>_layout/</tt></li>
    1.81                    <li>
    1.82 -                    <tt>_postfork/</tt>
    1.83 -                    <ul>
    1.84 -                      <li>
    1.85 -                        <tt>02_second_postfork_initializer.lua</tt>
    1.86 -                      </li>
    1.87 -                    </ul>
    1.88 -                  </li>
    1.89 -                  <li>
    1.90 -                    <tt>_filter/</tt>
    1.91 -                    <ul>
    1.92 -                      <li>
    1.93 -                        <tt>10_first_filter.lua</tt>
    1.94 -                      </li>
    1.95 -                      <li>
    1.96 -                        <tt>30_third_filter.lua</tt>
    1.97 -                      </li>
    1.98 -                      <li>&hellip;</li>
    1.99 -                    </ul>
   1.100 -                  </li>
   1.101 -                  <li>
   1.102 -                    <tt>_filter_action/</tt>
   1.103 -                    <ul>
   1.104 -                      <li>
   1.105 -                        <tt>20_second_filter.lua</tt>
   1.106 -                      </li>
   1.107 -                      <li>&hellip;</li>
   1.108 -                    </ul>
   1.109 -                  </li>
   1.110 -                  <li>
   1.111 -                    <tt>_filter_view/</tt>
   1.112 -                    <ul>
   1.113 -                      <li>&hellip;</li>
   1.114 -                    </ul>
   1.115 -                  </li>
   1.116 -                  <li>
   1.117 -                    <tt>_layout/</tt>
   1.118 -                    <ul>
   1.119 -                      <li>&hellip;</li>
   1.120 -                    </ul>
   1.121 -                  </li>
   1.122 -                  <li>
   1.123 -                    <tt>index/</tt>
   1.124 +                    <tt>index/</tt> (module "index" is the default module)
   1.125                      <ul>
   1.126                        <li>
   1.127                          <tt>_action/</tt>
   1.128                          <ul>
   1.129 -                          <li>
   1.130 -                            <i>action_name</i><tt>.lua</tt>
   1.131 -                          </li>
   1.132 -                          <li>
   1.133 -                            <i>another_action_name</i><tt>.lua</tt>
   1.134 -                          </li>
   1.135 +                          <li><i>action_name</i><tt>.lua</tt></li>
   1.136 +                          <li><i>another_action_name</i><tt>.lua</tt></li>
   1.137                            <li>&hellip;</li>
   1.138                          </ul>
   1.139                        </li>
   1.140 -                      <li>
   1.141 -                        <tt>index.lua</tt>
   1.142 -                      </li>
   1.143 -                      <li>
   1.144 -                        <i>other_view_name</i><tt>.lua</tt>
   1.145 -                      </li>
   1.146 +                      <li><tt>index.lua</tt> (view "index" of module "index" is the default view)</li>
   1.147 +                      <li><i>other_view_name</i><tt>.lua</tt></li>
   1.148                        <li>&hellip;</li>
   1.149                      </ul>
   1.150                    </li>
   1.151                    <li>
   1.152                      <i>other_module_name</i><tt>/</tt>
   1.153 -                    <ul>
   1.154 -                      <li>&hellip;</li>
   1.155 -                    </ul>
   1.156 +                    <ul><li>&hellip;</li></ul>
   1.157                    </li>
   1.158                  </ul>
   1.159                </li>
   1.160 @@ -394,28 +345,20 @@
   1.161            <li>
   1.162              <tt>config/</tt>
   1.163              <ul>
   1.164 -              <li>
   1.165 -                <tt>development.lua</tt>
   1.166 -              </li>
   1.167 -              <li>
   1.168 -                <tt>production.lua</tt>
   1.169 -              <li>
   1.170 -              <li>
   1.171 -                <i>other_config_name</i><tt>.lua</tt>
   1.172 -              </li>
   1.173 +              <li><tt>development.lua</tt> (e.g. to be used for development purposes)</li>
   1.174 +              <li><tt>production.lua</tt> (e.g. to be used for production)</li>
   1.175 +              <li><i>other_config_name</i><tt>.lua</tt></li>
   1.176                <li>&hellip;</li>
   1.177              </ul>
   1.178            </li>
   1.179            <li>
   1.180              <tt>db/</tt>
   1.181              <ul>
   1.182 -              <li>
   1.183 -                <tt>schema.sql</tt>
   1.184 -              </li>
   1.185 +              <li><tt>schema.sql</tt> (not used by WebMCP, but may be used to initialize a database)</li>
   1.186              </ul>
   1.187            </li>
   1.188            <li>
   1.189 -            <tt>locale/</tt>
   1.190 +            <tt>locale/</tt> (translation files used by the <a href="#_">underscore function</a>")
   1.191              <ul>
   1.192                <li>
   1.193                  <tt>translations.de.lua</tt>
   1.194 @@ -433,7 +376,7 @@
   1.195              <tt>model/</tt>
   1.196              <ul>
   1.197                <li>
   1.198 -                <i>model_name</i><tt>.lua</tt>
   1.199 +                <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>")
   1.200                </li>
   1.201                <li>
   1.202                  <i>another_model_name</i><tt>.lua</tt>
   1.203 @@ -448,7 +391,7 @@
   1.204              </ul>
   1.205            </li>
   1.206            <li>
   1.207 -            <tt>tmp/</tt> (writable by the web process)
   1.208 +            <tt>tmp/</tt> (needs to be writable by the user executing WebMCP)
   1.209            </li>
   1.210          </ul>
   1.211        </li>

Impressum / About Us