/ 
App-MFILE-WWW-0.176
River stage one • 1 direct dependent • 1 total dependent
/ App::MFILE::WWW

NAME

App::MFILE::WWW - Web UI development toolkit with prototype demo app

VERSION

Version 0.176

LICENSE

This software is distributed under the "BSD 3-Clause" license, the text of which can be found in the file named COPYING in the top-level distro directory. The license text is also reprodued at the top of each source file.

SYNOPSIS

$ man mfile-www
$ mfile-www
$ firefox http://localhost:5001

DESCRIPTION

This distro contains a foundation/framework/toolkit for developing the "front end" portion of web applications.

App::MFILE::WWW is a Plack application that provides a HTTP request-response handler (based on Web::Machine), CSS and HTML source code for an in-browser "screen", and JavaScript code for displaying various "widgets" (menus, forms, etc.) in that screen and for processing user input from within those widgets.

In addition, infrastructure is included (but need not be used) for user authentication, session management, and communication with a backend server via AJAX calls.

Front ends built with App::MFILE::WWW will typicaly be menu-driven, consisting exclusively of fixed-width Unicode text, and capable of being controlled from the keyboard, without the use of a mouse. The overall look-and-feel is reminiscent of the text terminal era.

The distro comes with a prototype (demo) application to illustrate how the various widgets are used.

QUICK START (DEMO)

App::MFILE::WWW can be run as a standalone "front-end web application" written in JavaScript with an embedded HTTP server.

Assuming App::MFILE::WWW has been installed properly, this mode of operation can be started by running mfile-www, as a normal user (even 'nobody'), with no arguments or options:

$ mfile-www

The start-up script will write information about its state to the standard output. This includes the location of its log file, the port where the HTTP server is listening (default is 5001), etc. For a detailed description of what happens when the start-up script is run, see the POD of mfile-www itself - e.g. "man mfile-www".

DERIVED WWW CLIENTS

When you write your own web frontend using this distro, from App::MFILE::WWW's perspective it is a "derived client" and will be referred to as such in this document.

Derived client operation

In a derived-client scenario, App::MFILE::WWW serves as the foundation upon which the "real" application is built.

The derived-client handling is triggered by providing the --ddist command-line option, i.e.

$ mfile-www --ddist=App-Dochazka-WWW

where 'App-Dochazka-WWW' refers to the Perl module App::Dochazka::WWW, which is assumed to contain the derived client source code.

So, in the first place it is necessary to create such a Perl module. It should have a sharedir configured and present. One such derived client, App::Dochazka::WWW, is available on CPAN.

PERL AND JAVASCRIPT

The App::MFILE::WWW codebase has two parts, or "sides": the "Perl side" and the "JavaScript side". The Perl side implements the embedded web server and the JavaScript side implements the front-end application served to browsers by the Perl side.

Control passes from the Perl side to the JavaScript side

  • synchronously whenever the user (re)loads the page

  • asynchronously whenever the user triggers an AJAX call

Perl side

