table of contents
MFILE-WWW(1) | User Contributed Perl Documentation | MFILE-WWW(1) |
NAME¶
mfile-www - App::MFILE::WWW server startup script
SYNOPSIS¶
Standalone mode (runs demo "app" on http://localhost:5001):
$ mfile-www
Derived distribution mode with derived distro 'App::Dochazka::WWW':
First, create necessary directories and symlinks by running as root with --init:
$ sudo mfile-www --ddist=App-Dochazka-WWW --init
Then, start the HTTP server
$ mfile-www --ddist=App-Dochazka-WWW
Or, if you need site configuration:
$ mfile-www --dist=App-Dochazka-WWW --sitedir=/foo/bar/baz
NOTE: Be careful with the "--ddist" option - especially when running as root - because the script will treat the argument to this option as a "derived" Perl distribution, and attempt to create new directories and symlinks in that distribution's "sharedir" (shared directory).
DESCRIPTION¶
Run this script from the bash prompt to start the server that will provide the HTTP server (e.g. Starman) that will serve the JavaScript source files that make up your application's frontend.
Standalone operation (demo)¶
- by default (in the absence of the "--ddist" option), $ddist is set to the empty string
- $ddist_dir is not set
- the script calls the "App::MFILE::WWW::init" routine, which loads the configuration parameters stored in "config/WWW_Config.pm" of the core distro (App::MFILE::WWW) sharedir
- since no "sitedir" option was specified on the command line, no other configuration files are loaded
- the configuration parameters and their core default values can be seen in "config/WWW_Config.pm" under the core distro (App::MFILE::WWW) sharedir
- a very important configuration parameter is MFILE_WWW_LOG_FILE, which is the full path to the log file where the Perl side of App::MFILE::WWW will write its log messages -- by default, this is set to '.mfile-www.log' in the user's home directory, and the current setting is always reported on-screen by the startup script so the user knows where to look if something goes wrong
- the HTTP server is started by calling Plack::Runner, and the script reports to the user the port number at which it is listening (5001 by default)
- the HTTP server always interprets URL paths it receives relative to its "root" (called "HTTP_ROOT" for the purposes of this document), which is set to the core distro (App::MFILE::WWW) sharedir in this case
- JS and CSS files are considered "static content" and will be served from "HTTP_ROOT/js" and "HTTP_ROOT/css", respectively
- when an HTTP 'GET' request comes in on the port where the HTTP server is listening, and it is not requesting static content, the request is passed on to the Web::Machine application (effectively, App::MFILE::WWW::Resource) for processing
- POST requests are assumed to be AJAX calls and are handled by the "process_post" routine of App::MFILE::WWW::Resource
- GET requests are assumed to have originated from a web browser running on a user's computer -- to handle these, the "main_html" routine of "Resource.pm" generates HTML code which is sent back in the HTTP response
- the HTML so generated contains embedded JavaScript code to start up RequireJS <http://requirejs.org> with the required configuration and pass control over to "the JavaScript side" of App::MFILE::WWW
The embedded JavaScript code does the following:
- sets the "baseURL" to "$site->MFILE_WWW_REQUIREJS_BASEURL", which is set to "/js" -- in absolute terms, this means "HTTP_ROOT/js"
- sets the ""app"" path config to "$site->MFILE_APPNAME" -- for example, if "$site->MFILE_APPNAME" is set to 'foobar', the path config for "app" will be set to "foobar" and a RequireJS dependency "app/bazblat" on the JavaScript side will translate to "HTTP_ROOT/js/foobar/bazblat.js"
- in this particular case, of course, "MFILE_APPNAME" is set to "mfile-www"
- persuades RequireJS via magic incantations to "play nice" together with jQuery and QUnit
- by calling "requirejs.config", brings in site configuration parameters needed on the JavaScript side so they can be accessed via the "cf" JS module
- passes control to the "app/main" JS module
What happens on the JavaScript side is described in a different section of this documentation.
Derived distribution mode¶
Nice as the demo may be, the real purpose of App::MFILE::WWW is to provide a structure for writing "real" web frontends. For this purpose, "bin/mfile-www" is run in "derived distribution mode".
Here is a "play-by-play" description of what happens in this scenario when the startup script is run. Again, refer to the script source code for better understanding:
- $ddist is set to the string given in the "--ddist" option, e.g. "App-Dochazka-WWW" (or 'App::Dochazka::WWW' in which case it will be converted to the correct, hyphen-separated format)
- $ddist_dir is set to File::ShareDir::dist_dir( $ddist ), i.e. the derived distro sharedir (extending the above example, the distro sharedir of App::Dochazka::WWW)
- the presence of the "--ddist" option triggers a special routine whose purpose is to ensure that the derived distro exists and that its sharedir is properly set up to work with App::MFILE::WWW:
- error exit if the distro referred to by the "--ddist" option doesn't exist
- error exit if the distro lacks a sharedir
- "css" and "js/core" need to exist and be symlinks to the same directories in the App::MFILE::WWW sharedir. If this is not the case, the script displays a message asking the user to re-run the script as root with --init
- if already running as root, the symlinks are created and the script displays a message asking to be re-run without --init as a normal user
- once the symlinks are in place, the script runs some sanity checks (mainly verifying the existence of certain files in their expected places)
- •
- the script calls the "App::MFILE::WWW::init" routine, which loads the configuration parameters stored in the following places:
- the App::MFILE::WWW distro sharedir (under "config/WWW_Config.pm")
- the derived distro sharedir (also under "config/WWW_Config.pm")
- finally and optionally, if a sitedir was specified on the command line -- for example "--sitedir=/etc/dochazka-www" --, configuration parameters are loaded from a file "WWW_SiteConfig.pm" in that directory, overriding the defaults
- the derived distro's configuration should override the MFILE_APPNAME parameter -- in our example, it could be set to 'dochazka-www'
- also refer to the previous section to review the explanation of the MFILE_WWW_LOG_FILE parameter
- the HTTP server is started by calling Plack::Runner, and the script reports to the user at what port number it is listening (5001 by default)
- the HTTP server always interprets URL paths it receives relative to its "root" (called "HTTP_ROOT" for the purposes of this document), which is set to the derived distro's sharedir
- the rest of the description is the same as for Standalone operation
2017-12-07 | perl v5.40.0 |