A VSPX page describes a web page in terms of static XHTML plus XML elements in the VSPX namespace, "http://example.com/vspx/" . This namespace is abbreviated as v: in the rest of this document.

Elements in the v namespace introduce VSPX elements, options or controls. Some of these may in turn have HTML children. VSPX elements with HTML children are called templates, as these will process their HTML contents at run time, typically modifying these based on run time data.

Figure 14.15. VSPX Conceptual Diagram

VSPX Conceptual Diagram

When the page is requested, the system checks whether it is already compiled and compiles it if the compilation is absent or older than the source. The VSPX compilation has two phases: pre-processing and compilation. The first phase expands included files and applies the external macro XSL-T sheet. The result of which is a single page encapsulating all related components which will be stored in a .vspx-m intermediary file. The result of second phase, compilation is a single .vspx-sql file containing class and method definitions for a subclass of the generic VSPX page class. All code directly derived from the pre-processed page will be found in this file. The file can of course refer to outside Virtuoso/PL code.

The results of compilation process are stored usually in an OS dependent temporary directory. This would be the $TMPDIR for UNIXes or %TMP% for Windows platforms. If these environment variables are not available it will be some default system specific location, such as /var/tmp or /tmp on Unix's. Note that this temporary storage applies to the VSPX pages that are stored within the file system, for the WebDAV repository the product of compilation is stored as described below. For development purposes the use of temporary storage can be turned off by executing:

registry_set ('__no_vspx_temp', '1')

from ISQL. In this case both file-system and WebDAV repository will contain .vspx-m and .vspx-sql files in the same place and with the same name as the VSPX source file. VSPX temporary storage can be re-enabled in the same way but using the string value '0' instead of '1'. Note that this is a string rather than a number.

Any VSPX page invocation, whether through the GET or POST HTTP request, consists of the following steps:

  • Instantiation.  The tree of widgets is built according to the page description. The possibly saved state of controls is restored when instantiating these, if there was a persistent state vector as part of the post request or stored on the server.

  • Data Binding.  The tree is traversed and attributes or subtrees depending on SQL expressions are set or instantiated.

  • Post Processing.  If this was a POST request, the control that was mentioned in the POST gets a post event, as well as any enclosing controls or input controls affected by the posted data. The subtree containing the submit button originating the POST gets the post event to all its nodes, children before parents. Post data server side validation takes place during this phase. Any database updating takes place during this processing, typically inside the post handler of the form element, after the post handling of each individual field is complete.

  • Before Render.  The control tree is now assumed to be in a state reflecting the operation intended by the POST or GET. This pass typically collects the page state to be persisted. Other application dependent finalization operations can be added here.

  • Render.  This pass is a depth first traversal of the control tree and is responsible for generating the text to be sent to the user agent. This will typically be straight HTML, but can also be something else, such as XML for post processing in a style sheet.

Just as with VSP pages the code of the page make call http_xslt(), this has the effect of applying the specific stylesheet to the HTML text produced by the render phase. Since output contains HTML tags generated by VSPX controls, the style-sheet should have these as a general rule to leave these unchanged. The http_xslt () is more useful with VSP pages producing XML than with VSPX pages.