The HTTP request-response cycle implemented by the Perl side is designed to work approximately like this:

  • nginx listens for incoming connections on port 80/443 of the server

  • When a connection comes in, nginx decrypts it and forwards it to a high-numbered port where a PSGI-compatible HTTP server (such as Starman) is listening

  • The embedded HTTP server takes the connection and passes it to the Plack middleware. The key middleware component is Plack::Middleware::Session, which assigns an ID to the session, stores whatever data the server-side code needs to associate with the session, links the session to the user's browser via a cookie, and provides the application a hook (in the Plack environment stored in the HTTP request) to access the session data

  • if the connection is asking for static content (defined as anything in images/, css/, or js/), that content is served immediately and the request doesn't even make it into our Perl code

  • any other path is considered dynamic content and is passed to Web::Machine for processing -- Web::Machine implements the HTTP standard as a state machine

  • the Web::Machine state machine takes the incoming request and runs it through several functions that are overlayed in App::MFILE::WWW::Resource - an appropriate HTTP error code is returned if the request doesn't make it through the state machine. Along the way, log messages are written to the log.

  • as part of the state machine, all incoming requests are subject to "authorization" (in the HTTP sense, which actually means authentication). First, the session data is examined to determine if the request belongs to an existing authorized session. If it doesn't, the request is treated as a login/logout attempt -- the session is cleared and control passes to the JavaScript side, which, lacking a currentUser object, displays the login dialog.

  • once an authorized session is established, there are two types of requests: GET and POST

  • incoming GET requests happen whenever the page is reloaded - in an authorized session, this causes the main menu to be displayed, but all static content (CSS and JavaScript modules) are reloaded for a "clean slate", as if the user had just logged in.

  • Note that App::MFILE::WWW pays no attention to the URI - if the user enters a path (e.g. http://mfile.site/some/bogus/path), this will be treated like any other page (re)load and the path is simply ignored.

  • if the session is expired or invalid, any incoming GET request will cause the login dialog to be displayed.

  • well-formed POST requests are directed to the process_post routine in App::MFILE::WWW::Dispatch. In derived-distro mode, the derived distro must provide its own dispatch module.

  • under ordinary operation, the user will spend 99% of her time interacting with the JavaScript code running in her browser, which will communicate asynchronously as needed with the back-end (which must be implemented separately) via AJAX calls.

JavaScript side

The JavaScript side provides a toolkit for building web applications that

do not require the use of a mouse; and
look and feel very much like text terminal applications from the 1980s

Developing a front-end application with App::MFILE::WWW currently assumes that you, the developer, will want to use RequireJS, jQuery, and QUnit.

The JavaScript code is modular. Each code module has its own file and modules are loaded asynchronously by RequireJS. Also, jQuery and QUnit http://qunitjs.com/ are loaded automatically.

In addition to the above, App::MFILE::WWW provides a number of primitives, also referred to as "targets", that can be used to quickly slap together a web application. The next chapter explains what these widgets are and how to use them.

FRONT-END PRIMITIVES

The JavaScript side implements a set of primitives, or widgets, from which the front-end application is built up. These include a menu primitive, a form primitive for entering data, table and "browser" primitives for viewing datasets, and a "rowselect" primitive for selecting among

daction

The daction primitive is a generalized widget that can do anything.

dbrowser

The dbrowser primitive is like dform, except that it displays a set of data objects and enables the user to "browse" the dataset using arrow keys. Like dform, the primitive includes "miniMenu" functionality through which the user can potentially trigger actions that take the current object as input.

dcallback

The dcallback primitive is useful for cases when none of the other primitives are appropriate for displaying a given type of object, and no interactivity is needed beyond that provided by miniMenu. The dcallback primitive writes the target title and miniMenu to the screen, along with a "dcallback" div in between, which it populates by calling the callback function. Since the callback function part of the target definition, it can be app-specific.

dform

The dform primitive is used to implement forms consisting of read-only fields (for viewing data), read-write fields (for entering data), or a combination of both. A "miniMenu" can be defined, allowing the user to trigger actions that take the current object as input.

dmenu

The dmenu primitive is used to implement menus.

dnotice

The dnotice primitive takes an HTML string and displays it. The same functionality can be accomplished with a daction, of course, but using the dnotice primitive ensures that the notice will have the same "look and feel" as the other widgets.

drowselect

The drowselect primitive takes an array of strings, displays them vertically as a list, and allows the user to choose one and perform an action on it. Actions are defined via a miniMenu. The currently-selected item is displayed in reverse-video.

dtable

The dtable primitive is similar to dbrowser in that it takes a set of objects and allows the user to choose one and perform actions on it via a miniMenu. Unlike dbrowser, however, it display the objects in table form. The currently-selected object is displayed in reverse video.

JAVASCRIPT UNIT TESTS

The JavaScript side has unit tests and functional tests that can be run by starting the application and then pointing the browser to a URL like:

http://localhost:5001/test

The tests are implemented using QUnit. A good source of practical advise on the use of QUnit is the QUnit Cookbook, available here:

https://qunitjs.com/cookbook/

The QUnit API itself is documented here:

http://api.qunitjs.com/

Adding new test cases

There are separate sets of JavaScript unit tests for each of the following three components:

mfile-www core
mfile-www demo app
derived application (e.g. dochazka-www)

To add a new test case, go to the appropriate tests/ directory (in mfile-www core, in the mfile-www demo app, or in your derived application, as appropriate) and create a js file (use one of the other tests/*.js files as a model). Then add this file to the test.js file in the parent directory.

DEVELOPMENT NOTES

UTF-8

In conformance with the JSON standard, all data passing to and from the server are assumed to be encoded in UTF-8. Users who need to use non-ASCII characters should check their browser's settings.

Deployment

To minimize latency, App::MFILE::WWW can be deployed on the same server as the back-end (e.g. App::Dochazka::REST), but this is not required.

PACKAGE VARIABLES

For convenience, the following variables are declared with package scope:

FUNCTIONS

init

Initialization routine - run from bin/mfile-www, the server startup script. This routine loads configuration parameters from files in the distro and site configuration directories, and sets up logging.

FIXME: This code could be moved into the startup script.