Handling AJAX and non-AJAX requests
Lichen has a mode where it can work without JavaScript enabled, rendering the appropriate HTML on the server and returning that, instead of returning JSON objects for the client side to parse and use.
Strategy - AJAX
All AJAX requests post back to ajax.php. Upon login, a variable is set in session, telling Lichen if the session is a AJAX session or not. ajax.php uses this flag to determine how to handle the request to ajax.php.
To handle an ajax request, it expects to have a variable called 'request' passed to it. "request_" is prepended to the value of the $_POST['request'] variable, and this is considered as a function name to call.
If the request function exists, it is called according to the method documented in RequestMethods.
If the request succeeded, the results of the function are JSON encoded and returned to the client. If the request failed, the errorString and errorCode are JSON encoded and returned to the client, so that it can handle the error condition.
Strategy - non-AJAX
All non-ajax requests are handled by ajax.php. Upon login, a variable is set in session, telling Lichen if the session is a AJAX session or not. ajax.php uses this flag to determine how to handle the request to ajax.php.
Lichen always passes back the following variables (regardless of mode):
- mailbox - the current IMAP mailbox.
- search - the current IMAP search term.
- sort - the current sort method.
- page - the current view page.
- mboxopen - the top level mailboxes that are expanded in the mailbox view on the left.
To control what Lichen does when processing a non-AJAX request, it passes back a variable called 'sequence'. This variable defines what 'mode' Lichen is currently in, and is a general overview of what it is supposed to be displaying. The value of sequence is one of 'list', 'comp', 'disp', or 'settings', corresponding with a message list, the composer, message display, or settings screen respectively. If sequence is not set, then 'list' is assumed.
Before the sequence is processed, some common processing is done. This includes generating the mailbox list that goes on the left, preparing the page headers (ie, <html><head>, etc), handling and setting the basic variables.
The sequence variable is passed into a large switch statement, with one section for each possible sequence. The case sections of this switch statement contain the logic to determine exactly what to do. These sections generally perform the following tasks:
- Figure out what processing needs to occur for the given user input.
- Call the appropriate "request_foo()" functions to do whatever action is required. (These follow the standards documented in RequestMethods)
- Call a "render_foo()" function, that renders the HTML as a result of the processing. For example, this could be a list of messages, or a display of an email. (These follow the standards documented in RenderMethods)
The sequences generally look for another variable, generally called '<foo>action', which defines a subaction to be performed in that sequence. For example, 'listaction' might be set to 'move', which means 'move the selected messages'. This is processed at the beginning of each sequence, as it generally affects the rendered outcome (eg, moving a message - you shouldn't see the message after you've just moved it).
Some of the code gets ugly in the non-AJAX dispatcher, but some examination should show how it works. It has so far proven reasonably easy to modify to match the AJAX version of Lichen.
There are some other helper functions for the non-AJAX version designed to make working with the non-AJAX version less hard. See NonAJAXHelpers for information on those functions.
