• Info
• Initial State
• View Source
• Run

Basic VSPX Programming

VX-S-1 Simple VSPX controls

Building a VSPX page

Preliminaries

The framework named Virtuoso Server Pages Extensions (VSPX) is a set of widgets (controls) which are executed on server side. The VSPX page itself is an active page which contains XHTML, VSP and widget code. The VSPX page like VSP is a server side executable, so in both cases the virtual directory where pages are placed needs to be executable. For the details of virtual directory setup please read VS-B-1.

It might appear that VSPX pages and VSP pages are similar, but in practice there are differences:

• The content of a VSPX page must be well-formed XML (like XHTML), in contrast to a VSP page where this is not mandatory.
• VSPX pages have a container element named "page", VSP pages do not (they are processing instruction based).
• The controls and containers in the VSPX page are in a special name space: "http://www.openlinksw.com/vspx/", we will alias it with the prefix "vspx:" for the controls in the rest of the tutorials.
• Any active content must be in vspx:page container, and no more than one vspx:page can be in a separate VSPX source file.
• The VSPX pages are compiled to a more complex structure than VSPs.
• The processing model of VSPX pages have five phases on execution: initialization, data-binding, post processing, pre-rendering and rendering. VSP only has pre-processing, and execution. For more details please read the VSPX section in the Virtuoso server documentation.
• The VSPX page may contain one or more controls, VSPs do not have components. Also each control in the VSPX page (and page container itself) represents a user defined type (class).

As VSPX pages may contain macros and may have a pre-processing XSL-T transformation, an intermediate file will be generated in the same place where the source page is. Also the compilation will generate a SQL script as a file before compilation of PL code in memory. These files will be explained later in the VX-S-8 example.

Finally there are several notes about VSPX controls (widgets). They need to have unique names in the page space, including the macro expanded ones. It is not mandatory for the page name to be unique in the Web server space. All of the controls are represented by trees of class instances, where each member vc_children contains instances to the children controls.

Example

The example shows a simple page containing a vspx:page container and basic controls: vspx:label, vspx:url and vspx:include. The vspx:page container (as already discussed) can contain any executable content, but it may not be the topmost element in the page as we may see in the source of simple.vspx page. It also shows how VSP processing instructions can be nested in the VSPX page. On that point we need to say that a good VSPX programming style is to use very minimal VSP code to get the benefit of widgets.

The rest of the controls used in this example can be placed in any other control or container allowing content. The special case is vspx:include which we will discuss later.

The vspx:label is the simplest text label which can be data bound. The "data bound" term designates the ability of the control to obtain a value (it may be constant or Virtuoso/PL expression) on data bind phase when the page gets executed. The format attribute is used to render the data, so it depends on the data type of the control's value. In practice it's a format string as in sprintf() function. In that example the first label has string value and the format is '%s', but second one is integer and the format used is '%d'.

The vspx:url represents a HTML anchor, but value and url are data bind-able. We can talk about it as an extended functionality of the vspx:label control.

The last one is a vspx:include control. This is not a control per se, it's rather a place where the expanded content of another document will be placed before VSPX page compilation. In that way we can easily re-use common code between different pages. In that particular case the included file is very simple, but it can also be another VSPX page. With this approach VSPX pages have more complex ways to do macro expansions which will be explained in detail in VX-S-8.

View the source	Action
1. simple.vspx	Run