Webapp architecture
In a webapp, the main event handling is controlled by the runHandler function. This function looks for a variable in the incoming POST data called kaya_submit_Kayn, where n is a number. If one is found, then it will take the contents of the kaya_control_Kayn variable, decrypt it with the application secret key using decode, and uncompress it with uncompressString. This gives a serialised representation of a Triple containing a function, a function parameter, and a prefix string. This is then unserialised with unmarshal and provided the prefix matches the expected one (see below for more about prefixes) the function is run with the function parameter. runHandler then returns the return value of the function.
If no kaya_submit_Kayn variable exists in the POST data, then the GET data will be checked for the presence of a kaya_control variable. If this exists, it will be decrypted and run as above.
If neither GET nor POST contain the right variable, then the default function passed to runHandler will be run with no parameters.
Creating the control fields.
The control fields are created by the following methods:
- addLocalControlInput creates the
kaya_submit_Kayn andkaya_control_Kayn contents, and places them into <input> elements in the HTML, makingkaya_submit_Kayn a submit button for the form. - The localControlURL function creates a URL containing the current web application and the
kaya_controlparameter. This can then be used just as other URLs, and additional parameters may be appended.
The 'prefix' parameter
The addLocalControlInput and localControlURL functions may both take a prefix. If this is done, all form and URL variables they produce will have this prefix added to the start of their name.
url1 = localControlURL(@myFn,state,"");
// url1 = "./app.cgi?kaya_control=.....";
url2 = localControlURL(@myFn,state,"subsection");
// url1 = "./app.cgi?subsectionkaya_control=.....";The runHandler function also takes a prefix, and will only look for control variables with the same prefix. This allows multiple runHandler calls to coexist in the same application, which is useful for writing application components.
CGI architecture
The CGI architecture is similar to the webapp architecture in the means used to store and retrieve state in the web browser. Instead of using runHandler, the CGI template automatically runs the retrieved state after running the PreContent function, or runs the Default function if no state can be retrieved. State in the CGI model is stored in the kaya_function (function to run) and kaya_arg (function argument) hidden input fields or URL parameters by the formHandler and linkHandler functions.
A kaya_prepost input may also be created. If this (after decryption and unmarshalling) equals zero, then the PreContent and PostContent functions are not run.
Other differences from the webapp architecture are that there is no way to set a prefix, and the state data is not compressed between serialisation and encryption (for the relatively small state used in most CGI model applications, this is usually more efficient).
Alternative storage of state
It is sometimes useful, either if the state is very large, or if most of the user interaction with the application is via hyperlinks and the GET method where 'friendly URLs' are important, to store the state itself server-side, and only send a pointer to the state to the user's web browser. In the webapp model, the storeFunction and retrieveFunction allow an interface to server-side storage to be constructed. The API documentation and the server-side state tutorial contain some examples of usage. While the format (encrypted compressed serialised data) for storage of state remains unchanged, the methods for storing and retrieving it are application-defined.
