File: vspxdoc.xml

package info (click to toggle)
virtuoso-opensource 6.1.4%2Bdfsg1-7
links: PTS, VCS
area: main
in suites: wheezy
size: 245,116 kB
sloc: ansic: 639,631; sql: 439,225; xml: 287,085; java: 61,048; sh: 38,723; cpp: 36,889; cs: 25,240; php: 12,562; yacc: 9,036; lex: 7,149; makefile: 6,093; jsp: 4,447; awk: 1,643; perl: 1,017; ruby: 1,003; python: 329
file content (9867 lines) | stat: -rw-r--r-- 469,378 bytes
parent folder | download | duplicates (2)
<?xml version="1.0" encoding="ISO-8859-1" ?>
<sect2 id="vspx_attr_types" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:vd="http://www.openlinksw.com/vspx/deps/" xmlns:v="http://www.openlinksw.com/vspx/">
<title>Commonly Used Types of Attributes of VSPX Controls</title>
 <refentry id="vc_type_CalculateableValue">
  <refmeta>
    <refentrytitle>CalculateableValue</refentrytitle>
    <refmiscinfo>vspx_simple_type</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>CalculateableValue</refname>
    <refpurpose>The type of attribute that contains an expression to be calculated at run time.</refpurpose>
  </refnamediv>
  <refsect1 id="vc_desc_CalculateableValue">
    <title>Description</title>
    <para>
The type of a string constant or an expression.
If the value of this type is started with &#39;--&#39;, the rest of string
is the text of an expression to be calculated in order to get the effective value of the property.
If the value of this type is not started with &#39;--&#39;, the effective value is the original string itself.
</para>
    <para>
The type identifier &#39;CalculateableValue&#39; is introduced only for diagnostic purposes, you will never use it in VSPX code.
When Virtuoso server tries to compile an invalid VSPX page, you might see a diagnostic messages like &#39;the value of attribute X of a control Y does not match pattern ... for type CalculateableValue&#39;.
If you see this then you should check the syntax of the value of the specified attribute.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_type_ForcedCalculateableValue">
  <refmeta>
    <refentrytitle>ForcedCalculateableValue</refentrytitle>
    <refmiscinfo>vspx_simple_type</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>ForcedCalculateableValue</refname>
    <refpurpose>The type of attribute that contains an expression to be calculated at run time.</refpurpose>
  </refnamediv>
  <refsect1 id="vc_desc_ForcedCalculateableValue">
    <title>Description</title>
    <para>
The type of an expression.
The value of this type must be started with &#39;--&#39;, the rest of string
is the text of an expression to be calculated in order to get the effective value of the property.
</para>
    <para>
The type identifier &#39;ForcedCalculateableValue&#39; is introduced only for diagnostic purposes, you will never use it in VSPX code.
When Virtuoso server tries to compile an invalid VSPX page, you might see a diagnostic messages like &#39;the value of attribute X of a control Y does not match pattern ... for type ForcedCalculateableValue&#39;.
If you see this then you should check the syntax of the value of the specified attribute.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_type_SqlCode">
  <refmeta>
    <refentrytitle>SqlCode</refentrytitle>
    <refmiscinfo>vspx_simple_type</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>SqlCode</refname>
    <refpurpose>The type of a string value that is a Text of a Virtuoso/PL procedure.</refpurpose>
  </refnamediv>
  <refsect1 id="vc_desc_SqlCode">
    <title>Description</title>
    <para>Text of an event handler or other Virtuoso/PL procedure. This is
expected to be a complete statement or sequence of statements, hence
to be terminated like a statement, unlike the &#39;calculatable value&#39;
expression case.
</para>
    <para>
The type identifier &#39;SqlCode&#39; is introduced only for diagnostic purposes, you will never use it in VSPX code.
When Virtuoso server tries to compile an invalid VSPX page, you might see a diagnostic messages like &#39;the value of attribute X of a control Y does not match pattern ... for type SqlCode&#39;.
If you see this then you should check the syntax of the value of the specified attribute.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_type_SqlName">
  <refmeta>
    <refentrytitle>SqlName</refentrytitle>
    <refmiscinfo>vspx_simple_type</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>SqlName</refname>
    <refpurpose>The type of attribute that contains a name of the Virtuoso/PL UDT instance that should be created for the control.</refpurpose>
  </refnamediv>
  <refsect1 id="vc_desc_SqlName">
    <title>Description</title>
    <para>
The type for a Virtuoso/PL name that should be used during code generation.
KNOWN BUG: If double quotes are used in the value of this type then
the generated code may be incorrect.
This is why this schema restrictes the syntax of values of such type.
</para>
    <para>
The type identifier &#39;SqlName&#39; is introduced only for diagnostic purposes, you will never use it in VSPX code.
When Virtuoso server tries to compile an invalid VSPX page, you might see a diagnostic messages like &#39;the value of attribute X of a control Y does not match pattern ... for type SqlName&#39;.
If you see this then you should check the syntax of the value of the specified attribute.
</para>
  </refsect1>
 </refentry>
</sect2>
<sect2 id="vspx_controls" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:vd="http://www.openlinksw.com/vspx/deps/" xmlns:v="http://www.openlinksw.com/vspx/">
<title>VSPX Controls</title>
 <refentry id="vc_after_data_bind">
  <refmeta>
    <refentrytitle>after-data-bind</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>after-data-bind</refname>
    <refpurpose>Container for code that should be executed after data bind.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_after_data_bind">
    <funcprototype id="vc_proto_after_data_bind">
        <funcdef>
            &lt;<function>after-data-bind</function>&gt;(EventHandler)&lt;/<function>after-data-bind</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_after_data_bind">
    <title>Description</title>
    <para>
The code contained in this element is executed after the default data bind processing on the returning edge of recursion.
The context has self as the page, control as the control with this handler, event as the vspx_event which caused the page invocation.
Any return value from the code is ignored.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_after_data_bind_container">
  <refmeta>
    <refentrytitle>after-data-bind-container</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>after-data-bind-container</refname>
    <refpurpose>This is identical to v:after-data-bind.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_after_data_bind_container">
    <funcprototype id="vc_proto_after_data_bind_container">
        <funcdef>
            &lt;<function>after-data-bind-container</function>&gt;(EventHandler)&lt;/<function>after-data-bind-container</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_after_data_bind_container">
    <title>Description</title>
  </refsect1>
 </refentry>
 <refentry id="vc_before_data_bind">
  <refmeta>
    <refentrytitle>before-data-bind</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>before-data-bind</refname>
    <refpurpose>Container for code that should be executed before data bind.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_before_data_bind">
    <funcprototype id="vc_proto_before_data_bind">
        <funcdef>
            &lt;<function>before-data-bind</function>&gt;(EventHandler)&lt;/<function>before-data-bind</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_before_data_bind">
    <title>Description</title>
    <para>
The code contained in this element is executed before the default data bind processing on the descending edge of recursion.
The context has self as the page, control as the control with this handler, event as the vspx_event which caused the page invocation.
A return value from the code if equal to 1 (one) will stop further data-bind processing of the
containing control and it&#39;s children if any.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_before_data_bind_container">
  <refmeta>
    <refentrytitle>before-data-bind-container</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>before-data-bind-container</refname>
    <refpurpose>This is identical to v:before-data-bind.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_before_data_bind_container">
    <funcprototype id="vc_proto_before_data_bind_container">
        <funcdef>
            &lt;<function>before-data-bind-container</function>&gt;(EventHandler)&lt;/<function>before-data-bind-container</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_before_data_bind_container">
    <title>Description</title>
  </refsect1>
 </refentry>
 <refentry id="vc_before_render">
  <refmeta>
    <refentrytitle>before-render</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>before-render</refname>
    <refpurpose>Container for code that should be executed before rendering.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_before_render">
    <funcprototype id="vc_proto_before_render">
        <funcdef>
            &lt;<function>before-render</function>&gt;(EventHandler)&lt;/<function>before-render</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_before_render">
    <title>Description</title>
    <para>
The code contained in this element is executed on the descending edge of recursion when traversing the vspx control tree before rendering.
This is expected to have side effects on vspx controls only, not to return anything or emit any output.
Any return value from the code is ignored.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_before_render_container">
  <refmeta>
    <refentrytitle>before-render-container</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>before-render-container</refname>
    <refpurpose>This is identical to v:before-render.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_before_render_container">
    <funcprototype id="vc_proto_before_render_container">
        <funcdef>
            &lt;<function>before-render-container</function>&gt;(EventHandler)&lt;/<function>before-render-container</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_before_render_container">
    <title>Description</title>
  </refsect1>
 </refentry>
 <refentry id="vc_button">
  <refmeta>
    <refentrytitle>button</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>button</refname>
    <refpurpose>Scriptable button.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_button">
    <funcprototype id="vc_proto_button">
        <funcdef>
            &lt;<function>button</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>action</parameter> (required) </attribute>
          <attribute>
            <parameter>value</parameter> (required) </attribute>
          <attribute>
            <parameter>style</parameter> (optional) </attribute>
          <attribute>
            <parameter>active</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-active</parameter> (optional) </attribute>
          <attribute>
            <parameter>child-window-options</parameter> (optional) </attribute>
          <attribute>
            <parameter>browser-current</parameter> (optional) </attribute>
          <attribute>
            <parameter>browser-filter</parameter> (optional) </attribute>
          <attribute>
            <parameter>browser-list</parameter> (optional) </attribute>
          <attribute>
            <parameter>browser-mode</parameter> (optional) </attribute>
          <attribute>
            <parameter>browser-type</parameter> (optional) </attribute>
          <attribute>
            <parameter>browser-xfer</parameter> (optional) </attribute>
          <attribute>
            <parameter>selector</parameter> (optional) </attribute>
          <attribute>
            <parameter>format</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_button">
    <title>Description</title>
    <para>Scriptable version of Submit Button of the HTML form. Depending of
&#39;action&#39; attribute it may have variants. In some of these variants the button will not have a submit function, as in select and browse buttons.  In these cases the button will use client JavaScript to pop up new windows or for setting values in other windows.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_button">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
      <title>action</title>
      <para>This specifies the button subclass to use.</para>
   <table>
        <title>Allowed values of the &#39;action&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>simple</entry>
       <entry>
                <para>is a simple submit button, no special functions
				</para>
       </entry>
      </row>
      <row>
              <entry>submit</entry>
       <entry>
                <para>an alias of &#39;simple&#39; button, obsolete
				</para>
       </entry>
      </row>
      <row>
              <entry>delete</entry>
       <entry>
                <para>a button for deleting a row in a data-set or data-grid control. This is represented as a submit button with a special on-post script. The delete function is performed based on table, key attributes. (check implementation!!)
				</para>
       </entry>
      </row>
      <row>
              <entry>browse</entry>
       <entry>
                <para>Button that opens pup-up window using client-side javascript (browse-button).
This control allows the designer to place some part of a form&#39;s input into a pop-up window. When the HTML page is rendered, this control puts a button and associated client-side javascript into the resulting page so clicking the button opens a child window.  </para>
       </entry>
      </row>
      <row>
              <entry>return</entry>
       <entry>
                <para>
This is to be used on a page invoked for selecting from a browse button.  Specifies that the value of the fields designated by the field children are to be asigned to the corresponding fields of the invoking page.
				</para>
       </entry>
      </row>
      <row>
              <entry>logout</entry>
       <entry>
                <para> This will terminate the current session when clicked.  Can only occur inside the login control.
				</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Text of the label of the button.</para>
  </formalpara>
  <formalpara>
      <title>style</title>
      <para>A style of button, affects appearance.</para>
   <table>
        <title>Allowed values of the &#39;style&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>submit</entry>
       <entry>
                <para>This is a default style used, no special handling.
The button will be rendered as a usual submit button.
				</para>
       </entry>
      </row>
      <row>
              <entry>url</entry>
       <entry>
                <para>The button will be rendered as a link, furthermore client side JavaScript code will be produced to act as submit button.	</para>
       </entry>
      </row>
      <row>
              <entry>image</entry>
       <entry>
                <para>The button will be rendered as an image on the browser under link button. In that case value of button control must be link to the image file.
				</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>active = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A data bound value to enable or disable the button. The default is &#39;1&#39; meaning &#39;enable&#39;.</para>
  </formalpara>
  <formalpara>
   <title>initial-active = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A data bound value to enable or disable the button. The default is &#39;1&#39; meaning &#39;enable&#39;.
Unlike &#39;active&#39; attribute, this one is effective only when the page is displayed in the first time, not after user posts data back to the page.</para>
  </formalpara>
  <formalpara>
      <title>child-window-options</title>
      <para>Options for oppening a child pop-up window.This can be used only in conjuction with  action browse.</para>
  </formalpara>
  <formalpara>
      <title>browser-current</title>
      <para>Current directory of browsing. Can be used only with browse button for WebDAV or File system resources.</para>
  </formalpara>
  <formalpara>
      <title>browser-filter</title>
      <para>Filter expression(s) for browsing. (see above)</para>
  </formalpara>
  <formalpara>
      <title>browser-list</title>
      <para>Type of browser list, 0 - short, 1 - long</para>
  </formalpara>
  <formalpara>
      <title>browser-mode</title>
      <para>COL, RES or STANDALONE , for a file system or DAV browse button, this specifies whether to return an path name or internal ID.
</para>
  </formalpara>
  <formalpara>
      <title>browser-type</title>
      <para>This designates the type of browser: dav or OS (filesystem).</para>
  </formalpara>
  <formalpara>
      <title>browser-xfer</title>
      <para>For a browse button, this is the   means  of transferring the data between windows, DOM is default. No other options in current implementation.</para>
  </formalpara>
  <formalpara>
      <title>selector</title>
      <para>For a browse button this is the  URL that will be loaded into the pop up window.</para>
  </formalpara>
  <formalpara>
   <title>format = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A sprintf format string for printing the value</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_button">
    <title>Declaration of type vspx_button</title>
    <para>
 Button class, encapsulate all controls originating a event
</para>
    <screen>
create type vspx_button under vspx_field as
(
  bt_pressed int default 0,
  bt_style  varchar default &#39;submit&#39;,
  bt_close_img varchar,
  bt_open_img varchar,
  bt_url varchar default &#39;&#39;,
  bt_l_pars varchar default &#39;&#39;,
  bt_text varchar default &#39;&#39;,
  bt_anchor int default 0
)  temporary self as ref
overriding method vc_render () returns any,
overriding method vc_xrender () returns any,
overriding method vc_set_model () returns any,
constructor method vspx_button (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_button">
    <title>Examples</title>
   <example id="vc_ex_button__0">
      <title>
  Buton shown as an image
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: button__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The button of the form will be shown as a picture plus.gif. Attributes whose names start with &#39;xhtml_&#39; are
placed into the resulting HTML with no changes.

</para>
      <screen>
&lt;v:page name=&quot;button__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:button&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:text name=&quot;txt1&quot; default=&quot;&quot;/&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; style=&quot;image&quot; xhtml_alt=&quot;A test button&quot; value=&quot;--&#39;plus.gif&#39;&quot; /&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
   <example id="vc_ex_button__1">
      <title>
  Simple &#39;Add-Number&#39; example
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: button__1.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form accepts two numbers and calculates their sum.

</para>
      <screen>
&lt;v:page name=&quot;button__1&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:button&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;f1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
	&lt;v:label name=&quot;l1&quot; value=&quot;--0&quot; format=&quot;%.2f&quot; /&gt;&lt;br/&gt;
        &lt;v:text name=&quot;t1&quot; default=&quot;0&quot;/&gt;
        &lt;v:text name=&quot;t2&quot; default=&quot;0&quot;/&gt;
        &lt;v:button name=&quot;b1&quot; action=&quot;simple&quot; value=&quot;Add&quot; &gt;
	&lt;v:on-post&gt;
	 self.l1.ufl_value := atof (self.t1.ufl_value) + atof (self.t2.ufl_value);
	&lt;/v:on-post&gt;
	&lt;/v:button&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
   <example id="vc_ex_button__2">
      <title>
  Simple &#39;Browse File&#39; dialog
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: button__2.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form allows to select a file from server&#39;s file system

&lt;html&gt;
&lt;body&gt;
</para>
      <screen>
&lt;v:page name=&quot;browse__2&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;v:form name=&quot;f1&quot; type=&quot;simple&quot; method=&quot;POST&quot;&gt;
      &lt;v:text name=&quot;floc&quot; value=&quot;&quot; xhtml_size=&quot;60%&quot; /&gt;
      &lt;v:button action=&#39;browse&#39; name=&quot;cmb&quot; selector=&quot;browser/dav_browser.vsp&quot;
		child-window-options=&quot;resizable=yes, status=no, menubar=no, scrollbars=no, width=640, height=400&quot;
		value=&quot;Browse&quot;
		browser-type=&quot;os&quot;
		browser-mode=&quot;RES&quot;
		browser-xfer=&quot;DOM&quot;
		browser-list=&quot;1&quot;
		browser-current=&quot;1&quot;
		browser-filter=&quot;*&quot;&gt;
        &lt;v:field name=&quot;floc&quot; /&gt;
      &lt;/v:button&gt;
  &lt;/v:form&gt;
&lt;/v:page&gt;
&lt;/body&gt;
&lt;/html&gt;
</screen>
   </example>
   <example id="vc_ex_button__3">
      <title>
  Simple browse button example
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: button__3.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form allows to select a two values from a different page

&lt;html&gt;
&lt;body&gt;
</para>
      <screen>
&lt;v:page name=&quot;button__3&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;v:form name=&quot;frm&quot; type=&quot;simple&quot; method=&quot;POST&quot;&gt;
      &lt;v:text name=&quot;fld1&quot; value=&quot;&quot; /&gt;
      &lt;v:text name=&quot;fld2&quot; value=&quot;&quot; /&gt;
      &lt;v:button action=&#39;browse&#39; name=&quot;br1&quot; selector=&quot;button__4.vspx&quot;
		child-window-options=&quot;scrollbars=yes, menubar=no, height=630, width=600&quot;
		value=&quot;Browse&quot;&gt;
        &lt;v:field name=&quot;fld1&quot; /&gt;
        &lt;v:field name=&quot;fld2&quot; /&gt;
      &lt;/v:button&gt;
  &lt;/v:form&gt;
&lt;/v:page&gt;
&lt;/body&gt;
&lt;/html&gt;
</screen>
   </example>
   <example id="vc_ex_button__4">
      <title>
  Simple select button example
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: button__4.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form returns back to caller form two walues from a text box and select list

&lt;html&gt;
&lt;body&gt;
</para>
      <screen>
&lt;v:page name=&quot;button__4&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;v:form name=&quot;f1&quot; type=&quot;simple&quot; method=&quot;POST&quot;&gt;
     &lt;v:text name=&quot;sl1&quot; value=&quot;Test&quot; /&gt;
     &lt;v:select-list name=&quot;sl2&quot;&gt;
       &lt;v:item name=&quot;*default*&quot; value=&quot;0&quot; /&gt;
       &lt;v:item name=&quot;FIRST&quot; 	value=&quot;1&quot; /&gt;
       &lt;v:item name=&quot;SECOND&quot; 	value=&quot;2&quot; /&gt;
     &lt;/v:select-list&gt;
	&lt;v:button name=&quot;select1&quot; action=&quot;return&quot; value=&quot;Select&quot;&gt;
	  &lt;v:field name=&quot;fld1&quot; ref=&quot;sl1&quot; /&gt;
	  &lt;v:field name=&quot;fld2&quot; ref=&quot;sl2&quot; /&gt;
	&lt;/v:button&gt;
 &lt;/v:form&gt;
&lt;/v:page&gt;
&lt;/body&gt;
&lt;/html&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/form.vspx">VX-S-2</ulink>
   </para>
   <para>
      <ulink url="/tutorial/web/vx_s_7/products.vspx">VX-S-7</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_calendar">
  <refmeta>
    <refentrytitle>calendar</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>calendar</refname>
    <refpurpose>Databound calendar control.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_calendar">
    <funcprototype id="vc_proto_calendar">
        <funcdef>
            &lt;<function>calendar</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-date</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_calendar">
    <title>Description</title>
    <para>This is the generic calendar control.</para>
  </refsect1>
  <refsect1 id="vc_attrs_calendar">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>initial-date = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Expression which returns a date for setting initially the current date of the calendar.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_calendar">
    <title>Declaration of type vspx_calendar</title>
    <para>
</para>
    <screen>
create type vspx_calendar under vspx_control as
(
  cal_date date,
  cal_meta any,
  cal_selected datetime,
  cal_current_row vspx_row_template
) temporary self as ref
method vc_get_date_array () returns any,
overriding method vc_view_state (stream any, n int) returns any,
overriding method vc_set_view_state (e vspx_event) returns any,
constructor method vspx_calendar (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_calendar">
    <title>Examples</title>
   <example id="vc_ex_calendar__0">
      <title>
  A calendar
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: calendar__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This demo will show a calendar allowing to list dates by months

</para>
      <screen>
&lt;v:page name=&quot;pagecal1&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
&lt;body&gt;
&lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; method=&quot;POST&quot; &gt;
    &lt;v:calendar name=&quot;cal1&quot; initial-date=&quot;--now()&quot;&gt;
      &lt;v:template type=&quot;simple&quot; name=&quot;chead1&quot; name-to-remove=&quot;table&quot; set-to-remove=&quot;bottom&quot;&gt;
      &lt;table border=&quot;0&quot; cellpadding=&quot;0&quot; cellspacing=&quot;0&quot;&gt;
        &lt;tr&gt;
         &lt;td align=&quot;center&quot;&gt;
	  &lt;v:button name=&quot;pmon&quot; value=&quot;&lt;&quot; action=&quot;simple&quot; style=&quot;url&quot;&gt;
	    &lt;v:on-post&gt;
	    self.cal1.cal_date := dateadd (&#39;month&#39;, -1, self.cal1.cal_date);
	    self.cal1.vc_data_bind (e);
	    &lt;/v:on-post&gt;
	  &lt;/v:button&gt;
	 &lt;/td&gt;
 	 &lt;td colspan=&quot;5&quot; align=&quot;center&quot;&gt;
           &lt;?V monthname((control.vc_parent as vspx_calendar).cal_date) ?&gt;
	   &lt;?V year((control.vc_parent as vspx_calendar).cal_date) ?&gt;
	 &lt;/td&gt;
         &lt;td align=&quot;center&quot;&gt;
	  &lt;v:button name=&quot;nmon&quot; value=&quot;&gt;&quot; action=&quot;simple&quot; style=&quot;url&quot;&gt;
	    &lt;v:on-post&gt;
	    self.cal1.cal_date := dateadd (&#39;month&#39;, 1, self.cal1.cal_date);
	    self.cal1.vc_data_bind (e);
	    &lt;/v:on-post&gt;
	  &lt;/v:button&gt;
	 &lt;/td&gt;
	 &lt;/tr&gt;
        &lt;tr&gt;&lt;td&gt;Sun&lt;/td&gt;&lt;td&gt;|Mon&lt;/td&gt;&lt;td&gt;|Tue&lt;/td&gt;&lt;td&gt;|Wed&lt;/td&gt;&lt;td&gt;|Thu&lt;/td&gt;&lt;td&gt;|Fri&lt;/td&gt;&lt;td&gt;|Sat&lt;/td&gt;&lt;/tr&gt;
      &lt;/table&gt;
      &lt;/v:template&gt;
      &lt;v:template type=&quot;repeat&quot; name=&quot;cbody1&quot; name-to-remove=&quot;&quot; set-to-remove=&quot;&quot;&gt;
      &lt;v:template type=&quot;browse&quot; name=&quot;crow1&quot; name-to-remove=&quot;table&quot; set-to-remove=&quot;both&quot;&gt;
      &lt;table&gt;
      &lt;tr&gt;
       &lt;td align=&quot;center&quot;&gt;&lt;v:button style=&quot;url&quot; action=&quot;simple&quot; name=&quot;b1&quot; value=&quot;--cal_icell(control, 0)&quot; /&gt;&lt;/td&gt;
       &lt;td align=&quot;center&quot;&gt;&lt;v:button style=&quot;url&quot; action=&quot;simple&quot; name=&quot;b2&quot; value=&quot;--cal_icell(control, 1)&quot; /&gt;&lt;/td&gt;
       &lt;td align=&quot;center&quot;&gt;&lt;v:button style=&quot;url&quot; action=&quot;simple&quot; name=&quot;b3&quot; value=&quot;--cal_icell(control, 2)&quot; /&gt;&lt;/td&gt;
       &lt;td align=&quot;center&quot;&gt;&lt;v:button style=&quot;url&quot; action=&quot;simple&quot; name=&quot;b4&quot; value=&quot;--cal_icell(control, 3)&quot; /&gt;&lt;/td&gt;
       &lt;td align=&quot;center&quot;&gt;&lt;v:button style=&quot;url&quot; action=&quot;simple&quot; name=&quot;b5&quot; value=&quot;--cal_icell(control, 4)&quot; /&gt;&lt;/td&gt;
       &lt;td align=&quot;center&quot;&gt;&lt;v:button style=&quot;url&quot; action=&quot;simple&quot; name=&quot;b6&quot; value=&quot;--cal_icell(control, 5)&quot; /&gt;&lt;/td&gt;
       &lt;td align=&quot;center&quot;&gt;&lt;v:button style=&quot;url&quot; action=&quot;simple&quot; name=&quot;b7&quot; value=&quot;--cal_icell(control, 6)&quot; /&gt;&lt;/td&gt;
      &lt;/tr&gt;
      &lt;/table&gt;
      &lt;/v:template&gt;
      &lt;/v:template&gt;
      &lt;v:template type=&quot;simple&quot; name=&quot;cbott1&quot; name-to-remove=&quot;table&quot; set-to-remove=&quot;top&quot;&gt;
      &lt;table&gt;
      &lt;/table&gt;
      &lt;/v:template&gt;
    &lt;/v:calendar&gt;
&lt;/v:form&gt;
&lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_check_box">
  <refmeta>
    <refentrytitle>check-box</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>check-box</refname>
    <refpurpose>Scriptable check-box.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_check_box">
    <funcprototype id="vc_proto_check_box">
        <funcdef>
            &lt;<function>check-box</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>error-glyph</parameter> (optional) </attribute>
          <attribute>
            <parameter>auto-submit</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>group-name</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-checked</parameter> (optional) </attribute>
          <attribute>
            <parameter>is-boolean</parameter> (optional) </attribute>
          <attribute>
            <parameter>true-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>false-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_check_box">
    <title>Description</title>
    <para>is a represantation of HTML check box. Scriptable, databindable.</para>
  </refsect1>
  <refsect1 id="vc_attrs_check_box">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
      <title>error-glyph</title>
      <para>The character to be displayed near the resulting HTML input element if the test of v:validator of the element detects an error in the current value of the element.</para>
  </formalpara>
  <formalpara>
      <title>auto-submit</title>
      <para>Flag to auto submit the parent form if value of the control is changed.</para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
   <title>group-name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>
When several check boxes are grouped, this is the group name.
This will be submitted instead of the control name on post.
			     </para>
  </formalpara>
  <formalpara>
   <title>initial-checked = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Specifies whether the control is initially checked.</para>
  </formalpara>
  <formalpara>
      <title>is-boolean</title>
      <para>If this attribute is set to &#39;1&#39; then the check-box is forced to ignore its &#39;initial-checked&#39; status and work using the data-bound value as the only criterion for enabling or disabling its &#39;checked&#39; property. This mode is convenient for editing two-state data values. Before render, the control will check if the ufl_value is equal to &#39;true-value&#39; or &#39;false-value&#39;, and it is displayed as checked if the ufl_value is equal to &#39;true-value&#39; (or it is not equal to any of these two but is not a logical &#39;false&#39;). On post, a new status of the checkbox is inspected, and the ufl_value is set to &#39;true-value&#39; if it is checked or &#39;false-value&#39; otherwise.
The default value of this attribute is &#39;0&#39; meaning that there is no system-level relation between the &#39;checked&#39; status and the &#39;value&#39;.
When the form with the check-box submits data, the submitted value of the attribute depends on its &#39;is-boolean&#39; property. If it&#39;s &#39;0&#39; then the result of cast (control.ufl_value as varchar) is submitted; otherwise a string &#39;1&#39; is submitted.
</para>
  </formalpara>
  <formalpara>
   <title>true-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This attribute should be used if and only if &#39;is-boolean&#39; attribute is set to &#39;1&#39;.
The calculated value of this attribute is saved in ufl_true_value field of the control and is used to represent a logical &#39;true&#39; for the control. The checkbox is displayed as checked if the bound value is equal to the ufl_true_value. If the checked checkbox is submitted then the bound value of the control is set to the ufl_true_value.
</para>
  </formalpara>
  <formalpara>
   <title>false-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This attribute should be used if and only if &#39;is-boolean&#39; attribute is set to &#39;1&#39;.
The calculated value of this attribute is saved in ufl_false_value field of the control and is used to represent a logical &#39;false&#39; for the control. The checkbox is displayed as not checked if the bound value is equal to the ufl_valuse_value. If no checked checkbox is submitted by a form then the bound value of the control is set to ufl_false_value.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_check_box">
    <title>Declaration of type vspx_check_box</title>
    <para>
</para>
    <screen>
create type vspx_check_box under vspx_field
temporary self as ref
constructor method vspx_check_box (name varchar, parent vspx_control),
overriding method vc_render () returns any,
overriding method vc_xrender () returns any,
overriding method vc_view_state (stream any, n int) returns any,
overriding method vc_set_view_state (e vspx_event) returns any,
overriding method vc_set_model () returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_check_box">
    <title>Examples</title>
   <example id="vc_ex_check_box__0">
      <title>
  Entry form with a checkbox
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: check_box__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


Depending on the state of the checkbox, the submitted value is either &#39;checked&#39; or &#39;unchecked&#39;.

</para>
      <screen>
&lt;v:page name=&quot;check_box__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:check-box&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:check-box name=&quot;cb1&quot; initial-checked=&quot;0&quot; value=&quot;-- case control.ufl_selected when 1 then &#39;checked&#39; else &#39;unchecked&#39; end&quot;  /&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; value=&quot;OK&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/check_box.vspx">VX-S-2</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_code_file">
  <refmeta>
    <refentrytitle>code-file</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>code-file</refname>
    <refpurpose>Code-behind file containing SQL script.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_code_file">
    <funcprototype id="vc_proto_code_file">
        <funcdef>
            &lt;<function>code-file</function> <attribute>
            <parameter>url</parameter> (required) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_code_file">
    <title>Description</title>
    <para>This element is used to load an external SQL
	  script after page class compilation and before page execution.
	  This script may contain page subclass or custom control definitions.
	  In this way SQL code can be separated from VSPX markup, or in other words
	  to separate page design from application logic.
      </para>
  </refsect1>
  <refsect1 id="vc_attrs_code_file">
    <title>Attributes</title>
  <formalpara>
      <title>url</title>
      <para>URL of file to be loaded after VSPX page compilation.
		If relative then the base is the page where the control resides
		(i.e. same URL resolution rules applied as for includes).
          </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_ex_code_file">
    <title>Examples</title>
   <example id="vc_ex_code_file__0">
      <title>
  Code-behind SQL script
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: code_file__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The script of a button&#39;s post event is in separate SQL file.

The code_file__0.sql contents:
drop type my_page_subclass
;

create type my_page_subclass under DB.dba.page__vspx_code__file____0_vspx
temporary self as ref
overriding method vc_post_b1 (control vspx_button, e vspx_event) returns any,
method button_change (control vspx_button) returns any
;

create method vc_post_b1 (inout control vspx_button, inout e vspx_event) for my_page_subclass
 {
   if (not control.vc_focus) return;
   self.button_change (control);
   return;
 }
;

create method button_change (inout control vspx_button) for my_page_subclass
 {
   self.var1 := self.var1 + 1;
   control.ufl_value := &#39;Activated&#39;;
 }
;


</para>
      <screen>
&lt;v:page name=&quot;page1&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot; page-subclass=&quot;my_page_subclass&quot;&gt;
  &lt;html&gt;
    &lt;body&gt;
      &lt;v:code-file  url=&quot;code_file__0.sql&quot;/&gt;
      &lt;v:variable name=&quot;var1&quot; type=&quot;int&quot; default=&quot;0&quot; param-name=&quot;id&quot; persist=&quot;pagestate&quot; /&gt;
      &lt;v:form type=&quot;simple&quot; name=&quot;f1&quot;&gt;
	&lt;v:label name=&quot;l1&quot; value=&quot;--self.var1&quot; format=&quot;%d&quot; /&gt;
	&lt;v:button action=&quot;simple&quot; name=&quot;b1&quot; value=&quot;Submit&quot; /&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_column">
  <refmeta>
    <refentrytitle>column</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>column</refname>
    <refpurpose>A column marker.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_column">
    <funcprototype id="vc_proto_column">
        <funcdef>
            &lt;<function>column</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>label</parameter> (optional) </attribute>
          <attribute>
            <parameter>input-format</parameter> (optional) </attribute>
          <attribute>
            <parameter>output-format</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_column">
    <title>Description</title>
    <para>
A column marker for use in v:data-set, v:data-grid and v:data-source.
This element should exist for each selected column of the SQL expression of the data set.
If this is specified under data-set, data-source or data-grid controls, this must be the exact same columns as in SQL statement to be evaluated. If those element is omitted in data-set or data-grid, the columns will be extracted from compilation of the SQL statement.
However, this  will always be required for calls of stored procedures that return resultsets and for the data-source control.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_column">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of column
	  </para>
  </formalpara>
  <formalpara>
   <title>label = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Alternate text which could be used to display in column headings.
	  </para>
  </formalpara>
  <formalpara>
      <title>input-format</title>
      <para>A sprintf format string for printing the input value
	  </para>
  </formalpara>
  <formalpara>
      <title>output-format</title>
      <para>A sprintf format string for printing the output value
	  </para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_data_grid">
  <refmeta>
    <refentrytitle>data-grid</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>data-grid</refname>
    <refpurpose>Scrollable databound multi-row control.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_data_grid">
    <funcprototype id="vc_proto_data_grid">
        <funcdef>
            &lt;<function>data-grid</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>data</parameter> (optional) </attribute>
          <attribute>
            <parameter>meta</parameter> (optional) </attribute>
          <attribute>
            <parameter>nrows</parameter> (optional) </attribute>
          <attribute>
            <parameter>sql</parameter> (required) </attribute>
          <attribute>
            <parameter>scrollable</parameter> (optional) </attribute>
          <attribute>
            <parameter>cursor-type</parameter> (optional) </attribute>
          <attribute>
            <parameter>edit</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_data_grid">
    <title>Description</title>
    <para>
<para>This is the generic multi-row database view control. It is used to show repeating data, as from tables
or procedure views. Allows scrolling (paging) editing the data; adding a row or removal of existing rows.
Usually this control generates a PL scrollable cursor of type as specified. The number of rows shown are
configurable via nrows attribute. Note also that column children elements are optional; they can be omitted
so then VSPX engine will compute them from specified SQL statement in &#39;sql&#39; attribute.</para>
<para>Specific to this control is to have row-template and frame-template, these are to present repeating and non-repeating groups of children elements. The frame-template will usually
have a &#39;rowset&#39; placeholder to designate the place where repeating group (row-template) will be instantiated. The control expects to find child controls with specific names. for scrolling buttons - [data-grid name]&#39;_prev&#39; and [data-grid name]&#39;_next&#39;; for editing buttons - [data-grid name]&#39;_edit&#39; and [data-grid name]&#39;_delete&#39;.</para>
	</para>
  </refsect1>
  <refsect1 id="vc_attrs_data_grid">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
    <formalpara>
   <title>data = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Expression which returns an array of rowset data, this is an alternative to specifying an SQL expression. The result then will be used to instantiate
the repeating group. An example of such data is the result returned by &#39;exec&#39; function:</para>
<programlisting>
(
  (&quot;ALFKI&quot; &quot;Alfreds Futterkiste&quot; &quot;030-0074321&quot; )
  (&quot;ANATR&quot; &quot;Ana Trujillo Emparedados y helados&quot; &quot;(5) 555-4729&quot; )
)
</programlisting>
</formalpara>
    <formalpara>
   <title>meta = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This works with combination of data attribute, this expression must return an array of ro metadata. So when this is specified it needs to be an expression returning meta-data for columns. In practice this is the same as 1st element of metadata returned by &#39;exec()&#39; :</para>

<programlisting>
(
  (&quot;CustomerID&quot; 182 0 5 0 1 1 &quot;Demo&quot; &quot;CustomerID&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
  (&quot;CompanyName&quot; 182 0 40 1 1 1 &quot;Demo&quot; &quot;CompanyName&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
  (&quot;Phone&quot; 182 0 24 1 1 1 &quot;Demo&quot; &quot;Phone&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
)
</programlisting>

<para>
for details of metadata see &#39;exec()&#39; function description.</para>

</formalpara>
  <formalpara>
   <title>nrows = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The maximum number of replicas of the row template to be made for rows selected.
This is like the rowset size for a scrollable cursor.</para>
  </formalpara>
  <formalpara>
   <title>sql = <link linkend="vc_type_SqlCode">SqlCode</link>
   </title>
      <para>The select statement that gets the data.
Parameters to the statement MUST be specified as SQL identifiers prefixed with a colon (named parameter).
The values are given in the control&#39;s vspx:param children.  These specify the parameter name and a data bound expression for the value.
</para>
  </formalpara>
  <formalpara>
      <title>scrollable</title>
      <para>The setting controls whether next and previous page buttons are presented.  This can be on even if the cursor is not scrollable as such.</para>
  </formalpara>
  <formalpara>
      <title>cursor-type</title>
   <table>
        <title>Allowed values of the &#39;cursor-type&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>static</entry>
       <entry>
                <para>A static cursor is used.</para>
       </entry>
      </row>
      <row>
              <entry>dynamic</entry>
       <entry>
                <para>A dynamic cursor is used.</para>
       </entry>
      </row>
      <row>
              <entry>keyset</entry>
       <entry>
                <para>A keyset cursor is used.</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>edit = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Flags whether editing features are enabled on data grid control</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_data_grid">
    <title>Declaration of type vspx_data_grid</title>
    <para>
 Scrollable, Multi-Row data grid Class
</para>
    <screen>
create type vspx_data_grid under vspx_form
as (
    dg_nrows int default -1,    -- how many rows to show on single page
    dg_scrollable int default 0,  -- scroll on form is enabled
    dg_editable int default 1,          -- disable edit/add on whole grid
    dg_row_meta any,      -- metadata
    dg_row_data any,      -- the data for procedure binding
    dg_current_row vspx_row_template,   -- current row template
    dg_rowno_edit int default null, -- last edited row in result set, to re-display the edit box on error
    dg_rows_fetched int default 0,  -- these are to keep state for scrolling
    dg_prev_bookmark any default null,
    dg_last_bookmark any default null
   )  temporary self as ref
  method vc_templates_clean () returns any,
  constructor method vspx_data_grid (name varchar, parent vspx_control),
  overriding method vc_set_view_state (e vspx_event) returns any,
  overriding method vc_view_state (stream any, n int) returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_data_grid">
    <title>Examples</title>
   <example id="vc_ex_data_grid__0">
      <title>
  Editable multi-row data grid based on data-grid control
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: data_grid__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will show a list of customers from the Northwind demo database.
Allows editing, addtion and removal of existing records.

</para>
      <screen>
&lt;v:page name=&quot;data_grid__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
  &lt;body&gt;
      &lt;v:data-grid name=&quot;dg&quot; nrows=&quot;5&quot; sql=&quot;select CustomerID, CompanyName, Phone from Demo.demo.Customers where CustomerId like :mask&quot; cursor-type=&quot;keyset&quot; edit=&quot;1&quot;&gt;
        &lt;v:param name=&quot;mask&quot; value=&quot;&#39;%&#39;&quot;/&gt;
        &lt;v:template name=&quot;t1&quot; type=&quot;frame&quot;&gt;
          &lt;div&gt;
            &lt;div&gt;
              Action
                &lt;v:label name=&quot;l1&quot; value=&quot;--(control.vc_parent as vspx_data_grid).dg_row_meta[0]&quot;/&gt;
              &lt;v:label name=&quot;l2&quot; value=&quot;--(control.vc_parent as vspx_data_grid).dg_row_meta[1]&quot;/&gt;
              &lt;v:label name=&quot;l3&quot; value=&quot;--(control.vc_parent as vspx_data_grid).dg_row_meta[2]&quot;/&gt;
            &lt;/div&gt;
            &lt;v:rowset/&gt;
            &lt;v:form type=&quot;add&quot;/&gt;
            &lt;div&gt;
              &lt;v:button name=&quot;dg_prev&quot; action=&quot;simple&quot; value=&quot;&amp;lt;&amp;lt;&quot;/&gt;
              &lt;v:button name=&quot;dg_next&quot; action=&quot;simple&quot; value=&quot;&amp;gt;&amp;gt;&quot;/&gt;
            &lt;/div&gt;
          &lt;/div&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t2&quot; type=&quot;row&quot;&gt;
          &lt;div&gt;
            &lt;v:button name=&quot;dg_edit&quot; action=&quot;simple&quot; value=&quot;Edit&quot;/&gt;
            &lt;v:button name=&quot;dg_delete&quot; action=&quot;simple&quot; value=&quot;Delete&quot;&gt;
              &lt;v:on-post&gt;
              delete from Demo.demo.Customers where CustomerID = self.dg.dg_current_row.te_rowset[0];
              self.dg.vc_data_bind (e);
                &lt;/v:on-post&gt;
            &lt;/v:button&gt;
            &lt;v:label name=&quot;label1&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[0]&quot;/&gt;
            &lt;v:label name=&quot;label2&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[1]&quot;/&gt;
            &lt;v:label name=&quot;label3&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[2]&quot;/&gt;
          &lt;/div&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t3&quot; type=&quot;if-not-exists&quot;&gt;
          &lt;div&gt;No rows selected&lt;/div&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t4&quot; type=&quot;edit&quot;&gt;
          &lt;v:form name=&quot;u1&quot; type=&quot;update&quot; table=&quot;Demo.demo.Customers&quot; if-not-exists=&quot;insert&quot;&gt;
            &lt;v:key column=&quot;CustomerID&quot; value=&quot;--self.dg.dg_current_row.te_rowset[0]&quot; default=&quot;null&quot;/&gt;
            &lt;v:template type=&quot;if-exists&quot; name=&quot;t5&quot;&gt;
              &lt;div&gt;
                &lt;v:button name=&quot;b1&quot; action=&quot;submit&quot; value=&quot;Update&quot;/&gt;
                &lt;input type=&quot;submit&quot; name=&quot;b2&quot; value=&quot;Cancel&quot;/&gt;
                &lt;v:text name=&quot;c_id1&quot; column=&quot;CustomerID&quot;/&gt;
                &lt;v:text name=&quot;c_name1&quot; column=&quot;CompanyName&quot;/&gt;
                &lt;v:text name=&quot;c_phone1&quot; column=&quot;Phone&quot;/&gt;
              &lt;/div&gt;
            &lt;/v:template&gt;
          &lt;/v:form&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t6&quot; type=&quot;add&quot;&gt;
          &lt;v:form type=&quot;update&quot; name=&quot;a1&quot; table=&quot;Demo.demo.Customers&quot; if-not-exists=&quot;insert&quot;&gt;
            &lt;v:key column=&quot;CustomerID&quot; value=&quot;--&#39;&#39;&quot; default=&quot;null&quot;/&gt;
            &lt;v:template name=&quot;t7&quot; type=&quot;if-exists&quot;&gt;
              &lt;v:button name=&quot;b3&quot; action=&quot;submit&quot; value=&quot;Add&quot;/&gt;
              &lt;v:text name=&quot;c_id2&quot; column=&quot;CustomerID&quot;/&gt;
              &lt;v:text name=&quot;c_name2&quot; column=&quot;CompanyName&quot;/&gt;
              &lt;v:text name=&quot;c_phone2&quot; column=&quot;Phone&quot;/&gt;
            &lt;/v:template&gt;
          &lt;/v:form&gt;
        &lt;/v:template&gt;
      &lt;/v:data-grid&gt;
  &lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_data_list">
  <refmeta>
    <refentrytitle>data-list</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>data-list</refname>
    <refpurpose>Select list initialized from database table.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_data_list">
    <funcprototype id="vc_proto_data_list">
        <funcdef>
            &lt;<function>data-list</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>error-glyph</parameter> (optional) </attribute>
          <attribute>
            <parameter>auto-submit</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>table</parameter> (optional) </attribute>
          <attribute>
            <parameter>key-column</parameter> (optional) </attribute>
          <attribute>
            <parameter>value-column</parameter> (optional) </attribute>
          <attribute>
            <parameter>sql</parameter> (optional) </attribute>
          <attribute>
            <parameter>defvalue</parameter> (optional) </attribute>
          <attribute>
            <parameter>multiple</parameter> (optional) </attribute>
          <attribute>
            <parameter>list-document</parameter> (optional) </attribute>
          <attribute>
            <parameter>list-match</parameter> (optional) </attribute>
          <attribute>
            <parameter>list-key-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>list-value-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_data_list">
    <title>Description</title>
    <para>This control is used to make a select list, based on a SQL expression.
      Also instead of SQL expression only table name could be given, so then control will compose apropriate select statement.
      </para>
  </refsect1>
  <refsect1 id="vc_attrs_data_list">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>error-glyph</title>
      <para>The character to be displayed near the resulting HTML input element if the test of v:validator of the element detects an error in the current value of the element.</para>
  </formalpara>
  <formalpara>
      <title>auto-submit</title>
      <para>Flag to auto submit the parent form if value of the control is changed.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
      <title>table</title>
      <para>A table name for select statement.</para>
  </formalpara>
  <formalpara>
   <title>key-column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A key column name.</para>
  </formalpara>
  <formalpara>
   <title>value-column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A value column name.</para>
  </formalpara>
  <formalpara>
   <title>sql = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An alterantive of &#39;table&#39; attribute, when this attribute
	    is specified it must contains a valid select statement. The selection list
	    will be instantiated using a cursor as this expression is defined.
	  </para>
  </formalpara>
  <formalpara>
   <title>defvalue = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A default value for the control.</para>
  </formalpara>
  <formalpara>
      <title>multiple</title>
      <para>Used to desigante a multiple selection list box.
	    In this case the control&#39;s value will be an array of key data of selected items.
	  </para>
  </formalpara>
  <formalpara>
   <title>list-document = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to obtain all or some of items of the select-list from an XML document. If this attribute is specified then the value of the calculated attribute should be an XML entity and this entity will be saved in vsl_list_document field of the control; values of &#39;list-match&#39;, &#39;list-key-path&#39; and &#39;list-value-path&#39; arguments should specify XQuery expressions that should be used to retrieve keys and displayable values of items.
All selection items composed from the value of &#39;list-document&#39; will be listed before all items from &#39;table&#39; or &#39;sql&#39;, if both methods of data retrieval are used.
</para>
  </formalpara>
  <formalpara>
   <title>list-match = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to calculate a string value that is an XQuery expression. The text of this expression will be saved in &#39;vsl_list_match&#39; member of the control. This expression will be used during data binding to get array of displayable items from the value of &#39;list-document&#39;. The expression should return a node-set using &#39;list-document&#39; entity as a context mode; every item of the node-set will be converted into list item via &#39;list-key-path&#39; and &#39;list-value-path&#39; expressions.
</para>
  </formalpara>
  <formalpara>
   <title>list-key-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to specify the XQuery expression that calculates key value of a list item, using a result of &#39;list-match&#39; as a context node. The text of the expression will be saved in &#39;vsl_list_key_path&#39; member of the control.</para>
  </formalpara>
  <formalpara>
   <title>list-value-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to specify the XQuery expression that calculates a displayable value of a list item, using a result of &#39;list-match&#39; as a context node. The text of the expression will be saved in &#39;vsl_list_value_path&#39; member of the control.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_data_list">
    <title>Declaration of type vspx_data_list</title>
    <para>
</para>
    <screen>
create type vspx_data_list under vspx_select_list temporary self as ref
constructor method vspx_data_list (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_data_list">
    <title>Examples</title>
   <example id="vc_ex_data_list__0">
      <title>
  Select list based on table source
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: data_list__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will render in a form a select list containing the customers from Northwind demo database
with a option values their customer IDs.

</para>
      <screen>
&lt;v:page name=&quot;data_list__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
  &lt;body&gt;
      &lt;v:form name=&quot;f1&quot; type=&quot;simple&quot; method=&quot;POST&quot;&gt;
        &lt;v:data-list name=&quot;dl1&quot; table=&quot;Demo.demo.Customers&quot; key-column=&quot;CustomerID&quot; value-column=&quot;CompanyName&quot;/&gt;
      &lt;/v:form&gt;
  &lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
   <example id="vc_ex_data_list__1">
      <title>
  Select list based on SQL select statement
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: data_list__1.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will render in a form a select list containing the customers from Northwind demo database
with a option values their customer IDs.

</para>
      <screen>
&lt;v:page name=&quot;data_list__1&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
  &lt;body&gt;
      &lt;v:form name=&quot;f1&quot; type=&quot;simple&quot; method=&quot;POST&quot;&gt;
        &lt;v:data-list name=&quot;dl1&quot; sql=&quot;select * from Demo.demo.Customers&quot; key-column=&quot;CustomerID&quot; value-column=&quot;CompanyName&quot;/&gt;
      &lt;/v:form&gt;
  &lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_3/selectdb.vspx">VX-S-3</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_data_set">
  <refmeta>
    <refentrytitle>data-set</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>data-set</refname>
    <refpurpose>Scrollable, multi-row data bound grid.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_data_set">
    <funcprototype id="vc_proto_data_set">
        <funcdef>
            &lt;<function>data-set</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>sql</parameter> (optional) </attribute>
          <attribute>
            <parameter>data-source</parameter> (optional) </attribute>
          <attribute>
            <parameter>data</parameter> (optional) </attribute>
          <attribute>
            <parameter>meta</parameter> (optional) </attribute>
          <attribute>
            <parameter>nrows</parameter> (optional) </attribute>
          <attribute>
            <parameter>scrollable</parameter> (required) </attribute>
          <attribute>
            <parameter>cursor-type</parameter> (optional) </attribute>
          <attribute>
            <parameter>edit</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_data_set">
    <title>Description</title>
    <para>
      <para>A container for displaying and/or editing the content of a resultset.
This is the generic multi-row database view control. It is used to show repeating data, as from tables
or procedure views. Allows scrolling (paging) editing the data; adding a row or removal of existing rows.
Usually this control generates a PL scrollable cursor of type. The number of rows shown is
configurable via nrows attribute. Note also that column children elements are optional; they can be omitted
so then VSPX engine will compute them from the specified SQL statement in &#39;sql&#39; attribute.</para>

<para>This control has the same functionality as the data-grid control but has different syntax, better suited for editing via plugins for 3-d party WYSWYG HTML authoring tools (as Addobe GoLive and similar).</para>

<para>Specific to this control is to have several templates to present repeating and non-repeating groups of children elements. These templates are as follows: two generic templates to represent header and footer sections and one repeating template to enclose edit, add, not-exists and row (browse) sections. All of those templates are optional and their usage can be seen in examples.</para>

<para>Also following the convention for names of controls must be followed: for scrolling buttons - [data-set name]&#39;_prev&#39;, [data-set name]&#39;_next&#39;, [data-set name]&#39;_first&#39; and [data-set name]&#39;_last&#39;; for editing buttons - [data-set name]&#39;_edit&#39; and [data-set name]&#39;_delete&#39;.</para>
      </para>
  </refsect1>
  <refsect1 id="vc_attrs_data_set">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>sql = <link linkend="vc_type_SqlCode">SqlCode</link>
   </title>
      <para>The select statement that gets the data.
Parameters to the statement MUST be specified as SQL identifiers prefixed with a colon.
The values are given in the control&#39;s vspx:param children.  These specify the parameter name and a data bound expression for the value.
</para>
  </formalpara>
  <formalpara>
   <title>data-source = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A reference to a data-source, which wil lbe used to bind the data in data-set grid.
</para>
  </formalpara>
    <formalpara>
   <title>data = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>When this attribute is specified it must be an
expression returning array of arrays. This is an alternative to specifying an
SQL expression or data-source. The result then will be used to instantiate
the repeating group. An example of such data is the result returned by &#39;exec&#39; function:</para>
<programlisting>
(
  (&quot;ALFKI&quot; &quot;Alfreds Futterkiste&quot; &quot;030-0074321&quot; )
  (&quot;ANATR&quot; &quot;Ana Trujillo Emparedados y helados&quot; &quot;(5) 555-4729&quot; )
)
</programlisting>
</formalpara>
    <formalpara>
   <title>meta = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This attribute is used together with &#39;data&#39;, so when is
specified it needs to be an expression returning a meta-data for columns corresponding to the
these returned by &#39;data&#39; expression. In practice it&#39;s same as 1-st element of metadata returned by &#39;exec()&#39; :
</para>

<programlisting>
(
  (&quot;CustomerID&quot; 182 0 5 0 1 1 &quot;Demo&quot; &quot;CustomerID&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
  (&quot;CompanyName&quot; 182 0 40 1 1 1 &quot;Demo&quot; &quot;CompanyName&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
  (&quot;Phone&quot; 182 0 24 1 1 1 &quot;Demo&quot; &quot;Phone&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
)
</programlisting>

<para>for details of metadata see &#39;exec()&#39; function description.</para>
</formalpara>
  <formalpara>
   <title>nrows = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The maximum number of replicas of the row template to be made for rows selected.
It is like the rowset size for a scrollable cursor.
</para>
  </formalpara>
  <formalpara>
      <title>scrollable</title>
      <para>The setting controls whether next and previous page buttons are presented.  This can be on even if the cursor is not scrollable as such.</para>
  </formalpara>
  <formalpara>
      <title>cursor-type</title>
   <table>
        <title>Allowed values of the &#39;cursor-type&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>static</entry>
       <entry>
                <para>A static cursor is used.</para>
       </entry>
      </row>
      <row>
              <entry>dynamic</entry>
       <entry>
                <para>A dynamic cursor is used.</para>
       </entry>
      </row>
      <row>
              <entry>keyset</entry>
       <entry>
                <para>A keyset cursor is used.</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
      <title>edit</title>
      <para>Flags whether editing features are enabled on data grid control</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_data_set">
    <title>Declaration of type vspx_data_set</title>
    <para>
</para>
    <screen>
create type vspx_data_set under vspx_form
as (
    ds_nrows int,     -- how many rows to show on single page
    ds_scrollable int,      -- scroll on form is enabled
    ds_editable int default 1,          -- disable edit/add on whole grid
    ds_row_meta any,      -- metadata
    ds_row_data any,      -- data coming from a function, rowset
    ds_current_row vspx_row_template,   -- current row template
    ds_rowno_edit int default null, -- last edited row in result set, to re-display the edit box on error
    ds_rows_fetched int default 0,  -- how many rows are fetched for current page
    ds_rows_total int default 0,  -- how many data rows do we have in total (for vector)
    ds_rows_offs    int default 0,  -- this is the zero-based index of the first row of the current page in the whole list
    ds_rows_offs_saved int default 0,  -- this is the value of ds_rows_offs that was saved in the page state.
    ds_scrolled     int default 0,
    ds_has_next_page int default 0,	-- Flag if there are rows after the current page (so &#39;next page&#39; button should be enabled).
    ds_prev_bookmark any default null, -- Bookmark of the record that was at the beginning of previous retrieval of the page (bmk of the first row of the displayed page)
    ds_last_bookmark any default null, -- Bookmark of the record that was at the end of previous retrieval of the page (bmk of the last row of the displayed page)
    ds_rows_cache any,
    ds_data_source vspx_data_source default null
   )  temporary self as ref
  method vc_templates_clean () returns any,
  method vc_reset () returns any,
  method ds_column_offset (name varchar) returns any,
  method ds_iterate_rows (inx int) returns any,
  constructor method vspx_data_set (name varchar, parent vspx_control),
  overriding method vc_set_view_state (e vspx_event) returns any,
  overriding method vc_view_state (stream any, n int) returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_data_set">
    <title>Examples</title>
   <example id="vc_ex_data_set__0">
      <title>
  Editable multi-row data grid based on data-set control
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: data_set__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will show a list of customers from the Northwind demo database.
Allows editing, addtion and removal of existing records.

</para>
      <screen>
&lt;v:page name=&quot;data_set__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
  &lt;body&gt;
      &lt;v:data-set name=&quot;ds&quot; sql=&quot;select CustomerID, CompanyName, Phone from Demo.demo.Customers&quot; nrows=&quot;10&quot; scrollable=&quot;1&quot; cursor-type=&quot;keyset&quot;&gt;
        &lt;v:template name=&quot;t1&quot; type=&quot;simple&quot;&gt;
          &lt;div&gt;
            Action
            &lt;v:label name=&quot;l1&quot; value=&quot;CustomerID&quot; format=&quot;%s&quot; width=&quot;80&quot;/&gt;
            &lt;v:label name=&quot;l2&quot; value=&quot;CompanyName&quot; format=&quot;%s&quot; width=&quot;80&quot;/&gt;
            &lt;v:label name=&quot;l3&quot; value=&quot;Phone&quot; format=&quot;%s&quot; width=&quot;80&quot;/&gt;
          &lt;/div&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t2&quot; type=&quot;repeat&quot;&gt;
          &lt;v:template name=&quot;t7&quot; type=&quot;if-not-exists&quot;&gt;
            &lt;div&gt;No rows selected&lt;/div&gt;
          &lt;/v:template&gt;
          &lt;v:template name=&quot;t5&quot; type=&quot;edit&quot;&gt;
            &lt;v:form name=&quot;u1&quot; type=&quot;update&quot; table=&quot;Demo.demo.Customers&quot; if-not-exists=&quot;insert&quot;&gt;
              &lt;v:key column=&quot;CustomerID&quot; value=&quot;--self.ds.ds_current_row.te_rowset[0]&quot; default=&quot;null&quot;/&gt;
              &lt;v:template name=&quot;template6&quot; type=&quot;simple&quot;&gt;
                &lt;div&gt;
                  &lt;v:button name=&quot;upd_button&quot; action=&quot;submit&quot; value=&quot;Update&quot;/&gt;
                  &lt;input type=&quot;submit&quot; name=&quot;ds_cancel&quot; value=&quot;Cancel&quot;/&gt;
                  &lt;v:text name=&quot;c_id1&quot; column=&quot;CustomerID&quot;/&gt;
                  &lt;v:text name=&quot;c_name1&quot; column=&quot;CompanyName&quot;/&gt;
                  &lt;v:text name=&quot;c_phone1&quot; column=&quot;Phone&quot;/&gt;
                &lt;/div&gt;
              &lt;/v:template&gt;
            &lt;/v:form&gt;
          &lt;/v:template&gt;
          &lt;v:template name=&quot;t8&quot; type=&quot;add&quot;&gt;
            &lt;v:form name=&quot;a1&quot; type=&quot;update&quot; table=&quot;Demo.demo.Customers&quot; if-not-exists=&quot;insert&quot;&gt;
              &lt;v:key column=&quot;CustomerID&quot; value=&quot;--&#39;&#39;&quot; default=&quot;null&quot;/&gt;
              &lt;v:template name=&quot;template9&quot; type=&quot;simple&quot;&gt;
                &lt;div&gt;
                  &lt;v:button name=&quot;add_button&quot; action=&quot;submit&quot; value=&quot;Add&quot;/&gt;
                  &lt;v:text name=&quot;c_id2&quot; column=&quot;CustomerID&quot;/&gt;
                  &lt;v:text name=&quot;c_name2&quot; column=&quot;CompanyName&quot;/&gt;
                  &lt;v:text name=&quot;c_phone2&quot; column=&quot;Phone&quot;/&gt;
                &lt;/div&gt;
              &lt;/v:template&gt;
            &lt;/v:form&gt;
          &lt;/v:template&gt;
          &lt;v:template name=&quot;t4&quot; type=&quot;browse&quot;&gt;
            &lt;div&gt;
              &lt;v:button name=&quot;ds_edit&quot; action=&quot;simple&quot; value=&quot;Edit&quot;/&gt;
              &lt;v:button name=&quot;ds_delete&quot; action=&quot;simple&quot; value=&quot;Delete&quot;&gt;
                &lt;v:on-post&gt;
                      delete from Demo.demo.Customers where CustomerID = self.ds.ds_current_row.te_rowset[0];
                      self.ds.vc_data_bind(e);
                    &lt;/v:on-post&gt;
              &lt;/v:button&gt;
              &lt;v:label name=&quot;l5&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[0]&quot;/&gt;
              &lt;v:label name=&quot;l6&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[1]&quot;/&gt;
              &lt;v:label name=&quot;l7&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[2]&quot;/&gt;
            &lt;/div&gt;
          &lt;/v:template&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t3&quot; type=&quot;simple&quot;&gt;
          &lt;div&gt;
            &lt;v:button name=&quot;ds_prev&quot; action=&quot;simple&quot; value=&quot;&amp;lt;&amp;lt;&quot;/&gt;
            &lt;v:button name=&quot;ds_next&quot; action=&quot;simple&quot; value=&quot;&amp;gt;&amp;gt;&quot;/&gt;
          &lt;/div&gt;
        &lt;/v:template&gt;
      &lt;/v:data-set&gt;
  &lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
   <example id="vc_ex_data_set__1">
      <title>
  Simple multi-row data grid based on data-set control
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: data_set__1.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will show a list of customers from the Northwind demo database.
Allows scrolling only of existing records.

</para>
      <screen>
&lt;v:page name=&quot;data_set__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
  &lt;body&gt;
      &lt;v:data-set name=&quot;ds&quot; sql=&quot;select CustomerID, CompanyName, Phone from Demo.demo.Customers&quot; nrows=&quot;10&quot; scrollable=&quot;1&quot; cursor-type=&quot;keyset&quot;&gt;
        &lt;v:template name=&quot;t1&quot; type=&quot;simple&quot;&gt;
          &lt;div&gt;
            &lt;v:label name=&quot;l1&quot; value=&quot;CustomerID&quot; format=&quot;%s&quot; width=&quot;80&quot;/&gt;
            &lt;v:label name=&quot;l2&quot; value=&quot;CompanyName&quot; format=&quot;%s&quot; width=&quot;80&quot;/&gt;
            &lt;v:label name=&quot;l3&quot; value=&quot;Phone&quot; format=&quot;%s&quot; width=&quot;80&quot;/&gt;
          &lt;/div&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t2&quot; type=&quot;repeat&quot;&gt;
          &lt;v:template name=&quot;t7&quot; type=&quot;if-not-exists&quot;&gt;
            &lt;div&gt;No rows selected&lt;/div&gt;
          &lt;/v:template&gt;
          &lt;v:template name=&quot;t4&quot; type=&quot;browse&quot;&gt;
            &lt;div&gt;
              &lt;v:label name=&quot;l5&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[0]&quot;/&gt;
              &lt;v:label name=&quot;l6&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[1]&quot;/&gt;
              &lt;v:label name=&quot;l7&quot; value=&quot;--(control.vc_parent as vspx_row_template).te_rowset[2]&quot;/&gt;
            &lt;/div&gt;
          &lt;/v:template&gt;
        &lt;/v:template&gt;
        &lt;v:template name=&quot;t3&quot; type=&quot;simple&quot;&gt;
          &lt;div&gt;
            &lt;v:button name=&quot;ds_prev&quot; action=&quot;simple&quot; value=&quot;&amp;lt;&amp;lt;&quot;/&gt;
            &lt;v:button name=&quot;ds_next&quot; action=&quot;simple&quot; value=&quot;&amp;gt;&amp;gt;&quot;/&gt;
          &lt;/div&gt;
        &lt;/v:template&gt;
      &lt;/v:data-set&gt;
  &lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_3/data_set.vspx">VX-S-3</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_data_source">
  <refmeta>
    <refentrytitle>data-source</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>data-source</refname>
    <refpurpose>Scrollable multi-row data bound source.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_data_source">
    <funcprototype id="vc_proto_data_source">
        <funcdef>
            &lt;<function>data-source</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>expression-type</parameter> (required) </attribute>
          <attribute>
            <parameter>nrows</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-offset</parameter> (optional) </attribute>
          <attribute>
            <parameter>data</parameter> (optional) </attribute>
          <attribute>
            <parameter>meta</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_data_source">
    <title>Description</title>
    <para>Invisible multi-row data source.
      This control is an invisible represantation of a result set. Also it offer a
      number of methods for accessing and updating the data. It can be used as a source in
      the data-set control or as a separate data source for various form controls (such as label, url etc.).
      This control is using &#39;SELECT TOP N,M ..&#39; statements to bind the data into the resultset (when source is a table or SQL statement), hence this should be taken into account when using it.
      </para>
  </refsect1>
  <refsect1 id="vc_attrs_data_source">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>expression-type</title>
      <para>Denotes the type of &#39;expression&#39;</para>
   <table>
        <title>Allowed values of the &#39;expression-type&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>SQL</entry>
       <entry>
                <para>The expression is a SQL select statement</para>
       </entry>
      </row>
      <row>
              <entry>TABLE</entry>
       <entry>
                <para>The expression is a table reference</para>
       </entry>
      </row>
      <row>
              <entry>PROCEDURE</entry>
       <entry>
                <para>The expression is a procedure call</para>
       </entry>
      </row>
      <row>
              <entry>ARRAY</entry>
       <entry>
                <para>The rowset is already prepared and supplied as an array of arrays</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>nrows = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The maximum number of rows to be selected.
It is like the rowset size for a scrollable cursor.
</para>
  </formalpara>
  <formalpara>
   <title>initial-offset = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Number of record to start data binding of rowset</para>
  </formalpara>
    <formalpara>
   <title>data = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>When this attribute is specified it must be an
expression returning array of arrays. This is an alternative to specifying an
SQL expression or data-source. The result then will be used to instantiate
the repeating group. An example of such data is the result returned by &#39;exec&#39; function:</para>
<programlisting>
(
  (&quot;ALFKI&quot; &quot;Alfreds Futterkiste&quot; &quot;030-0074321&quot; )
  (&quot;ANATR&quot; &quot;Ana Trujillo Emparedados y helados&quot; &quot;(5) 555-4729&quot; )
)
</programlisting>
</formalpara>
    <formalpara>
   <title>meta = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This attribute is used together with &#39;data&#39;, so when is
specified it needs to be an expression returning a meta-data for columns corresponding to the
these returned by &#39;data&#39; expression. In practice it&#39;s same as 1-st element of metadata returned by &#39;exec()&#39; :
</para>

<programlisting>
(
  (&quot;CustomerID&quot; 182 0 5 0 1 1 &quot;Demo&quot; &quot;CustomerID&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
  (&quot;CompanyName&quot; 182 0 40 1 1 1 &quot;Demo&quot; &quot;CompanyName&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
  (&quot;Phone&quot; 182 0 24 1 1 1 &quot;Demo&quot; &quot;Phone&quot; &quot;demo&quot; &quot;Customers&quot; 0 )
)
</programlisting>

<para>for details of metadata see &#39;exec()&#39; function description.</para>
</formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_data_source">
    <title>Declaration of type vspx_data_source</title>
    <para>
</para>
    <screen>
create type vspx_data_source under vspx_control
as    (
    ds_row_meta any,      -- metadata
    ds_row_data any,      -- data coming from a function, rowset
    ds_array_data any,    -- data coming from @data=... where @expression-type=&#39;array&#39;
    ds_rows_fetched int default 0,  -- these are to keep state for scrolling
    ds_rows_offs    int default 0,  -- this is the pos of row at 0 offset
    ds_nrows int,     -- how many rows to show on single page
    ds_total_pages int default 0,
    ds_current_page int default 0,
    ds_current_pager_idx int default 0,
    ds_npages int default 10,
    ds_first_page int default 0,
    ds_last_page int default 0,
    ds_total_rows int default 0,
    ds_prev_bookmark any default null,
    ds_next_bookmark any default null,
    ds_parameters any default null,
    ds_columns any default null,
    ds_sql varchar default null,
    ds_sql_type varchar default &#39;sql&#39;,
    ds_current_inx int default 0,
    ds_update_inx int default -1,
    ds_tables any default null,
    ds_insert any default null,
    ds_update any default null,
    ds_delete any default null,
    ds_rb_data any default null,
    ds_have_more any default null
      )
temporary self as ref
method set_parameter (num any, value any) returns any,
method get_parameter (num any) returns any,
method add_parameter (value any) returns any,
method delete_parameter (num any) returns any,
method get_column_name (num any) returns any,
method set_column_label (num any, value any) returns any,
method get_column_label (num any) returns any,
method get_column_label (col varchar) returns any,
--method set_column_add_style (num int, style any) returns any,
--method get_column_add_style (num int) returns any,
--method set_column_edit_style () returns any,
--method get_column_edit_style () returns any,
--method set_column_browse_style () returns any,
--method get_column_browse_style () returns any,
--method set_column_add_format () returns any,
--method get_column_add_format () returns any,
--method set_column_edit_format () returns any,
--method get_column_edit_format () returns any,
--method set_column_browse_format () returns any,
--method get_column_browse_format () returns any,
method set_item_value (row any, col any, value any) returns any,
method set_item_value (col varchar, value any) returns any,
method get_item_value (row any, col any) returns any,
method get_rb_item_value (row any, col any) returns any,
method get_item_value (col any) returns any,
method get_item_value (col varchar) returns any,
method set_expression (expression varchar) returns any,
method get_expression () returns varchar,
method set_expression_type (type varchar) returns any,
method get_expression_type () returns varchar,
method reset () returns any,
method ds_data_bind (e vspx_event) returns any,
method ds_make_statistic () returns any,
method ds_insert (e vspx_event) returns any,
method ds_update (e vspx_event) returns any,
method ds_delete (e vspx_event) returns any,
method ds_key_params (tbl varchar) returns any,
method ds_tbl_params (tbl varchar) returns any,
method get_current_row () returns any,
constructor method vspx_data_source (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_data_source">
    <title>Examples</title>
   <example id="vc_ex_data_source__0">
      <title>
  Simple navigation form using invisible data-source control
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: data_source__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will show a cell of the customers table from the Northwind demo database.
Allows to show different columns : name and phone.

</para>
      <screen>
&lt;v:page name=&quot;data_source__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
&lt;body&gt;
&lt;v:variable name=&quot;offset&quot; default=&quot;0&quot; type=&quot;int&quot;/&gt;
   &lt;v:form name=&quot;f1&quot; method=&quot;POST&quot; type=&quot;simple&quot;&gt;
   &lt;div&gt;There is a hidden data-source on &quot;&lt;?V self.datasource1.ds_sql ?&gt;&quot;&lt;/div&gt;
   &lt;v:data-source name=&quot;datasource1&quot; expression-type=&quot;sql&quot; nrows=&quot;10&quot; initial-offset=&quot;--self.offset&quot;&gt;
     &lt;v:expression&gt;
       select * from Demo.demo.Customers where CustomerID like ? order by CompanyName desc
     &lt;/v:expression&gt;
     &lt;v:param name=&quot;mask&quot; value=&quot;--(&#39;L%&#39;)&quot;/&gt;
     &lt;v:column name=&quot;CompanyName&quot; label=&quot;Company Name&quot; input-format=&quot;%s&quot; output-format=&quot;%s&quot;/&gt;
     &lt;v:column name=&quot;Phone&quot; label=&quot;Telephone&quot; input-format=&quot;%s&quot; output-format=&quot;%s&quot; /&gt;
   &lt;/v:data-source&gt;
   &lt;div&gt;
   row #: &lt;v:text name=&quot;r1&quot; value=&quot;0&quot; /&gt;&lt;br /&gt;
   col #: &lt;v:text name=&quot;c1&quot; value=&quot;0&quot; /&gt;&lt;br /&gt;
   Seek : &lt;v:button action=&quot;simple&quot; name=&quot;b1&quot; value=&quot;OK&quot; /&gt;
   &lt;/div&gt;
   &lt;div&gt;
   &quot;&lt;v:label name=&quot;l1&quot; value=&quot;--self.datasource1.get_column_label (atoi(self.c1.ufl_value))&quot; /&gt;&quot; =
   &lt;v:label name=&quot;l2&quot; value=&quot;--self.datasource1.get_item_value (atoi(self.r1.ufl_value),atoi(self.c1.ufl_value))&quot;/&gt;
   &lt;/div&gt;
    &lt;v:on-post&gt;
      self.l1.vc_data_bind (e);
      self.l2.vc_data_bind (e);
    &lt;/v:on-post&gt;
   &lt;/v:form&gt;
&lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_error_summary">
  <refmeta>
    <refentrytitle>error-summary</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>error-summary</refname>
    <refpurpose>Placeholder for error messages.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_error_summary">
    <funcprototype id="vc_proto_error_summary">
        <funcdef>
            &lt;<function>error-summary</function> <attribute>
            <parameter>match</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_error_summary">
    <title>Description</title>
    <para>Placeholder for form error messages.
This is used on a form  to mark where error messages resulting from field or form validation are to be placed.
This   will be rendered if the vc_is_valid member of the enclosing page is false.
If rendered, this prints an error message generated by a validator or a catch handler.
This control wiil not be instantiated.  The error-summary may show errors for all controls or for a group of controls whose name matches a given regular expression.
The vc_error_message members of all controls whose validation failed will be shown at the place marked by this control if attribute &#39;match&#39; is not specified. Otherwise the vc_error_message of controls whose validation failed and &#39;name&#39; matches the pattern specified will be shown.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_error_summary">
    <title>Attributes</title>
  <formalpara>
      <title>match</title>
      <para>
This attribute specifies a regular expression to be matched against names of controls with failed validation.
The expression may match more than one control name, concatenating the messages in document order of controls. In this way an error summary may appear in
different places of the page to print errors for different controls.
			   </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_ex_error_summary">
    <title>Examples</title>
   <example id="vc_ex_error_summary__0">
      <title>
  Validation of text area input
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: error_summary__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form contains two v:textarea controls with v:validator elements inside.
When the OK button is pressed data are posted back to the same URI
so the page is instantiated again.
If any validator found a violation the message is shown to the user
in the place specified by v:error-summary element.

</para>
      <screen>
&lt;v:page name=&quot;error_summary__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:error-summary&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:error-summary /&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:textarea name=&quot;ta1&quot; default=&quot;enter your first text here&quot; value=&quot;--coalesce ({?&#39;ta1&#39;}, control.ufl_value)&quot; error-glyph=&quot;*&quot;&gt;
          &lt;v:validator test=&quot;length&quot; min=&quot;0&quot; max=&quot;50&quot; message=&quot;The length of the first input should not exceed 50 chars.&quot;/&gt;
        &lt;/v:textarea&gt;
        &lt;v:textarea name=&quot;ta2&quot; default=&quot;enter your second text here&quot; value=&quot;--coalesce ({?&#39;ta1&#39;}, control.ufl_value)&quot; error-glyph=&quot;*&quot;&gt;
          &lt;v:validator test=&quot;length&quot; min=&quot;0&quot; max=&quot;50&quot; message=&quot;The length of the second input should not exceed 50 chars.&quot;/&gt;
        &lt;/v:textarea&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; value=&quot;OK&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
   <example id="vc_ex_error_summary__1">
      <title>
  Validation of text area input with separate error summaries place
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: error_summary__1.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form contains two v:textarea controls with v:validator elements inside.
When the OK button is pressed data are posted back to the same URI
so the page is instantiated again.
If any validator found a violation the message is shown to the user
in the place specified by v:error-summary element depending of a match attribute.

</para>
      <screen>
&lt;v:page name=&quot;error_summary__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:error-summary&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:error-summary match=&quot;ta1&quot;/&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:textarea name=&quot;ta1&quot; default=&quot;enter your first text here&quot; value=&quot;--coalesce ({?&#39;ta1&#39;}, control.ufl_value)&quot; error-glyph=&quot;*&quot;&gt;
          &lt;v:validator test=&quot;length&quot; min=&quot;0&quot; max=&quot;50&quot; message=&quot;The length of the first input should not exceed 50 chars.&quot;/&gt;
        &lt;/v:textarea&gt;
      &lt;v:error-summary match=&quot;ta2&quot;/&gt;
        &lt;v:textarea name=&quot;ta2&quot; default=&quot;enter your second text here&quot; value=&quot;--coalesce ({?&#39;ta1&#39;}, control.ufl_value)&quot; error-glyph=&quot;*&quot;&gt;
          &lt;v:validator test=&quot;length&quot; min=&quot;0&quot; max=&quot;50&quot; message=&quot;The length of the second input should not exceed 50 chars.&quot;/&gt;
        &lt;/v:textarea&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; value=&quot;OK&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_expression">
  <refmeta>
    <refentrytitle>expression</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>expression</refname>
    <refpurpose>An SQL statement that generates a rowset for v:data-source.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_expression">
    <funcprototype id="vc_proto_expression">
        <funcdef>
            &lt;<function>expression</function> <attribute>
            <parameter>language</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_expression">
    <title>Description</title>
    <para>A container for SQL statement generating a rowset or table name (see data-source).</para>
  </refsect1>
  <refsect1 id="vc_attrs_expression">
    <title>Attributes</title>
  <formalpara>
   <title>language = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>Denotes the type of language,
	    currently only SQL expressions are supported, see &#39;expression-type&#39; attribute
	    of the data-source control.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_field">
  <refmeta>
    <refentrytitle>field</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>field</refname>
    <refpurpose>Name of input to be sent to and back between pup-up and parent window.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_field">
    <funcprototype id="vc_proto_field">
        <funcdef>
            &lt;<function>field</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>ref</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_field">
    <title>Description</title>
    <para>
 This element may occur under browse-button or select button,
 it enumerates the names of inputs to be sent between pop-up and parent window.</para>
  </refsect1>
  <refsect1 id="vc_attrs_field">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>ref = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>When a field is used as child of and return button
	    then this must contain valid reference to name of a input control
	    (like text, select-list, data-list etc.) from current page. The referenced
	    control&#39;s value will be used to set the value of control with name specified in
	    attribute &#39;name&#39; in the target page. The data will be set using automatically generated
	    JavaScript function.
	  </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_form">
  <refmeta>
    <refentrytitle>form</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>form</refname>
    <refpurpose>Generic scriptable container for elements that may accept user&#39;s input.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_form">
    <funcprototype id="vc_proto_form">
        <funcdef>
            &lt;<function>form</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>type</parameter> (optional) </attribute>
          <attribute>
            <parameter>action</parameter> (optional) </attribute>
          <attribute>
            <parameter>method</parameter> (optional) </attribute>
          <attribute>
            <parameter>table</parameter> (optional) </attribute>
          <attribute>
            <parameter>if-not-exists</parameter> (optional) </attribute>
          <attribute>
            <parameter>concurrency</parameter> (optional) </attribute>
          <attribute>
            <parameter>triggers</parameter> (optional) </attribute>
          <attribute>
            <parameter>data-source</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_form">
    <title>Description</title>
    <para>
    This is a grouping element for controls that handle post data and validation of user&#39;s input. In case of type &#39;update&#39;, this is a single row update control for a database table.
This retrieves the data from the row identified by the keys and shows the data in the column bound fields enclosed.  If responding to a post for a submit inside this form, the form updates/inserts the data and shows the resulting state at the render pass.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_form">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>type</title>
      <para>Type of form, can be &#39;simple&#39; or &#39;update&#39;. When this is &#39;simple&#39; the vspx_form class will be instantiated, otherwise in case of &#39;update&#39; vspx_update_form subclass will be used.</para>
   <table>
        <title>Allowed values of the &#39;type&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>simple</entry>
       <entry>
                <para>
Form with no special data binding.
</para>
       </entry>
      </row>
      <row>
              <entry>update</entry>
       <entry>
                <para>
Form that may be used in templates of type &#39;update&#39; or &#39;add&#39;.
</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
      <title>action</title>
      <para>
      A URL for processing. The data filled-in the form will be submitted to the &#39;action&#39; page.
      Therefore this is a page where the content of that form will be processed.
      If it is empty, the target is a current page.
				 </para>
  </formalpara>
  <formalpara>
      <title>method</title>
      <para>A method  of transferring the form data, can be POST or GET. The same as &#39;method&#39; of HTML forms.</para>
      <para>The use of &#39;GET&#39; is not recommended because the length of the URI may easily exceed internal limits of the browser or an intermediate proxy server.</para>
  </formalpara>
  <formalpara>
      <title>table</title>
      <para>If the value of &#39;type&#39; attribute is &#39;update&#39;, the form acts as a single row update control for a database table; and the value of &#39;table&#39; attribute specifies the name of that table.
It retrieves the data from the row identified by the keys and shows the data in the column bound fields enclosed.  If responding to a post for a submit inside this form, the form updates/inserts the data and shows the resulting state at the render pass.
This attribute is required if &#39;type&#39; is &#39;update&#39; and prohibited otherwise.</para>
  </formalpara>
  <formalpara>
      <title>if-not-exists</title>
      <para>If the keys do not select any row, and the value of this attribute is &#39;insert&#39;, the update form will be filled in with defaults filled in and will do an insert into the table when the form is submitted.
In this case of course the keys will have to be defaulted after the post or will have to be supplied in the post as fields.
Any defaulting should take place in the v:on-post handler which is before the insert or update in the event of the post.
</para>
  </formalpara>
  <formalpara>
      <title>concurrency</title>
      <para>If true and a previous value was shown in the form before the post being processed, this causes the system to check whether any of the data has been updated between getting it and the post at hand.
This is a sort of optimistic concurrency control at the row level.  If an update is detected, the updated_meanwhile message is set as the error message of the form and no update is made.  The render pass may choose to process this message as it will, the default is to show it as any other error message for form level validation failure.
</para>
  </formalpara>
  <formalpara>
      <title>triggers</title>
      <para>This is applicable for update form only, when this is OFF no PL triggers
	will be fired when inserting or updating.</para>
  </formalpara>
  <formalpara>
   <title>data-source = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>This is applicable to the update form and is
	An alternative of &#39;table&#39;. When is specified the value is suppsed to be
	valid reference to existing data-source control. Further the given data-source
	will be used to bind/update the data.
      </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_form">
    <title>Declaration of type vspx_form</title>
    <para>
</para>
    <screen>
create type vspx_form under vspx_control
   as
     (
       uf_action varchar default &#39;&#39;,
       uf_method varchar default &#39;post&#39;,
       --uf_inside_form int default 0,
       uf_validators any,
       uf_xmodel any default null,
       uf_xsubmit any default null,
       uf_xschema any default null
     )  temporary self as ref
   constructor method vspx_form (name varchar, parent vspx_control),
   method prologue_render (sid varchar, realm varchar, nonce varchar) returns any,
   method epilogue_render () returns any,
   overriding method vc_set_model () returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_form">
    <title>Examples</title>
   <example id="vc_ex_form__0">
      <title>
  Simple entry form
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: form__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The OK button of the form submits data from the form back to the same page.

</para>
      <screen>
&lt;v:page name=&quot;form__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:form&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:label name=&quot;label1&quot; value=&quot;--&#39;Simple form&#39;&quot;/&gt;
        &lt;v:text name=&quot;txt1&quot; default=&quot;&quot;/&gt;
        &lt;v:text name=&quot;txt2&quot; default=&quot;&quot;/&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; value=&quot;OK&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
   <example id="vc_ex_form__1">
      <title>
  Simple entry form containing various controls
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: form__1.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The OK button of the form submits data from the form back to the same page.
the check-box is validated against ragio group

</para>
      <screen>
&lt;v:page name=&quot;form__1&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:form | v:validator&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;f1&quot; type=&quot;simple&quot; method=&quot;POST&quot;&gt;
	&lt;v:error-summary/&gt;&lt;br/&gt;
        &lt;v:label name=&quot;l1&quot; value=&quot;--&#39;Simple form&#39;&quot;/&gt;&lt;br/&gt;
        &lt;v:url name=&quot;u1&quot; value=&quot;--&#39;This page&#39;&quot; url=&quot;--self.f1.uf_action&quot; /&gt;&lt;br/&gt;
        &lt;v:text name=&quot;t1&quot; value=&quot;--self.rb1.ufl_value&quot;/&gt;&lt;br/&gt;
        &lt;v:text name=&quot;t2&quot; value=&quot;--&#39;my&#39;||&#39;password&#39;&quot; type=&quot;password&quot;/&gt;&lt;br/&gt;
        &lt;v:text name=&quot;t3&quot; value=&quot;--&#39;something&#39;||&#39;hidden&#39;&quot; type=&quot;hidden&quot;/&gt;
	&lt;v:textarea name=&quot;ta1&quot; value=&quot;--&#39;some text&#39;&quot; /&gt;&lt;br/&gt;
        &lt;v:check-box name=&quot;cb1&quot; value=&quot;check-box&quot; /&gt;&lt;br/&gt;
	&lt;v:radio-group name=&quot;rg1&quot;&gt;
	 &lt;v:radio-button name=&quot;rb1&quot; value=&quot;one&quot; /&gt;
	 &lt;v:radio-button name=&quot;rb2&quot; value=&quot;two&quot; /&gt;
        &lt;/v:radio-group&gt;&lt;br/&gt;
        &lt;v:button name=&quot;b1&quot; action=&quot;simple&quot; value=&quot;--&#39;OK&#39;&quot;/&gt;&lt;br/&gt;
 	&lt;v:validator test=&quot;sql&quot; message=&quot;only when radio is on position one check-box could be checked&quot;&gt;
	if (self.rb2.ufl_selected and self.cb1.ufl_selected)
	  {
	    return 1;
	  }
	&lt;/v:validator&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/form.vspx">VX-S-2</ulink>
   </para>
   <para>
      <ulink url="/tutorial/web/vx_s_3/update_form.vspx">VX-S-3</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_hidden">
  <refmeta>
    <refentrytitle>hidden</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>hidden</refname>
    <refpurpose>A wrapper that prevents WYSIWYG editors from displaying its content.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_hidden">
    <funcprototype id="vc_proto_hidden">
        <funcdef>
            &lt;<function>hidden</function> <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_hidden">
    <title>Description</title>
    <para>This control does not affect the resulting HTML and Virtuoso/PL code. It is used by some WYSIWYG editors in order to temporarily hide details of the page fragment from the editor&#39;s drawing area.</para>
  </refsect1>
  <refsect1 id="vc_attrs_hidden">
    <title>Attributes</title>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_horizontal_template">
  <refmeta>
    <refentrytitle>horizontal-template</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>horizontal-template</refname>
    <refpurpose />
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_horizontal_template">
    <funcprototype id="vc_proto_horizontal_template">
        <funcdef>
            &lt;<function>horizontal-template</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_horizontal_template">
    <title>Description</title>
  </refsect1>
  <refsect1 id="vc_attrs_horizontal_template">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_horizontal_template">
    <title>Declaration of type vspx_horizontal_template</title>
    <para>
</para>
    <screen>
create type vspx_horizontal_template under vspx_control
as ( vc_stub any ) temporary self as ref
</screen>
  </refsect1>
</refentry>
 <refentry id="vc_include">
  <refmeta>
    <refentrytitle>include</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>include</refname>
    <refpurpose>A place where the source code of other page should be inserted.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_include">
    <funcprototype id="vc_proto_include">
        <funcdef>
            &lt;<function>include</function> <attribute>
            <parameter>url</parameter> (required) </attribute>
          <attribute>
            <parameter>active</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-active</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_include">
    <title>Description</title>
    <para>The VSPX compiler replaces this control with the content of another page.
This will include the content from the specified url at this point of the page.  The url is relative to the page.
The inclusion will be done before compilation of VSPX into Virtuoso/PL, hence the include can contain either vspx or static HTML  content.
The only requirement is that the included file be well formed.
Note also that if you are using vspx namespace in the include file, it must be declared as such.
This element will not be instantiated.
instead of instantiating it will be replaced with content of the specified document.
The included page may or may not contain a &#39;page&#39; element.
If a &#39;page&#39; element is found in the included file
this will be skipped in the resulting page.
Also names of controls in the included file   MUST NOT conflict with names of controls in the top level page or other included content.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_include">
    <title>Attributes</title>
  <formalpara>
      <title>url</title>
      <para>URL of file to be included. If relative then the base is the page where the control resides.
E.g. If &#39;/home/pageA&#39; includes &#39;subdir1/pageB&#39; and the included page includes &#39;subdir2/pageC&#39; then &#39;pageC&#39; should reside
in &#39;/home/subdir1/subdir2&#39;, not in &#39;/home/subdir2&#39;.
          </para>
  </formalpara>
  <formalpara>
   <title>active = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A data bound value to enable or disable the link. The default is &#39;1&#39; meaning &#39;enable&#39;.</para>
  </formalpara>
  <formalpara>
   <title>initial-active = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A data bound value to enable or disable the link. The default is &#39;1&#39; meaning &#39;enable&#39;.
Unlike &#39;active&#39; attribute, this one is effective only when the page is displayed in the first time, not after user posts data back to the page.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_ex_include">
    <title>Examples</title>
   <example id="vc_ex_include__0">
      <title>
  Include a common back-link into the end of page
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: include__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


If the file footer.xml is placed in the same directory where this sample page is located
and contains the paragraph
&lt;P&gt;&lt;a href=&quot;index.vspx&quot;&gt;Back to index&lt;/a&gt;&lt;/P&gt;
then the resulting page will have additional paragraph at the end.

</para>
      <screen>
&lt;v:page name=&quot;include__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;&lt;title&gt;VSPX samples | v:include&lt;/title&gt;&lt;/head&gt;
    &lt;body&gt;
      &lt;p&gt;The link after the horizontal ruler is included from footer.xml&lt;/p&gt;
      &lt;hr/&gt;
      &lt;v:include url=&quot;footer.xml&quot;/&gt; &lt;!-- this will include the file described above --&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_isql">
  <refmeta>
    <refentrytitle>isql</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>isql</refname>
    <refpurpose>An interactive SQL control that allows the user to type an SQL statement and to see the result of its execution.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_isql">
    <funcprototype id="vc_proto_isql">
        <funcdef>
            &lt;<function>isql</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>isolation</parameter> (optional) </attribute>
          <attribute>
            <parameter>timeout</parameter> (optional) </attribute>
          <attribute>
            <parameter>maxrows</parameter> (optional) </attribute>
          <attribute>
            <parameter>user</parameter> (optional) </attribute>
          <attribute>
            <parameter>password</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_isql">
    <title>Description</title>
  </refsect1>
  <refsect1 id="vc_attrs_isql">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>isolation</title>
      <para>Transaction isolation level to be used.</para>
   <table>
        <title>Allowed values of the &#39;isolation&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>uncomitted</entry>
       <entry>
                <para>&#39;uncomitted&#39; transaction isolation level</para>
       </entry>
      </row>
      <row>
              <entry>committed</entry>
       <entry>
                <para>&#39;committed&#39; transaction isolation level</para>
       </entry>
      </row>
      <row>
              <entry>repeatable</entry>
       <entry>
                <para>&#39;repeatable&#39; transaction isolation level</para>
       </entry>
      </row>
      <row>
              <entry>serializable</entry>
       <entry>
                <para>&#39;serializable&#39; transaction isolation level</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>timeout = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Query time-out in seconds (currently not supported)</para>
  </formalpara>
  <formalpara>
   <title>maxrows = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Maximum number of rows to be displayed.</para>
  </formalpara>
  <formalpara>
   <title>user = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>SQL user account to perform the query, if not specified
	    the SQL account used to run the VSPX page will be used.
	  </para>
  </formalpara>
  <formalpara>
   <title>password = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>When the &#39;user&#39; attribute is supplied, this is
	    the user&#39;s password.
	  </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_isql">
    <title>Declaration of type vspx_isql</title>
    <para>
 A isql control
</para>
    <screen>
create type vspx_isql under vspx_form
as
 (
   -- parameters
   isql_custom_exec integer default 0,  -- do nothing to allow vspx code to perform actual exec (i.e. dataset open)
   isql_explain integer default 0,  -- explain instead of execute
   isql_maxrows integer default 20,
   isql_chunked integer default 0,
   isql_current_stmt varchar default null,
   isql_current_state any default null,
   isql_current_meta any default null,
   isql_current_pos int default 0,
   isql_current_row int default 0,
   isql_rows_fetched int default 0,
   isql_user varchar default null,
   isql_password varchar default null,
   isql_isolation varchar default &#39;committed&#39;,
   isql_timeout integer default 60,
   isql_text varchar default &#39;&#39;, -- sql text to execute
   --results
   --also used vc_error_message as vector(vector(&#39;sqlstate&#39;,&#39;sqlmessage&#39;), ... ) for multiple statements
   isql_mtd any default null, --as vector(mtd, ... ) for multiple statements
   isql_res any default null,  --as vector(res, ... ) for multiple statements
   isql_stmts any default null -- array of statements to be executed on render as cursors
 )
   temporary self as ref
  constructor method vspx_isql (name varchar, parent vspx_control),
  method isql_exec () returns any
</screen>
  </refsect1>
</refentry>
 <refentry id="vc_item">
  <refmeta>
    <refentrytitle>item</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>item</refname>
    <refpurpose>Item representing a selection inside a select list.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_item">
    <funcprototype id="vc_proto_item">
        <funcdef>
            &lt;<function>item</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>value</parameter> (required) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_item">
    <title>Description</title>
    <para>
Item representing a selection inside a select list.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_item">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlCode">SqlCode</link>
   </title>
      <para>The visible value of the option, it will be shown
	    in the option list.
	  </para>
  </formalpara>
  <formalpara>
      <title>value</title>
      <para>The key value of the option, it will be assigned
	    to the select control ufl_value is given option is seelcted.
	  </para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_key">
  <refmeta>
    <refentrytitle>key</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>key</refname>
    <refpurpose>A key value of the vspx:form of type &#39;update&#39;.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_key">
    <funcprototype id="vc_proto_key">
        <funcdef>
            &lt;<function>key</function> <attribute>
            <parameter>name</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (required) </attribute>
          <attribute>
            <parameter>value</parameter> (required) </attribute>
          <attribute>
            <parameter>default</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_key">
    <title>Description</title>
    <para>This control defines a key value of the vspx:form of type &#39;update&#39;.
All the vspx:key children together should select one or zero rows from the table.
Controls inside the form will process fields of this selected row.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_key">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>Not used</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>Name of the column in the table to be updated.
This may be either the name of a primary key column or an other column, as long as the selection specified by all vspx:key children of the vspx:form is unambiguous.</para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The value of the key field referred to  by the &#39;column&#39; attribute.</para>
  </formalpara>
  <formalpara>
   <title>default = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The default value to be used when the &#39;value&#39; expression returns NULL.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_label">
  <refmeta>
    <refentrytitle>label</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>label</refname>
    <refpurpose>Generic scriptable text.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_label">
    <funcprototype id="vc_proto_label">
        <funcdef>
            &lt;<function>label</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>format</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_label">
    <title>Description</title>
    <para>This is for displaying a value as plain text.
The underlying class is derived from VSPX_FIELD so the value to be displayed is accessible as a value of any VSPX field.</para>
  </refsect1>
  <refsect1 id="vc_attrs_label">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
      <title>format</title>
      <para>A sprintf format string for printing the value</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_label">
    <title>Declaration of type vspx_label</title>
    <para>
</para>
    <screen>
create type vspx_label under vspx_field
as
(
  vl_format varchar default &#39;%s&#39;
) temporary self as ref
constructor method vspx_label (name varchar, parent vspx_control),
overriding method vc_render () returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_label">
    <title>Examples</title>
   <example id="vc_ex_label__0">
      <title>
  Simple dynamic text
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: label__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This page demonstrates output of data values of various types.

</para>
      <screen>
&lt;v:page name=&quot;label__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;&lt;title&gt;VSPX samples | v:label&lt;/title&gt;&lt;/head&gt;
    &lt;body&gt;
	Float: &lt;v:label name=&quot;flo&quot; value=&quot;--3.14&quot; format=&quot;%d&quot; /&gt;&lt;br/&gt;
	Integer: &lt;v:label name=&quot;intgr&quot; value=&quot;--2+2&quot; format=&quot;%d&quot; /&gt;&lt;br/&gt;
	String: &lt;v:label name=&quot;strg&quot; value=&quot;--&#39;The quick brown fox has stopped his jumping over the lazy dog&#39;&quot; format=&quot;%s&quot; /&gt;&lt;br/&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_leaf_template">
  <refmeta>
    <refentrytitle>leaf-template</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>leaf-template</refname>
    <refpurpose />
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_leaf_template">
    <funcprototype id="vc_proto_leaf_template">
        <funcdef>
            &lt;<function>leaf-template</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_leaf_template">
    <title>Description</title>
  </refsect1>
  <refsect1 id="vc_attrs_leaf_template">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_leaf_template">
    <title>Declaration of type vspx_leaf_template</title>
    <para>
</para>
    <screen>
create type vspx_leaf_template under vspx_control
as ( vc_stub any ) temporary self as ref
</screen>
  </refsect1>
</refentry>
 <refentry id="vc_local_variable">
  <refmeta>
    <refentrytitle>local-variable</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>local-variable</refname>
    <refpurpose>Local variable - an invisible control to store a temporary value.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_local_variable">
    <funcprototype id="vc_proto_local_variable">
        <funcdef>
            &lt;<function>local-variable</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_local_variable">
    <title>Description</title>
    <para>
This tag declares a control that can store a temporary value that can be accessed from other controls.
Usually it is an intermediate value that is used by a group of controls of the same form. E.g. if
controls of a form display various data stored in a complex object then it may be convenient to obtain this object once and place it
into value of a local-variable control that is the first child control of a form. The rest of child controls may access the value
from the first child to calculate their values.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_local_variable">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_login">
  <refmeta>
    <refentrytitle>login</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>login</refname>
    <refpurpose>Authentication parameters of a page.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_login">
    <funcprototype id="vc_proto_login">
        <funcdef>
            &lt;<function>login</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>realm</parameter> (required) </attribute>
          <attribute>
            <parameter>mode</parameter> (required) </attribute>
          <attribute>
            <parameter>user-password</parameter> (optional) </attribute>
          <attribute>
            <parameter>user-password-check</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_login">
    <title>Description</title>
    <para>
<para>The login control controls authentication for its page.
Depending on options this  may or may not be visible.
This works together with a login-form and logout-button controls.  The storage of passwords and user names is left to the application, which can specify functions called by these widgets.
The server keeps login information in the following table:</para>
<programlisting>

create table VSPX_SESSION (VS_REALM varchar, VS_SID varchar, VS_UID varchar, VS_STATE long varchar,
  primary key (VS_REALM, VS_SID));

</programlisting>
<para> This table is shared between all vspx applications, each with their login differentiated by realm.
The state is an array of name value pairs which will be accessed through connection_get and connection_set inside the page code.</para>
<para>
There are three methods of keeping session state:URL-poisoning, digest authentication and Cookies.The URL-poisoning scheme presents a login dialog form and sets a session ID as hidden form element.
Digest authentication  uses an opaque value as session id and is available only for browsers that support standard HTTP 1.1 digest authentication. The Cookie is an analogue of URL poisoning, but in that case session ID is kept as a Cookie, thus cookies must be enabled on the browser.
</para>

<para>
The login control is mandatory when using a persistent page variables (see persist=&quot;session&quot; attribute of &#39;variable&#39; control). This is because HTTP protocol is state-less; therefore value of such variables have to be stored in a table and restored on next hit with same session ID (and realm). Hence as login control maintains a session state (via some mechanism, see notes above), this capability is used to maintain persistent page variables.
Note also that persistent page variables can be used between different pages, in that case all of those pages need to have login control (in most cases it is invisible).
</para>
</para>
  </refsect1>
  <refsect1 id="vc_attrs_login">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>realm</title>
      <para>This is the authentication realm name.</para>
  </formalpara>
  <formalpara>
      <title>mode</title>
      <para>This specifies the preferred mode of keeping session and login information.
In the case of url and cookie the name and password will have to be supplied in a form submit.  The vspx:login-form control provides a convenient way of doing this.  If passwords are transmitted in a form submit, it is best for security to have the login page accessed via SSL only. Many values may be separated by spaces.  This is the order of preference.  The system will use the first available depending on the user agent.</para>
   <table>
        <title>Allowed values of the &#39;mode&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>digest</entry>
       <entry>
                <para>HTTP digest authentication is used and the session id will travel as the opaque data in the digest headers.</para>
       </entry>
      </row>
      <row>
              <entry>url</entry>
       <entry>
                <para>The url mode means that URL poisoning is used and that the session id passes with the links, posts etc.  Some automation is offered for this by the vspx:url and vspx:form and derived controls.</para>
       </entry>
      </row>
      <row>
              <entry>cookie</entry>
       <entry>
                <para>The session id is set in a cookie on browser.</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
    <formalpara>
      <title>user-password</title>
<para>The name of a SQL function which will retrieve the password given a user name.  If digest authentication is to be possible, this function must be specified. Example:
</para>
<programlisting>
create procedure
sql_user_password (in name varchar)
{
  declare pass varchar;
  pass := NULL;
  whenever not found goto none;
  select pwd_magic_calc (U_NAME, U_PASSWORD, 1) into pass
          from SYS_USERS where U_NAME = name and U_SQL_ENABLE = 1 and U_IS_ROLE = 0;
none:
  return pass;
}
;</programlisting>
</formalpara>
    <formalpara>
      <title>user-password-check</title>
<para>This is a function which takes the user name and password (unencrypted) and returns true if these match, false otherwise.</para>

<para>
If the application will keep a session state  which will automatically be extracted from the application&#39;s user repository upon login, then either of these functions may set this using connection_set.  This will persist in the session if the login is successful and will be discarded otherwise.  An example of such information is a user privilege class, real name, email or such.
These functions may be called one or more times during the session, but no more than one call at the start is guaranteed.</para>
<para>Example:</para>
<programlisting>

create procedure
sql_user_password_check (in name varchar, in pass varchar)
{
  if (exists (select 1 from SYS_USERS where U_NAME = name and U_SQL_ENABLE = 1 and U_IS_ROLE = 0 and
        pwd_magic_calc (U_NAME, U_PASSWORD, 1) = pass))
    return 1;
  return 0;
}
;</programlisting>
<para>Note: when the mode is digest the login control will only call user_password and in other modes  it will only call user_password_check.</para>
</formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_login">
    <title>Declaration of type vspx_login</title>
    <para>
</para>
    <screen>
create type vspx_login under vspx_form
as (
    vl_realm varchar,
    vl_mode varchar,
    vl_pwd_get varchar,
    vl_usr_check varchar,
    vl_authenticated int default 0,
    vl_user varchar,
    vl_sid varchar,
    vl_no_login_redirect varchar,
    vl_logout_in_progress int default 0
   )
 temporary self as ref
overriding method vc_view_state (stream any, n int) returns any,
overriding method vc_set_view_state (e vspx_event) returns any,
constructor method vspx_login (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_login">
    <title>Examples</title>
   <example id="vc_ex_login__0">
      <title>
  Simple login dialog
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: login__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will show simltaniously &#39;not-autneticated&#39; message and
a simple post counter.

</para>
      <screen>
&lt;v:page name=&quot;login__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
  &lt;body&gt;
      &lt;v:variable name=&quot;ctr&quot; type=&quot;int&quot; persist=&quot;session&quot; default=&quot;0&quot;/&gt;
      &lt;v:login name=&quot;lc1&quot; realm=&quot;vspx&quot; mode=&quot;url&quot; user-password-check=&quot;sql_user_password_check&quot;&gt;
        &lt;v:template type=&quot;if-no-login&quot;&gt;You are not logged in&lt;/v:template&gt;
        &lt;v:login-form name=&quot;f1&quot; required=&quot;1&quot; title=&quot;Login&quot; user-title=&quot;User Name&quot; password-title=&quot;Password&quot; submit-title=&quot;Login&quot;/&gt;
        &lt;v:template type=&quot;if-login&quot;&gt;
    Posted #: &lt;v:label name=&quot;l1&quot; value=&quot;--self.ctr&quot; format=&quot;%d&quot;/&gt;
          &lt;v:button name=&quot;b1&quot; action=&quot;simple&quot; value=&quot;Reload&quot;&gt;
            &lt;v:on-post&gt;
		self.ctr := self.ctr + 1;
		self.l1.vc_data_bind (e);
		&lt;/v:on-post&gt;
          &lt;/v:button&gt;
          &lt;v:button name=&quot;b2&quot; action=&quot;logout&quot; value=&quot;Logout&quot;/&gt;
        &lt;/v:template&gt;
      &lt;/v:login&gt;
  &lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_6/login.vspx">VX-S-6</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_login_form">
  <refmeta>
    <refentrytitle>login-form</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>login-form</refname>
    <refpurpose>A form to be shown if the user is not logged in.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_login_form">
    <funcprototype id="vc_proto_login_form">
        <funcdef>
            &lt;<function>login-form</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>required</parameter> (required) </attribute>
          <attribute>
            <parameter>title</parameter> (optional) </attribute>
          <attribute>
            <parameter>user-title</parameter> (optional) </attribute>
          <attribute>
            <parameter>password-title</parameter> (optional) </attribute>
          <attribute>
            <parameter>submit-title</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_login_form">
    <title>Description</title>
    <para>
login-form is the control for getting login information.  This may only appear inside a login.
Its function will depend on the type of login being attempted.  If the type is digest, this is a button which, when submitted, will send the digest challenge.
			</para>
    <para>
If the url or cookie session mode is chosen, this will be a form of 2 fields with user name and password and a submit button.
			</para>
    <para>
if the standard form is not suitable, this can be an arbitrary form.  This must post  buttons values named &quot;username&quot; and &quot;password&quot; and a submit button named &quot;login&quot;.  No children need be specified if the default form is OK.
			</para>
    <para>
If the redirect attribute of template[@type=if-no-login] is not specified,
the contents of this child are instantiated and shown in the place of the login control.
This can be arbitrary content.
			</para>
  </refsect1>
  <refsect1 id="vc_attrs_login_form">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>required</title>
      <para>
If digest is the mode, then this means that the login is mandatory and that instead of displaying the login button which will send the challenge if pressed, the challenge will be sent automatically.
			   </para>
  </formalpara>
  <formalpara>
      <title>title</title>
      <para>Title of login button if digest is attempted.
			   </para>
  </formalpara>
  <formalpara>
      <title>user-title</title>
      <para>Title of user name field
			   </para>
  </formalpara>
  <formalpara>
      <title>password-title</title>
      <para>Title of password field
			   </para>
  </formalpara>
  <formalpara>
      <title>submit-title</title>
      <para>Title of submit button
			   </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_login_form">
    <title>Declaration of type vspx_login_form</title>
    <para>
</para>
    <screen>
create type vspx_login_form under vspx_form
as
  (
   vlf_title varchar,
   vlf_user_title varchar,
   vlf_password_title varchar,
   vlf_submit_title varchar,
   vlf_login vspx_login
  ) temporary self as ref
constructor method vspx_login_form (name varchar,  parent vspx_control),
constructor method vspx_login_form (name varchar, title varchar, user_title varchar, password_title varchar, submit_tile varchar, login vspx_login),
overriding method vc_render () returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_login_form">
    <title>Examples</title>
   <example id="vc_ex_login_form__0">
      <title>
  A simple default login-form
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: login_form__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This example will render just a login form

</para>
      <screen>
&lt;v:page name=&quot;login_form__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;&lt;title&gt;VSPX samples | v:login-form&lt;/title&gt;&lt;/head&gt;
    &lt;body&gt;
      &lt;v:login name=&quot;login_0&quot; mode=&quot;url&quot; user-password-check=&quot;sql_user_password_check&quot; realm=&quot;vspx&quot;&gt;
        &lt;v:login-form name=&quot;login_form_0&quot;
          required=&quot;1&quot;
          title=&quot;Login&quot;
          user-title=&quot;User Name&quot;
          password-title=&quot;Password&quot;
          submit-title=&quot;Login&quot;/&gt;
        &lt;/v:login&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_method">
  <refmeta>
    <refentrytitle>method</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>method</refname>
    <refpurpose>Page method - a user defined member of page class.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_method">
    <funcprototype id="vc_proto_method">
        <funcdef>
            &lt;<function>method</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>returns</parameter> (optional) </attribute>
          <attribute>
            <parameter>arglist</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_method">
    <title>Description</title>
    <para>This creates a custom method of the page class.</para>
  </refsect1>
  <refsect1 id="vc_attrs_method">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of method to be created</para>
  </formalpara>
  <formalpara>
   <title>returns = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>Optional return datatype type</para>
  </formalpara>
  <formalpara>
      <title>arglist</title>
      <para>comma-separated list of arguments. For example : &quot;in arg1 varchar, out arg1 integer ...&quot;</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_node">
  <refmeta>
    <refentrytitle>node</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>node</refname>
    <refpurpose>A place holder for rendering a tree node.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_node">
    <funcprototype id="vc_proto_node">
        <funcdef>
            &lt;<function>node</function> <attribute>
            <parameter>void</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_node">
    <title>Description</title>
    <para>This control indicates the place of a subtree inside a node template.</para>
  </refsect1>
  <refsect1 id="vc_attrs_node">
    <title>Attributes</title>
  <formalpara>
      <title>void</title>
      <para>Not used.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_node_template">
  <refmeta>
    <refentrytitle>node-template</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>node-template</refname>
    <refpurpose />
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_node_template">
    <funcprototype id="vc_proto_node_template">
        <funcdef>
            &lt;<function>node-template</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_node_template">
    <title>Description</title>
  </refsect1>
  <refsect1 id="vc_attrs_node_template">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_node_template">
    <title>Declaration of type vspx_node_template</title>
    <para>
</para>
    <screen>
create type vspx_node_template under vspx_control
as ( vc_stub any ) temporary self as ref
</screen>
  </refsect1>
</refentry>
 <refentry id="vc_on_init">
  <refmeta>
    <refentrytitle>on-init</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>on-init</refname>
    <refpurpose>Container for code that should be executed at the end of control instantiation.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_on_init">
    <funcprototype id="vc_proto_on_init">
        <funcdef>
            &lt;<function>on-init</function>&gt;(EventHandler)&lt;/<function>on-init</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_on_init">
    <title>Description</title>
    <para>The code contained in this element is executed at the end of the control&#39;s constructor.
	This is expected to have additional initialization checking etc.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_on_init_container">
  <refmeta>
    <refentrytitle>on-init-container</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>on-init-container</refname>
    <refpurpose>This is identical to v:on-init.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_on_init_container">
    <funcprototype id="vc_proto_on_init_container">
        <funcdef>
            &lt;<function>on-init-container</function>&gt;(EventHandler)&lt;/<function>on-init-container</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_on_init_container">
    <title>Description</title>
  </refsect1>
 </refentry>
 <refentry id="vc_on_post">
  <refmeta>
    <refentrytitle>on-post</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>on-post</refname>
    <refpurpose>Container for code that should be executed when the element gets a post.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_on_post">
    <funcprototype id="vc_proto_on_post">
        <funcdef>
            &lt;<function>on-post</function>&gt;(EventHandler)&lt;/<function>on-post</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_on_post">
    <title>Description</title>
    <para>
The code contained in this element is executed when the element gets a post.
For fields and forms, this is a context for an a SQL compound statement that will be executed.
The statement should end with a return 1 or 0.  The implicit return is 0.  A return of 1 means that the post is fully handled here and not to be passed on to the parent chain.
A 0 means that the post was not handled and the next control up the chain will try.
</para>
    <para>
The context has a self which is the page, a vspx_control which is the control which defines this handler, and a origin_control, which is the control that first got the post event.  This will be a data field or button.  The vspx_event with the post&#39;s data will be in the variable event.
</para>
    <para>
The interpretation of the return value is the same for other event handlers.  SQL
conditions signalled will go to the page, these condition handlers are
invoked in no special context, hence the declare handler for SQL
construct should not be used to pass control between handlers, but only
within handlers.
</para>
  </refsect1>
 </refentry>
 <refentry id="vc_on_post_container">
  <refmeta>
    <refentrytitle>on-post-container</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>on-post-container</refname>
    <refpurpose>This is identical to v:on-post.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_on_post_container">
    <funcprototype id="vc_proto_on_post_container">
        <funcdef>
            &lt;<function>on-post-container</function>&gt;(EventHandler)&lt;/<function>on-post-container</function>&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_on_post_container">
    <title>Description</title>
  </refsect1>
 </refentry>
 <refentry id="vc_page">
  <refmeta>
    <refentrytitle>page</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>page</refname>
    <refpurpose>Container of VSPX code.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_page">
    <funcprototype id="vc_proto_page">
        <funcdef>
            &lt;<function>page</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>decor</parameter> (optional) </attribute>
          <attribute>
            <parameter>style</parameter> (optional) </attribute>
          <attribute>
            <parameter>on-error-redirect</parameter> (optional) </attribute>
          <attribute>
            <parameter>on-deadlock-retry</parameter> (optional) </attribute>
          <attribute>
            <parameter>doctype</parameter> (optional) </attribute>
          <attribute>
            <parameter>doctype-system</parameter> (optional) </attribute>
          <attribute>
            <parameter>page-subclass</parameter> (optional) </attribute>
          <attribute>
            <parameter>file-name</parameter> (optional) </attribute>
          <attribute>
            <parameter>no-script-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_page">
    <title>Description</title>
    <para>The container for the rest of the vspx code.
The page or a subclass of it will be the outermost VSPX element  on any VSPX page.
Each .vspx file defines explicitly one custom page class derived from vspx_page.
This element can enclose all HTML elements or can be incorporated in it&#39;s children on place apropriate for
rendering the VSPX controls, but one VSPX page must contain only one vspx:page element. and noe VSPX-specific element may appear outside the vspx:page. It can be placed in other HTML stuff or around it, does not matter, but VSP &amp; VSPX code must be inside it (the same applies to customized HTML attributes, i.e. containing &lt;?V &amp; &lt;?U shortcuts).
Note that when using &#39;include&#39; or &#39;decoration&#39; features the top level page element will be : in case of include - &#39;this&#39; page, in case of &#39;decoration&#39; - the decoration page.
Also page variables, controls will be combined in all cases of inclusion or macro-expansion, so their names must not be duplicated; this means that names of variables introduced by macro expansion or inclusion must not conflict with cnames of variables or controls in the top level page or any included or macro content.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_page">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of subclass of vspx_page to be generated. The name of class will be prefixed with &#39;page_&#39; plus that name.
</para>
  </formalpara>
  <formalpara>
      <title>decor</title>
      <para>This attribute specifies a &#39;decoration&#39; page URL. The decoration page is a VSPX page that is wrapped around the including page.  The content of the including page is then put in the place indicated by a placeholder element in the decor page.  This is useful for defining enclosing tables, headers, footers and other repeating content.
</para>
  </formalpara>
  <formalpara>
      <title>style</title>
      <para>This designates an external XSL-T style sheet to be apply over the page, before page compilation.  This is useful as a &#39;macro&#39; feature.  The XSLT sheet may define rules for macroexpanding things in the page body.
	  </para>
  </formalpara>
  <formalpara>
      <title>on-error-redirect</title>
      <para>This specifies where to redirect the HTTP client in the event of an  an unhandled error.
This  will pass a __SQL_STATE, __SQL_MESSAGE and __PAGE as parameters to the error page.
</para>
  </formalpara>
  <formalpara>
      <title>on-deadlock-retry</title>
      <para>This specifies how many times to retry page execution upon deadlock.
When the number of retries is reached, the behaviour will be as for other SQL errors.
</para>
  </formalpara>
  <formalpara>
      <title>doctype</title>
      <para>This is to specify the resulting document type declaration (DTD) public URI.
</para>
  </formalpara>
  <formalpara>
      <title>doctype-system</title>
      <para>This is to specify the resulting document type declaration (DTD) system URI.
</para>
  </formalpara>
  <formalpara>
   <title>page-subclass = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of page subclass to be instantiated for processing.
		The subclass with this name MUST already be  defined.
		The subclass definition can be kept in a code-behind file (see code-file element).
</para>
  </formalpara>
  <formalpara>
      <title>file-name</title>
      <para>The name of page to be generated.
	    Used by wizards to designate where generated page will be stored.
	    This attribute do not affect VSPX processing.
</para>
  </formalpara>
  <formalpara>
      <title>no-script-function</title>
      <para>A function to enable or disable automatic NOSCRIPT element generation.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_page">
    <title>Declaration of type vspx_page</title>
    <para>
 VSPX Page Class , from it must be derived all VSPX pages, no subcalsses for others
</para>
    <screen>
create type vspx_page under vspx_control
as (
    vc_view_state any,
    vc_is_postback int default 0,
    vc_persisted_vars any,
    vc_event vspx_event,
    vc_is_valid int default 1,          -- set to 0 when first validator fails
    vc_authenticated int default 0,     -- is true if login control in the page suceeded
    vc_current_id int default 0,
    vc_browser_caps any default 0,
    vc_authentication_mode int default 1, -- authentication mode 0 - cookie, 1 - url, 2 - digest
    vc_debug_log_acc any default null	-- The accumulator in xte_nodebld_... style for keeping debugging info.
    )  temporary self as ref
  method vc_state_deserialize (stream any, n int) returns any,
  method vc_get_debug_log (title varchar) returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_page">
    <title>Examples</title>
   <example id="vc_ex_page__0">
      <title>
  Sample VSPX page
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: page__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  



</para>
      <screen>
&lt;v:page name=&quot;page__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;&lt;title&gt;VSPX samples | v:page&lt;/title&gt;&lt;/head&gt;
    &lt;body&gt;
      &lt;p&gt;This VSPX page does nothing.&lt;br/&gt;
It does not even print traditional &#39;Hello world&#39; phrase.&lt;/p&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_1/simple.vspx">VX-S-1</ulink>
   </para>
   <para>
      <ulink url="/tutorial/web/vx_s_8/formsty.vspx">VX-S-8</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_param">
  <refmeta>
    <refentrytitle>param</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>param</refname>
    <refpurpose>Named parameter for the cursor.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_param">
    <funcprototype id="vc_proto_param">
        <funcdef>
            &lt;<function>param</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>value</parameter> (required) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_param">
    <title>Description</title>
    <para>Named parameter for execution of the cursor select statement. This must be the name of a parameter for SQL statement specified, but without leading colon.</para>
  </refsect1>
  <refsect1 id="vc_attrs_param">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>Name of the parameter.</para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bound value of the parameter.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_placeholder">
  <refmeta>
    <refentrytitle>placeholder</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>placeholder</refname>
    <refpurpose>Placeholder for original page in the decoration page.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_placeholder">
    <funcprototype id="vc_proto_placeholder">
        <funcdef>
            &lt;<function>placeholder</function> <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_placeholder">
    <title>Description</title>
    <para>This marks the place in the decoration page where the content of the original page should be placed.</para>
  </refsect1>
  <refsect1 id="vc_attrs_placeholder">
    <title>Attributes</title>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_radio_button">
  <refmeta>
    <refentrytitle>radio-button</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>radio-button</refname>
    <refpurpose>Scriptable radio button.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_radio_button">
    <funcprototype id="vc_proto_radio_button">
        <funcdef>
            &lt;<function>radio-button</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>error-glyph</parameter> (optional) </attribute>
          <attribute>
            <parameter>auto-submit</parameter> (optional) </attribute>
          <attribute>
            <parameter>group-name</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-checked</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_radio_button">
    <title>Description</title>
    <para>is a scriptable version of HTML radio button.</para>
  </refsect1>
  <refsect1 id="vc_attrs_radio_button">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
      <title>error-glyph</title>
      <para>The character to be displayed near the resulting HTML input element if the test of v:validator of the element detects an error in the current value of the element.</para>
  </formalpara>
  <formalpara>
      <title>auto-submit</title>
      <para>Flag to auto submit the parent form if value of the control is changed.</para>
  </formalpara>
  <formalpara>
      <title>group-name</title>
      <para>When several  check boxes are to be grouped, this is the  name of the group. Upon  post the name of the group will be submitted  instead of the  than name of the control. This also will restrict in the group to have more than one button on</para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
      <title>initial-checked</title>
      <para>This flag specifies whther this control is initially checked.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_radio_button">
    <title>Declaration of type vspx_radio_button</title>
    <para>
</para>
    <screen>
create type vspx_radio_button under vspx_field
temporary self as ref
constructor method vspx_radio_button (name varchar, parent vspx_control),
overriding method vc_view_state (stream any, n int) returns any,
overriding method vc_set_view_state (e vspx_event) returns any,
overriding method vc_render () returns any,
overriding method vc_xrender () returns any,
overriding method vc_set_model () returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_radio_button">
    <title>Examples</title>
   <example id="vc_ex_radio_button__0">
      <title>
  Groups of radio buttons.
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: radio_button__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form contains two groups of radio buttons, three button in each group.

</para>
      <screen>
&lt;v:page name=&quot;radio_button__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:radio-button&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;GET&quot;&gt;
	&lt;input type=&quot;text&quot; name=&quot;qq&quot;/&gt;
        &lt;table&gt;
          &lt;tr&gt;
            &lt;td&gt;
              &lt;v:radio-button name=&quot;radio1&quot; group-name=&quot;radio_group_A&quot; value=&quot;--&#39;A-one&#39;&quot; initial-checked=&quot;1&quot;/&gt;
              &lt;v:radio-button name=&quot;radio2&quot; group-name=&quot;radio_group_A&quot; value=&quot;--&#39;A-two&#39;&quot;/&gt;
              &lt;v:radio-button name=&quot;radio3&quot; group-name=&quot;radio_group_A&quot; value=&quot;--&#39;A-three&#39;&quot;/&gt;
            &lt;/td&gt;
          &lt;/tr&gt;
          &lt;tr&gt;
            &lt;td&gt;
              &lt;v:radio-button name=&quot;radio4&quot; group-name=&quot;radio_group_B&quot; value=&quot;--&#39;B-one&#39;&quot; initial-checked=&quot;1&quot;/&gt;
              &lt;v:radio-button name=&quot;radio5&quot; group-name=&quot;radio_group_B&quot; value=&quot;--&#39;B-two&#39;&quot;/&gt;
              &lt;v:radio-button name=&quot;radio6&quot; group-name=&quot;radio_group_B&quot; value=&quot;--&#39;B-three&#39;&quot;/&gt;
            &lt;/td&gt;
          &lt;/tr&gt;
        &lt;/table&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; style=&quot;image&quot; xhtml:alt=&quot;A test button&quot; value=&quot;--&#39;plus.gif&#39;&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/radio.vspx">VX-S-2</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_radio_group">
  <refmeta>
    <refentrytitle>radio-group</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>radio-group</refname>
    <refpurpose>A group of radio-buttons.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_radio_group">
    <funcprototype id="vc_proto_radio_group">
        <funcdef>
            &lt;<function>radio-group</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>error-glyph</parameter> (optional) </attribute>
          <attribute>
            <parameter>auto-submit</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_radio_group">
    <title>Description</title>
    <para>
      This control is used to group containing radio-buttons in a group.
      This ensures that only one button is  selected  at a time.
      Note: This control is not mandatory for making  such group of
      buttons, another option is to use &#39;group-name&#39; attribute of the radio-button control.
      </para>
  </refsect1>
  <refsect1 id="vc_attrs_radio_group">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>error-glyph</title>
      <para>The character to be displayed near the resulting HTML input element if the test of v:validator of the element detects an error in the current value of the element.</para>
  </formalpara>
  <formalpara>
      <title>auto-submit</title>
      <para>Flag to auto submit the parent form if value of the control is changed.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
	  If nothing else is specified, the column meta data from the
	  containing update form sets the field&#39;s attributes.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_radio_group">
    <title>Declaration of type vspx_radio_group</title>
    <para>
</para>
    <screen>
create type vspx_radio_group under vspx_field
temporary self as ref
constructor method vspx_radio_group (name varchar, parent vspx_control),
method vc_choose_selected () returns any,
overriding method vc_xrender () returns any,
overriding method vc_set_model () returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_radio_group">
    <title>Examples</title>
   <example id="vc_ex_radio_group__0">
      <title>
  Groups of radio buttons.
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: radio_group__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form contains a groups of radio buttons, grouped with radio-group control.

</para>
      <screen>
&lt;v:page name=&quot;radio_group_demo&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
&lt;body&gt;
  &lt;v:form name=&quot;sf&quot; type=&quot;simple&quot; method=&quot;POST&quot;&gt;
     &lt;v:radio-group name=&quot;radio00&quot;&gt;
       &lt;v:radio-button name=&quot;radiob01&quot; value=&quot;--&#39;one&#39;&quot; /&gt;
       &lt;v:radio-button name=&quot;radiob02&quot; value=&quot;--&#39;two&#39;&quot; /&gt;
     &lt;/v:radio-group&gt;
  &lt;/v:form&gt;
&lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/radio_group.vspx">VX-S-2</ulink>
   </para>
   <para>
      <ulink url="/tutorial/web/vx_s_3/update_radio.vspx">VX-S-3</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_script">
  <refmeta>
    <refentrytitle>script</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>script</refname>
    <refpurpose>A (redundant) wrapper for SQL code, can be omitted.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_script">
    <funcprototype id="vc_proto_script">
        <funcdef>
            &lt;<function>script</function> <attribute>
            <parameter>language</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_script">
    <title>Description</title>
    <para>
This control can appear only inside event handling controls and it always contain SQL code to be executed when the event occurs.
There is no difference for VSPX compiler whether SQL code is enclosed in &#39;script&#39; control or not.
Some WYSIWYG tools can display the enclosed SQL code to the application developer according to custom attributes of this control
but it does not affect the generated Virtuoso/PL code of the page.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_script">
    <title>Attributes</title>
  <formalpara>
   <title>language = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>Denotes the type of language,
	    currently only Virtuoso/PL expressions are supported.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_select_list">
  <refmeta>
    <refentrytitle>select-list</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>select-list</refname>
    <refpurpose>Fixed initialized select list.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_select_list">
    <funcprototype id="vc_proto_select_list">
        <funcdef>
            &lt;<function>select-list</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>error-glyph</parameter> (optional) </attribute>
          <attribute>
            <parameter>auto-submit</parameter> (optional) </attribute>
          <attribute>
            <parameter>multiple</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_select_list">
    <title>Description</title>
    <para>This is a scriptable version of HTML select control.
It shows a static list of items (see item element). Databind and on-post scripts are allowed.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_select_list">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
      <title>error-glyph</title>
      <para>The character to be displayed near the resulting HTML input element if the test of v:validator of the element detects an error in the current value of the element.</para>
  </formalpara>
  <formalpara>
      <title>auto-submit</title>
      <para>Flag to auto submit the parent form if value of the control is changed.</para>
  </formalpara>
  <formalpara>
      <title>multiple</title>
      <para>Used to designate a multiple selection list box.
	    In this case the control&#39;s value will be an array of key data of selected items.
	  </para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_select_list">
    <title>Declaration of type vspx_select_list</title>
    <para>
</para>
    <screen>
create type vspx_select_list under vspx_field
as (
     vsl_items any,
     vsl_item_values any,
     vsl_selected_inx any default null,
     vsl_change_script int default 0,
     vsl_list_document any default null,
     vsl_list_match varchar default null,
     vsl_list_key_path varchar default null,
     vsl_list_value_path varchar default null,
     vsl_multiple int default 0
   )
  temporary self as ref
 overriding method vc_render () returns any,
 overriding method vc_view_state (stream any, n int) returns any,
 overriding method vc_set_view_state (e vspx_event) returns any,
 overriding method vc_set_model () returns any,
 overriding method vc_xrender () returns any,
 method vs_set_selected () returns any,
constructor method vspx_select_list (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_select_list">
    <title>Examples</title>
   <example id="vc_ex_select_list__0">
      <title>
  A simple static select list
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: select_list__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form of the sample page contains a list of three items.

</para>
      <screen>
&lt;v:page name=&quot;select_list__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:select-list&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:select-list name=&quot;sel_list&quot;&gt;
          &lt;v:item name=&quot;*default*&quot; value=&quot;0&quot;/&gt;
          &lt;v:item name=&quot;FIRST&quot; value=&quot;1&quot;/&gt;
          &lt;v:item name=&quot;SECOND&quot; value=&quot;2&quot;/&gt;
        &lt;/v:select-list&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; value=&quot;OK&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/select.vspx">VX-S-2</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_style">
  <refmeta>
    <refentrytitle>style</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>style</refname>
    <refpurpose>A markup tag for use by &#39;macro stylesheets&#39;.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_style">
    <funcprototype id="vc_proto_style">
        <funcdef>
            &lt;<function>style</function> <attribute>
            <parameter>name</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_style">
    <title>Description</title>
    <para>This control marks the enclosed content for special processing in the &#39;macro stylesheet&#39; whose name is specified by &#39;style&#39; attribute of v:page element.</para>
  </refsect1>
  <refsect1 id="vc_attrs_style">
    <title>Attributes</title>
  <formalpara>
      <title>name</title>
      <para>Optional name of the control which could be used
	    in the macro expansion stylesheet assigned.
	  </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
</refentry>
 <refentry id="vc_tab">
  <refmeta>
    <refentrytitle>tab</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>tab</refname>
    <refpurpose>Selects one of its children to be active at any one time.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_tab">
    <funcprototype id="vc_proto_tab">
        <funcdef>
            &lt;<function>tab</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-active</parameter> (optional) </attribute>
          <attribute>
            <parameter>style</parameter> (optional) </attribute>
          <attribute>
            <parameter>active</parameter> (optional) </attribute>
          <attribute>
            <parameter>is-input</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_tab">
    <title>Description</title>
    <para>
A container that contains some number of pages and displays them one by one.
This can be used for multi-page forms or Windows style tabbed decks or making multi-part forms, alternative visualizations of the same data etc.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_tab">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>initial-active = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>
This is the name of the child template which is active at the time and
which thus will be rendered.  Whether inactive templates are
instantiated and keep state is controlled by is-input.  The active
attribute initializes the tb_active member of the vspx_tab instance.
This is preserved in the view state. Data bindable.
			    </para>
  </formalpara>
  <formalpara>
      <title>style</title>
      <para>
This determines what HTML control is used to select which child is shown.
If unspecified, there will be no such control and the program logic is responsible for flipping the pages.  Otherwise  &quot;list&quot; means there is a HTML select control showing the titles  of the tabs.  &quot;radio&quot; means the titles of the tabs are shown as a radio group.  If there is a tab selector widget, it is always above the tabs.
			    </para>
  </formalpara>
  <formalpara>
   <title>active = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A data bound value to enable or disable the tab switch.
	    The default is &#39;1&#39; meaning &#39;enable&#39;.</para>
  </formalpara>
  <formalpara>
      <title>is-input</title>
      <para>If true, all the children are considered to be collectively a
	    multipart form and each will be instantiated when the page is made and
	    will get to retain a view state.  Although only one page of the form
	    is shown at a time, the state of all is kept. Not data bindable.
	    The default is &#39;1&#39; meaning &#39;template contains input&#39;.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_tab">
    <title>Declaration of type vspx_tab</title>
    <para>
Tab Deck
</para>
    <screen>
create type vspx_tab under vspx_form
as
   (
     tb_active vspx_template,
     tb_is_input int default 0,
     tb_style varchar
   )
    temporary self as ref
   constructor method vspx_tab (name varchar, parent vspx_control),
   --overriding method vc_render () returns any,
   overriding method vc_set_view_state (e vspx_event) returns any,
   overriding method vc_view_state (stream any, n int) returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_tab">
    <title>Examples</title>
   <example id="vc_ex_tab__0">
      <title>
  Switching of page content
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: tab__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The sample page contains three templates; only one of three is shown and user can switch them to change the visible content of the page.

</para>
      <screen>
&lt;v:page name=&quot;tab__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;&lt;title&gt;VSPX samples | v:tab&lt;/title&gt;&lt;/head&gt;
    &lt;body&gt;
      &lt;v:tab name=&quot;tab&quot; initial-active=&quot;template1&quot; style=&quot;list&quot; is-input=&quot;0&quot;&gt;
        &lt;v:template name=&quot;template1&quot; type=&quot;simple&quot;&gt;This is a first template&lt;/v:template&gt;
        &lt;v:template name=&quot;template2&quot; type=&quot;simple&quot;&gt;This is a second template&lt;/v:template&gt;
        &lt;v:template name=&quot;template3&quot; type=&quot;simple&quot;&gt;This is a third template&lt;/v:template&gt;
      &lt;/v:tab&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_5/tab.vspx">VX-S-5</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_template">
  <refmeta>
    <refentrytitle>template</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>template</refname>
    <refpurpose>Container for a group of controls and/or HTML code.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_template">
    <funcprototype id="vc_proto_template">
        <funcdef>
            &lt;<function>template</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>type</parameter> (optional) </attribute>
          <attribute>
            <parameter>redirect</parameter> (optional) </attribute>
          <attribute>
            <parameter>condition</parameter> (optional) </attribute>
          <attribute>
            <parameter>name-to-remove</parameter> (optional) </attribute>
          <attribute>
            <parameter>set-to-remove</parameter> (optional) </attribute>
          <attribute>
            <parameter>title</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_template">
    <title>Description</title>
    <para>The container for any optional, repeatable or otherwise grouped controls or code. The type modifier is used to specify special kind of templates (i.e. repeatable content or tree node representation)</para>
  </refsect1>
  <refsect1 id="vc_attrs_template">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>type</title>
      <para>The behaviour of the template.</para>
   <table>
        <title>Allowed values of the &#39;type&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>simple</entry>
       <entry>
                <para>The template contains an arbitrary number of controls and HTML tags and  groups them together to control their processing, e.g. to enable or disable them altogether depending on some condition.</para>
       </entry>
      </row>
      <row>
              <entry>repeat</entry>
       <entry>
                <para>A repeating row of v:data-set. The template of this type will be repeated for each row in the window of the data-set. It will be instantiated, data bound, rendered.  If the template contains forms and submits, they get the post method called as one would expect.
On data binding, the parent of the template has its dg_current_row data member set to an array representing the selected row from left to right.
</para>
       </entry>
      </row>
      <row>
              <entry>row</entry>
       <entry>
                <para>A repeating row of v:data-grid. The template of this type will be repeated for each row in the window of the v:data-grid. It will be instantiated, data bound, rendered.  If the template contains forms and submits, they get the post method called as one would expect.
On data binding, the parent of the template has its dg_current_row data member set to an array representing the selected row from left to right.
</para>
                <para>
The controls under this template (such as text, label, button etc.) can access data in current row in order as columns are given by referencing te_rowset member of row template.
</para>
       </entry>
      </row>
      <row>
              <entry>frame</entry>
       <entry>
                <para>
A non-repeating static content of v:data-grid.
Content of this template represents view in page when rows are selected,
position of scroll buttons, rowset and form for adding a record.
</para>
       </entry>
      </row>
      <row>
              <entry>if-exists</entry>
       <entry>
                <para>
Template that is enabled only if the resultset is not empty in v:data-set.
</para>
       </entry>
      </row>
      <row>
              <entry>if-not-exists</entry>
       <entry>
                <para>Template that is enabled only if the resultset is empty in v:data-set.</para>
       </entry>
      </row>
      <row>
              <entry>add</entry>
       <entry>
                <para>Template that is enabled when user adds new record in the resultset in v:data-set (if the resultset is not read-only).
Similarly to templates of type &#39;edit&#39;, the &#39;add&#39; template contains a vspx:form of type &#39;update&#39; that is used to allow adding of rows in table as specified.
Usually this form is a vspx_form + vspx_text constrained to columns and table selected in SQL expression of the parent vspx:data-set control with value of key attributes set to null. Please remember to set the &#39;if-not-exists&#39; attribute of the form to &#39;insert&#39;.</para>
       </entry>
      </row>
      <row>
              <entry>browse</entry>
       <entry>
                <para>This type is meaningful only for templates right inside templates of type &#39;repeat&#39;. When the template of type &#39;repeat&#39; is used multiple times to display every row of a data-set, the template of type &#39;browse&#39; expands only for those rows that are not currently editable.
</para>
       </entry>
      </row>
      <row>
              <entry>edit</entry>
       <entry>
                <para>Template that is enabled when user edits an existing record in the resultset in v:data-set (if the resultset isnot read-only and if the &#39;edit&#39; attribute of v:data-set is set to &#39;true&#39;).
The template of this type usually contains a vspx:form of type &#39;update&#39;;
the &#39;table&#39; attribute of the form is the name of the table from &#39;sql&#39; attribute of the v:data-set where the &#39;edit&#39; template is located; controls of the form are usually constrained to columns of the SQL expression of that &#39;sql&#39; attribute.</para>
       </entry>
      </row>
      <row>
              <entry>if-login</entry>
       <entry>
                <para>Template that is enabled when user is logged in (e.g. for use in v:login. If the login is valid, the contents of this child will be instantiated.  This can be for example a button with &#39;action&#39; attribute set to &#39;logout&#39;, a welcome message or such.  When using the vspx:login system, the user name is is obtained by connection_get (&#39;vspx_user&#39;).</para>
       </entry>
      </row>
      <row>
              <entry>if-not-login</entry>
       <entry>
                <para>Template that is enabled when user is not yet logged in or is already logged out (e.g. for use in v:login.
The template specifies what to do if there are no credentials with the page.
If the &#39;redirect&#39; attribute is given, then the entire page containing
this is not processed at all but instead the page specified in the url
is processed instead, with the context being that of the invocation of
this page.  The redirect page can thus ask for the login and having
checked it return to this page, since it knows the url for this.  In
this way it is possible to bookmark places of which the uri&#39;s may
expire, and accessing an expired place will just prompt for the login
before going to the page.


If the redirect is not specified, the content of the template is instantiated and shown. The content can be arbitrary, e.g. the vspx:login-form control can appear here, providing a standard login form that prompts for a user name and password and has a submit button.</para>
       </entry>
      </row>
      <row>
              <entry>tree-node</entry>
       <entry>
                <para>
Template for internal nodes of the tree in v:tree (i.e. for nodes with children).
</para>
       </entry>
      </row>
      <row>
              <entry>tree-leaf</entry>
       <entry>
                <para>Template for terminal nodes of the tree in v:tree (i.e. for nodes without children).</para>
       </entry>
      </row>
      <row>
              <entry>input</entry>
       <entry>
                <para>Template for input the SQL statement to execute it interactively in v:isql element.</para>
       </entry>
      </row>
      <row>
              <entry>result</entry>
       <entry>
                <para>Template to show if v:isql returns result without an error.</para>
       </entry>
      </row>
      <row>
              <entry>error</entry>
       <entry>
                <para>Template to be shown by v:isql if the user entered the SQL query and the execution of this query caused an error.</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
      <title>redirect</title>
      <para>The URL to which the user agent is redirected if not authenticated, applicable only when type is &#39;if-no-login&#39;.</para>
  </formalpara>
  <formalpara>
   <title>condition = <link linkend="vc_type_SqlCode">SqlCode</link>
   </title>
      <para>This is a SQL expression to be tested for rendering the template</para>
  </formalpara>
  <formalpara>
      <title>name-to-remove</title>
      <para>This works together with set-to-remove, see next.</para>
  </formalpara>
  <formalpara>
      <title>set-to-remove</title>
      <para>This combined with name-to-remove gives posibility to remove a HTML elements from output.</para>
   <table>
        <title>Allowed values of the &#39;set-to-remove&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>none</entry>
       <entry>
                <para>The rendered output of the enclosing template will not be affected by the &#39;name-to-remove&#39; attribute of the template.</para>
       </entry>
      </row>
      <row>
              <entry>top</entry>
       <entry>
                <para>The rendered output of the enclosing template should not contain the first opening tag whose name is equal to the value of &#39;name-to-remove&#39; attribute of the template.</para>
       </entry>
      </row>
      <row>
              <entry>bottom</entry>
       <entry>
                <para>
The rendered output of the enclosing template should not contain the last closing tag whose name is equal to the value of &#39;name-to-remove&#39; attribute of the template.
</para>
       </entry>
      </row>
      <row>
              <entry>both</entry>
       <entry>
                <para>
The rendered output of the enclosing template should not contain the both the first opening tag and the last closing tag whose name is equal to the value of &#39;name-to-remove&#39; attribute of the template.
</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
      <title>title</title>
      <para>When used inside tab control, this is used to show as label of the selector</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_template">
    <title>Declaration of type vspx_template</title>
    <para>
</para>
    <screen>
create type vspx_template under vspx_control
  temporary self as ref
 constructor method vspx_template (name varchar, parent vspx_control)
</screen>
  </refsect1>
</refentry>
 <refentry id="vc_text">
  <refmeta>
    <refentrytitle>text</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>text</refname>
    <refpurpose>Scriptable, data-bindable input control.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_text">
    <funcprototype id="vc_proto_text">
        <funcdef>
            &lt;<function>text</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>error-glyph</parameter> (optional) </attribute>
          <attribute>
            <parameter>auto-submit</parameter> (optional) </attribute>
          <attribute>
            <parameter>type</parameter> (optional) </attribute>
          <attribute>
            <parameter>default</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>default-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>default_value</parameter> (optional) </attribute>
          <attribute>
            <parameter>format</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_text">
    <title>Description</title>
    <para>Text input, with scripts and validation options but no implied database binding. String input of the HTML form.</para>
  </refsect1>
  <refsect1 id="vc_attrs_text">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
      <title>error-glyph</title>
      <para>The character to be displayed near the resulting HTML input element if the test of v:validator of the element detects an error in the current value of the element.</para>
  </formalpara>
  <formalpara>
      <title>auto-submit</title>
      <para>Flag to auto submit the parent form if value of the control is changed.</para>
  </formalpara>
  <formalpara>
      <title>type</title>
   <table>
        <title>Allowed values of the &#39;type&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>plain</entry>
       <entry>
                <para>The value is displayed in a usual way and user can edit it. This is the default value.</para>
       </entry>
      </row>
      <row>
              <entry>password</entry>
       <entry>
                <para>The value is not shown on the screen to prevent occasional reading, only astericks are shown in the input field.</para>
       </entry>
      </row>
      <row>
              <entry>hidden</entry>
       <entry>
                <para>The text is passed to the target page without displaying it to the user.</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>default = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The default value of input field.</para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
   <title>default-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is an expression for setting the default value of the text.</para>
  </formalpara>
  <formalpara>
   <title>default_value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is deprecated alias for &#39;default-value&#39; attribute (note the difference between minus sign and underscore).</para>
  </formalpara>
  <formalpara>
   <title>format = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_text">
    <title>Declaration of type vspx_text</title>
    <para>
</para>
    <screen>
create type vspx_text under vspx_field
as
 (
   tf_default varchar default &#39;&#39;,
   tf_style any default 0 -- 0 is text, 1 is password, 2 is hidden
 )
 temporary self as ref
  overriding method vc_render () returns any,
  overriding method vc_set_view_state (e vspx_event) returns any,
  overriding method vc_view_state (stream any, n int) returns any,
  overriding method vc_set_model () returns any,
  overriding method vc_xrender () returns any,
  constructor method vspx_text (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_text">
    <title>Examples</title>
   <example id="vc_ex_text__0">
      <title>
  Simple text input
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: text__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form contains text input control with &#39;Hello&#39; string inside. User can edit the string and submit the changed value

</para>
      <screen>
&lt;v:page name=&quot;text__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:text&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:text name=&quot;txt01&quot; default=&quot;Hello&quot;/&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; value=&quot;OK&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_textarea">
  <refmeta>
    <refentrytitle>textarea</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>textarea</refname>
    <refpurpose>Scriptable text-area input.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_textarea">
    <funcprototype id="vc_proto_textarea">
        <funcdef>
            &lt;<function>textarea</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>error-glyph</parameter> (optional) </attribute>
          <attribute>
            <parameter>auto-submit</parameter> (optional) </attribute>
          <attribute>
            <parameter>type</parameter> (optional) </attribute>
          <attribute>
            <parameter>default_value</parameter> (optional) </attribute>
          <attribute>
            <parameter>default</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_textarea">
    <title>Description</title>
    <para>Scriptable, databindable   HTML text area.</para>
  </refsect1>
  <refsect1 id="vc_attrs_textarea">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
      <title>error-glyph</title>
      <para>The character to be displayed near the resulting HTML input element if the test of v:validator of the element detects an error in the current value of the element.</para>
  </formalpara>
  <formalpara>
      <title>auto-submit</title>
      <para>Flag to auto submit the parent form if value of the control is changed.</para>
  </formalpara>
  <formalpara>
      <title>type</title>
   <table>
        <title>Allowed values of the &#39;type&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>plain</entry>
       <entry>
                <para>The value is displayed in a usual way and user can edit it. This is the default value.</para>
       </entry>
      </row>
      <row>
              <entry>password</entry>
       <entry>
                <para>The value is not shown on the screen to prevent occasional reading, only astericks are shown in the input field.</para>
       </entry>
      </row>
      <row>
              <entry>hidden</entry>
       <entry>
                <para>The text is passed to the target page without displaying it to the user.</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>default_value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The default value of the field. Can be accessed via control.ufl_value n data bind stage.</para>
  </formalpara>
  <formalpara>
   <title>default = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Deprecated alias of &#39;default_value&#39;.</para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_textarea">
    <title>Declaration of type vspx_textarea</title>
    <para>
</para>
    <screen>
create type vspx_textarea under vspx_text  temporary self as ref
  constructor method vspx_textarea (name varchar, parent vspx_control),
  overriding method vc_xrender () returns any,
  overriding method vc_render () returns any
</screen>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/textarea.vspx">VX-S-2</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_tree">
  <refmeta>
    <refentrytitle>tree</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>tree</refname>
    <refpurpose>A container for displaying a tree of nested nodes.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_tree">
    <funcprototype id="vc_proto_tree">
        <funcdef>
            &lt;<function>tree</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>show-root</parameter> (optional) </attribute>
          <attribute>
            <parameter>multi-branch</parameter> (required) </attribute>
          <attribute>
            <parameter>orientation</parameter> (required) </attribute>
          <attribute>
            <parameter>root</parameter> (required) </attribute>
          <attribute>
            <parameter>child-function</parameter> (required) </attribute>
          <attribute>
            <parameter>start-path</parameter> (required) </attribute>
          <attribute>
            <parameter>open-at</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_tree">
    <title>Description</title>
    <para>
    <para>This can be used for hierarchical tables of contents,
    directory browsing, hierarchical menus and such.
    The tree can have either one or more branches open at any time, up to
    the leaves.  The tree has a root, which may or may not be visible.
    The contents of the tree can either be fixed, in which case these are an
    XML tree, or dynamic, in which case these are generated level by level
    by SQL functions attached to the tree. The tree can have various external appearences.</para>

    <para>The tree is represented at run time by a vspx_tree instance.
    Nodes of the tree are represented by vspx_tree_node objects,
    which are childs of the vspx_tree.  The nodes hold an identifier (vc_instance_name)
    of the corresponding tree branch, which is used to retrieve children of the node.
    These also hold a flag (tn_open member) indicating if the node is open or not.</para>
			</para>
  </refsect1>
  <refsect1 id="vc_attrs_tree">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>show-root</title>
      <para>This attribute is obsolete and has no effect.</para>
  </formalpara>
  <formalpara>
      <title>multi-branch</title>
      <para>
This determines whether more than one branches can be open at one time.
The values are 0 and 1 (true and false).  The default is 0 (false).
			   </para>
  </formalpara>
  <formalpara>
      <title>orientation</title>
      <para>
      This can be &#39;horizontal&#39; or &#39;vertical&#39;, the default is &#39;vertical&#39;.
      The tree can have different styles.  The default is a vertical arrangement
      with open levels indented, the children under the parent node.
      Each node template is a single line.  The horizontal style shows each level on a separate line.
      In this case it is not allowed multiple open branches.  The children of the root will be
      shown on one line.  When one is opened, its children will fill the next line.
			   </para>
  </formalpara>
    <formalpara>
   <title>root = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>
This is a SQL expression which produces the root object.
This can be of any data type, a file system path is an example.
</para>
<programlisting>

create procedure root_node (in path varchar)
{
  declare i, l int;
  declare ret, arr any;
  arr :=
    vector_concat (sys_dirlist (path, 0), sys_dirlist (path, 1));

  return arr;
};
</programlisting>
</formalpara>
    <formalpara>
   <title>child-function = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
<para>Given the result of the root expression, this must generate an array
of similar elements corresponing to the children of the node in
question.  This same function should be applicable to each element of
the array it returns.  If the array is empty then the node in question
is a leaf.</para>
<programlisting>


-- Example of this function

create procedure child_node (in node_name varchar, in node varchar)
{
  declare i, l int;
  declare ret, arr any;
  declare exit handler for sqlstate &#39;*&#39;
    {
      return vector ();
    };
  if (isstring (file_stat (node_name, 3)))
    return vector ();

  arr :=
    vector_concat (sys_dirlist (node_name, 0), sys_dirlist (node_name, 1));

  return arr;
}
;
</programlisting>
</formalpara>
  <formalpara>
   <title>start-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is an expression which will be evaluated and passed to the &#39;root&#39; function as argument.
                    </para>
  </formalpara>
  <formalpara>
   <title>open-at = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is an expression which will be used as XPath
	    expression to designate which branches of the tree are open
	    and which are not initially.
                    </para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_tree">
    <title>Declaration of type vspx_tree</title>
    <para>
</para>
    <screen>
create type vspx_tree under vspx_control
as
  (
    vt_current_node int default -1,
    vt_node any default null,
    vt_open_at varchar default null,
    vt_xpath_id varchar default null
  )
temporary self as ref
overriding method vc_view_state (stream any, n int) returns any,
method vc_get_state () returns any,
method vc_open_at (path varchar) returns any,
constructor method vspx_tree (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_tree">
    <title>Examples</title>
   <example id="vc_ex_tree__0">
      <title>
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: tree__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  

</para>
      <screen>
&lt;v:page name=&quot;demo_tree&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
&lt;html&gt;
 &lt;body&gt;
 &lt;v:form name=&quot;f1&quot; method=&quot;POST&quot; type=&quot;simple&quot;&gt;
 &lt;div&gt;
 &lt;v:tree name=&quot;tree1&quot; multi-branch=&quot;1&quot; orientation=&quot;vertical&quot;
         root=&quot;root_node&quot; start-path=&quot;.&quot; child-function=&quot;child_node&quot; &gt;
  &lt;v:node-template name=&quot;node_tmpl&quot;&gt;
    &lt;div STYLE=&quot;margin-left:1em;&quot;&gt;
	&lt;v:button name=&quot;tree1_toggle&quot; action=&quot;simple&quot; style=&quot;image&quot; value=&quot;--case (control.vc_parent as vspx_tree_node).tn_open when 0 then &#39;plus.gif&#39; else &#39;minus.gif&#39; end&quot; /&gt;
	&lt;b&gt;&lt;v:label name=&quot;label1&quot; value=&quot;--(control.vc_parent as vspx_tree_node).tn_value&quot; /&gt;&lt;/b&gt;
	&lt;v:node /&gt;
    &lt;/div&gt;
  &lt;/v:node-template&gt;
  &lt;v:leaf-template name=&quot;leaf_tmpl&quot;&gt;
    &lt;div STYLE=&quot;margin-left:1em;&quot;&gt;
	&lt;v:label name=&quot;label2&quot; value=&quot;--(control.vc_parent as vspx_tree_node).tn_value&quot; /&gt;
    &lt;/div&gt;
  &lt;/v:leaf-template&gt;
 &lt;/v:tree&gt;
 &lt;/div&gt;
 &lt;/v:form&gt;
 &lt;/body&gt;
&lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_4/tree.vspx">VX-S-4</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_url">
  <refmeta>
    <refentrytitle>url</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>url</refname>
    <refpurpose>Generic scriptable hypertext link.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_url">
    <funcprototype id="vc_proto_url">
        <funcdef>
            &lt;<function>url</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>column</parameter> (optional) </attribute>
          <attribute>
            <parameter>null-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-value</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-place</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-path</parameter> (optional) </attribute>
          <attribute>
            <parameter>element-update-params</parameter> (optional) </attribute>
          <attribute>
            <parameter>fmt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>cvt-function</parameter> (optional) </attribute>
          <attribute>
            <parameter>format</parameter> (optional) </attribute>
          <attribute>
            <parameter>url</parameter> (required) </attribute>
          <attribute>
            <parameter>active</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_url">
    <title>Description</title>
    <para>Dynamic data bindable hypertext link.</para>
  </refsect1>
  <refsect1 id="vc_attrs_url">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
   <title>column = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of the column bound.
If nothing else is specified, the column meta data from the containing update form sets the field&#39;s attributes.
</para>
  </formalpara>
  <formalpara>
      <title>null-value</title>
      <para>This value will be shown if value of the column is NULL, also
	      value of the control will be set to null if this value is passed upon POST request.
	  </para>
  </formalpara>
  <formalpara>
   <title>value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Data bindable value of control, represents value of HTML control to be drawn.
The calculated value of this attribute is stored in the control in ufl_value field.
</para>
  </formalpara>
  <formalpara>
   <title>element-value = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>An XML entity that contains a value to be displayed by an HTML control.
The calculated value is stored in ufl_element_value field of the control.
This value is used only if ufl_value is null (e.g. if the &#39;value&#39; attribute is not set at all), and the method vc_get_value_from_element() will be used to calculate ufl_value based on ufl_element_value, ufl_element_path and ufl_element_place.
</para>
  </formalpara>
  <formalpara>
   <title>element-place = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>The place of actual data inside an XML element. The calculated value of this attribute is stored in ufl_element_place field of the control. This is to process XMLSchema-compatible data without writing extra code for handling NULL values. The XML element can contain the value to be bound in either attribute or in an inner text node. XMLSchema treats missing attributes as NULL values. missing text node as an empty string value and if &#39;xsi:nil&#39; attribute is &#39;true&#39; then inner text value is NULL no matter if there are any text nodes. These self-evident rules are convenient for XQuery data retrieval but not for data update: an result of some XQuery expression can point to data but not to a place where data should occur in the future.
The use of &#39;element-place&#39; allows to eliminate the problem. Attributes &#39;element-value&#39;, &#39;element-path&#39; and &#39;element-update-path&#39; may locate an element that is always present whereas &#39;element-place&#39; describes where the desired datum will occur in the element.
The value of this attribute should be a string of syntax &#39;@attributename&#39; or &#39;text()&#39;. If this is &#39;@attributename&#39; then the effective bound value is a value of the specified attribute or NULL if the specified attribute is missing. On update, either the attribute is created/edited in order to set non-NULL value or the attribute is deleted in order to set NULL.
If text() is specified then both text value of the element and the value of its &#39;xsi:nil&#39; are properly handled on both data bind and update.</para>
  </formalpara>
  <formalpara>
   <title>element-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the path inside the entity that comes from &#39;element-value&#39; attribute. The default path is &#39;self::node()&#39;. This path is used to point precisely to an subentity that should actually be used for data binding. The calculated value of this attribute should be a string in XQuery syntax, and it is saved in ufl_element_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-path&#39; attribute is missing. The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-path = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Like the value of &#39;element-path&#39;, this is the path inside the entity that comes from &#39;element-value&#39; attribute. The difference is that &#39;element-path&#39; is used inside &#39;vc_get_value_from_element() during data-bind to set ufl_value based on ufl_element_value whereas &#39;element-update-path&#39; is used during data update inside &#39;vc_put_value_to_element() in order to save data inside the document that is referenced by ufl_element_value. The default path for update is equal to the path for data bind, i.e. it is the value of the calculated &#39;element-path&#39; attribute or &#39;self::node()&#39;. The calculated value of &#39;element-update-path&#39; should be a string in XQuery syntax, and it is saved in ufl_element_update_path member of the control.</para>
  </formalpara>
  <formalpara>
   <title>element-update-params = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is the vector of parameter values of the path specified by &#39;element-update-path&#39; attribute. The default is NULL indicating no parameters. The attribute is calculated but not used if &#39;element-update-path&#39; attribute is missing (e.g. you should not try to specify &#39;element-path&#39; without &#39;element-update-path&#39; and both &#39;element-params&#39; and &#39;element-update-params&#39; in hope that values from &#39;element-update-params&#39; will be passed to &#39;element-path&#39; on update). The calculated value of this attribute should be either NULL or a vector of even length whose items are parameter names and parameter values; refer to the description of xquery_eval() function for more details. The value of the attribute is saved in ufl_element_update_params member of the control.</para>
  </formalpara>
  <formalpara>
   <title>fmt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert the value that is bound to the control into a string to use during the rendering. The value of this attribute should be a name of function that takes a single argument of the type that matches the type of ufl_value and returns a string. If this is used then the value of &#39;cvt-function&#39; should probably be a name of function that converts the string back to the desired data type.
If a control supports &#39;format&#39; attribute then the format is applied to the result of &#39;fmt-function&#39;, so the value returned by fmt-function may be e.g. an integer to be formatted by &#39;%d&#39; format.
The calculated value of this attribute is stored in ufl_fmt_fn field of the control.</para>
  </formalpara>
  <formalpara>
   <title>cvt-function = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>This is to convert a user input of type varchar into a value that should be stored in ufl_value (and e.g. placed into some database column by an update).
The calculated value of this attribute is stored in ufl_cvt_fn field of the control.
For more details, see the description of &#39;fmt_function&#39; attribute above.</para>
  </formalpara>
  <formalpara>
      <title>format</title>
      <para>A sprintf format string for printing the value</para>
  </formalpara>
  <formalpara>
   <title>url = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A data bound value to be printed in place of href attribute.</para>
  </formalpara>
  <formalpara>
   <title>active = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>A data bound value to enable or disable the url. The default is &#39;1&#39; meaning &#39;enable&#39;.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_url">
    <title>Declaration of type vspx_url</title>
    <para>
</para>
    <screen>
create type vspx_url under vspx_field
as
  (
    vu_format varchar default &#39;%s&#39;,
    vu_url varchar default &#39;&#39;,
    vu_l_pars varchar default &#39;&#39;,
    vu_is_local int default 0
  )
temporary self as ref
overriding method vc_render () returns any,
constructor method vspx_url (name varchar, parent vspx_control)
</screen>
  </refsect1>
  <refsect1 id="vc_ex_url">
    <title>Examples</title>
   <example id="vc_ex_url__0">
      <title>
  Simple dynamic link
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: url__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This draws an anchor in browser screen.

</para>
      <screen>
&lt;v:page name=&quot;url__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;&lt;title&gt;VSPX samples | v:url&lt;/title&gt;&lt;/head&gt;
    &lt;body&gt;
	&lt;v:url name=&quot;url0&quot; value=&quot;--&#39;index&#39;&quot; url=&quot;--&#39;index.vspx&#39;&quot; format=&quot;A link to page with name %s and extension VSPX&quot; /&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_validator">
  <refmeta>
    <refentrytitle>validator</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>validator</refname>
    <refpurpose>A validator that is applied to user input.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_validator">
    <funcprototype id="vc_proto_validator">
        <funcdef>
            &lt;<function>validator</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>test</parameter> (required) </attribute>
          <attribute>
            <parameter>min</parameter> (optional) </attribute>
          <attribute>
            <parameter>max</parameter> (optional) </attribute>
          <attribute>
            <parameter>regexp</parameter> (optional) </attribute>
          <attribute>
            <parameter>expression</parameter> (optional) </attribute>
          <attribute>
            <parameter>empty-allowed</parameter> (optional) </attribute>
          <attribute>
            <parameter>message</parameter> (optional) </attribute>
          <attribute>
            <parameter>runat</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_validator">
    <title>Description</title>
    <para>
The validator objects are invoked when the element&#39;s control gets posted. the validator elements only make sense inside field or form types of controls.  the validators are invoked in the order given, and the first one to fail stops the invocation chain, so that no later ones are attempted.
furthermore the vc_is_valid member of the containing page class instance will be reset to false (0) to stop further processing. see also error-summary element and error-glyph attribute of field element.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_validator">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>test</title>
      <para>The type of test to be performed, can be &#39;length&#39;, &#39;value&#39;,  &#39;regexp&#39; or &#39;sql&#39;.
</para>
  </formalpara>
  <formalpara>
      <title>min</title>
      <para>A lower limit in value and length tests
</para>
  </formalpara>
  <formalpara>
      <title>max</title>
      <para>The upper limit for value and length tests
</para>
  </formalpara>
  <formalpara>
      <title>regexp</title>
      <para>The REGEXP pattern to match field value
</para>
  </formalpara>
  <formalpara>
      <title>expression</title>
      <para>A SQL expression for validation
</para>
  </formalpara>
  <formalpara>
      <title>empty-allowed</title>
      <para>If specified as true (1) this will allow submitting an empty field
</para>
  </formalpara>
  <formalpara>
      <title>message</title>
      <para>The error message to be associated to parent control when the test represented by this validator fails.
</para>
  </formalpara>
    <formalpara>
      <title>runat</title>
      <para>Where to perform validation, at server side after posting, or at browser side when entering the values. Note that client side validators can be assigned only to input controls, hence client side form validators for inter-field integrity testing are not allowed.</para>
	  <para>Client side validators will generate client side JavaScript.</para>
</formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_validator">
    <title>Declaration of type vspx_validator</title>
    <para>
</para>
    <screen>
</screen>
  </refsect1>
  <refsect1 id="vc_ex_validator">
    <title>Examples</title>
   <example id="vc_ex_validator__0">
      <title>
  Validation of text area input
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: validator__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The form contains a v:textarea control with v:validator assigned. When the OK button is pressed,
data are posted back to the same URI so the page is instantiated again.
If validator found a violation, the message is shown right after the text input.
(The error reporting may be changed by using v:error-summary VSPX control and
by adding &#39;error-glyph&#39; attribute to the v:textarea.)

</para>
      <screen>
&lt;v:page name=&quot;validator__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:validator&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:form name=&quot;form1&quot; type=&quot;simple&quot; action=&quot;&quot; method=&quot;POST&quot;&gt;
        &lt;v:textarea name=&quot;ta1&quot; default=&quot;enter your text here&quot; value=&quot;--coalesce ({?&#39;ta1&#39;}, control.ufl_value)&quot;&gt;
          &lt;v:validator test=&quot;length&quot; min=&quot;0&quot; max=&quot;50&quot; message=&quot;The input length should not exceed 50 chars.&quot;/&gt;
        &lt;/v:textarea&gt;
        &lt;v:button name=&quot;submit1&quot; action=&quot;simple&quot; value=&quot;OK&quot;/&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
  <tip>
    <title>See Also: Reference Material in the Tutorial:</title>
   <para>
      <ulink url="/tutorial/web/vx_s_2/date.vspx">VX-S-2</ulink>
   </para>
  </tip>
</refentry>
 <refentry id="vc_variable">
  <refmeta>
    <refentrytitle>variable</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>variable</refname>
    <refpurpose>Page variable - a user defined member of page class.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_variable">
    <funcprototype id="vc_proto_variable">
        <funcdef>
            &lt;<function>variable</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>type</parameter> (required) </attribute>
          <attribute>
            <parameter>default</parameter> (optional) </attribute>
          <attribute>
            <parameter>persist</parameter> (optional) </attribute>
          <attribute>
            <parameter>param-name</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_variable">
    <title>Description</title>
    <para>
This element declares a data member for the page subclass corresponding to the containing page.
The value of this data member can be preserved between consecutive postbacks.
The attribute &quot;persist&quot; determine how to save the variable&#39;s value: to session table for inter-page usage, keep in page state only or do not keep it at all.
Note that inter-page variable storage is available only when a vspx:login control is included on the page and authentication is performed; also the name of page variables in corresponding pages needs to be same.
There is no special class for this control because only a data member will be added.
Also the page defines two special variables &#39;sid&#39; and &#39;realm&#39; for login control.
So when an existing login control is is in authenticated state, these will contain values for session id and application realm.
Also every non-repeating control of the page will be represented as a page variable and thus be acessible as &#39;self.&lt;name_of_control&gt;&#39; anywhere in the VSPX page after page initialization.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_variable">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The name of page class member.</para>
  </formalpara>
  <formalpara>
   <title>type = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>The SQL data type of the variable.</para>
  </formalpara>
  <formalpara>
   <title>default = <link linkend="vc_type_SqlCode">SqlCode</link>
   </title>
      <para>The default value. Must be a literal scalar value suitable for the default clause of a user defined type member.</para>
  </formalpara>
  <formalpara>
      <title>persist</title>
   <table>
        <title>Allowed values of the &#39;persist&#39; attribute</title>
    <tgroup cols="2">
     <tbody>
      <row>
              <entry>session</entry>
       <entry>
                <para>keep the variable in the session; needs a login control to be present</para>
       </entry>
      </row>
      <row>
              <entry>pagestate</entry>
       <entry>
                <para>keep the variable in page view state</para>
       </entry>
      </row>
      <row>
              <entry>temp</entry>
       <entry>
                <para>do not keep variable</para>
       </entry>
      </row>
      <row>
              <entry>0</entry>
       <entry>
                <para>same as &#39;pagestate&#39;</para>
       </entry>
      </row>
      <row>
              <entry>1</entry>
       <entry>
                <para>same as &#39;session&#39;</para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </formalpara>
  <formalpara>
   <title>param-name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>This specifies an optional name of a URL parameter for setting the page variable value.
            When this is specified and there is a parameter matching the name, the variable is set after it.  This is a shorthand for an explicit call of keyword_get.
          </para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_ex_variable">
    <title>Examples</title>
   <example id="vc_ex_variable__0">
      <title>
  Declaration of page variable
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: variable__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


The v:variable element defines a new member of page class and hance we can access it with self.mask in rest of VSPX code.

</para>
      <screen>
&lt;v:page name=&quot;variable__0&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;head&gt;
      &lt;title&gt;VSPX samples | v:variable&lt;/title&gt;
    &lt;/head&gt;
    &lt;body&gt;
      &lt;v:variable name=&quot;mask&quot; type=&quot;varchar&quot; default=&quot;null&quot;/&gt;
      &lt;?vsp self.mask := &#39;first value&#39;; ?&gt;
      &lt;p&gt;The variable value is set to &#39;&lt;?V self.mask ?&gt;&#39;&lt;/p&gt;
      &lt;?vsp self.mask := &#39;second value&#39;; ?&gt;
      &lt;p&gt;The variable value is set to &#39;&lt;?V self.mask ?&gt;&#39;&lt;/p&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_vscx">
  <refmeta>
    <refentrytitle>vscx</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>vscx</refname>
    <refpurpose />
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_vscx">
    <funcprototype id="vc_proto_vscx">
        <funcdef>
            &lt;<function>vscx</function> <attribute>
            <parameter>name</parameter> (required) </attribute>
          <attribute>
            <parameter>annotation</parameter> (optional) </attribute>
          <attribute>
            <parameter>initial-enable</parameter> (optional) </attribute>
          <attribute>
            <parameter>enabled</parameter> (optional) </attribute>
          <attribute>
            <parameter>instantiate</parameter> (optional) </attribute>
          <attribute>
            <parameter>control-udt</parameter> (optional) </attribute>
          <attribute>
            <parameter>xsd-stub-xhtml</parameter> (optional) </attribute>
          <attribute>
            <parameter>width</parameter> (optional) </attribute>
          <attribute>
            <parameter>height</parameter> (optional) </attribute>
          <attribute>
            <parameter>url</parameter> (required) </attribute>
          <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_vscx">
    <title>Description</title>
    <para>Custom control encapsulated in a separate VSPX page. This is a
	  wrapper for custom control instantiation. The target URL MUST contain
	  a valid VSPX page reference. In this way repeatable pieces of code can be reused in
	  form of instantiation of their page class, this is different from inclusion.
	  The target page variables can be initialized as attributes in this control, where
	  name of attribute is a name of variable of target page and value is
	  an expression to be assigned.
      </para>
  </refsect1>
  <refsect1 id="vc_attrs_vscx">
    <title>Attributes</title>
  <formalpara>
   <title>name = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>A page level unique name identifying a control.</para>
  </formalpara>
  <formalpara>
      <title>annotation</title>
      <para>A human readable comment.</para>
  </formalpara>
  <formalpara>
   <title>initial-enable = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is initially visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>enabled = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines  whether  a control is visible. True by default. Could be data-bound to an SQL expression.</para>
  </formalpara>
  <formalpara>
   <title>instantiate = <link linkend="vc_type_CalculateableValue">CalculateableValue</link>
   </title>
      <para>Determines whether a control instantiate its children. It is true by default. It could be data-bound to an SQL expression. Unlike most of calcucateable attributes, the value of this attribute for a control is calcluated before calling &#39;on-init&#39; event handler of the control; other values are calculated before calling &#39;before-data-bind&#39; event handler.</para>
  </formalpara>
  <formalpara>
   <title>control-udt = <link linkend="vc_type_SqlName">SqlName</link>
   </title>
      <para>At run time every control is represented as an instance of some user-defined type (UDT). VSPX compiles selects the UDT to use depending on name of the XML element that represents the control and maybe some of its attributes. In some specific cases the application developer may instruct VSPX compiler to use some other UDT, e.g. an application-specific UDT that is derived from the preset one. If specified, the value of &#39;control-udt&#39; attribute should be equal to the name of the desired target UDT.</para>
  </formalpara>
  <formalpara>
      <title>xsd-stub-xhtml</title>
      <para>This attribute is for internal use only. It has no effect if added to the source VSPX file.</para>
  </formalpara>
  <formalpara>
      <title>width</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>height</title>
      <para>Visible width of the control when it is displayed in WYSIWYG tools when the source VSPX text is edited.
The value of this attribute will not be used when the resulting HTML is rendered.</para>
  </formalpara>
  <formalpara>
      <title>url</title>
      <para>Reference to a VSPX page to be instantiated as a control.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_vscx">
    <title>Declaration of type vspx_vscx</title>
    <para>
</para>
    <screen>
create type vspx_vscx under vspx_form
self as ref temporary
constructor method vspx_vscx (name varchar, parent vspx_control, uri varchar),
overriding method vc_pre_render (stream any, n int) returns any
</screen>
  </refsect1>
  <refsect1 id="vc_ex_vscx">
    <title>Examples</title>
   <example id="vc_ex_vscx__0">
      <title>
  Outer page, including a navigation bar via vscx__1.vspx
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: vscx__0.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This page will embed  another page twice,  but not as simple inclusion. The
second page is treated as a control and it&#39;s page class will be instantiated twice as
as a child of outer page.

</para>
      <screen>
&lt;v:page name=&quot;outer_page&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;html&gt;
    &lt;body&gt;
      &lt;v:variable name=&quot;var1&quot; type=&quot;int&quot; default=&quot;0&quot; /&gt;
      &lt;h3&gt;Embeeding a page as a custom control&lt;/h3&gt;
      &lt;v:form type=&quot;simple&quot; name=&quot;f1&quot;&gt;
	&lt;div&gt;
	  &lt;div&gt;control1&lt;/div&gt;
	  &lt;v:vscx name=&quot;bar1&quot; url=&quot;vscx__1.vspx&quot;/&gt;
	&lt;/div&gt;
	&lt;div&gt;
	  &lt;div&gt;control2&lt;/div&gt;
	  &lt;v:vscx name=&quot;bar2&quot; url=&quot;vscx__1.vspx&quot;/&gt;
	&lt;/div&gt;
	&lt;div&gt;
	  &lt;v:text name=&quot;txt2&quot; /&gt;
	  &lt;v:button action=&quot;simple&quot; value=&quot;Outer&quot; name=&quot;b2&quot; /&gt;
	&lt;/div&gt;
      &lt;/v:form&gt;
    &lt;/body&gt;
  &lt;/html&gt;
&lt;/v:page&gt;
</screen>
   </example>
   <example id="vc_ex_vscx__1">
      <title>
  Simple navigation bar used as custom control
</title>
      <para>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;!--
 -  
 -  $Id: vscx__1.vspx,v 1.2 2006/08/16 00:04:15 source Exp $
 -
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2006 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  


This page is used inside vscx__0.vspx one as a custom control.

</para>
      <screen>
&lt;v:page name=&quot;custom_bar&quot; xmlns:v=&quot;http://www.openlinksw.com/vspx/&quot;&gt;
  &lt;v:variable name=&quot;test&quot; type=&quot;int&quot; default=&quot;12&quot; /&gt;
  &lt;table border=&quot;1&quot; cellspacing=&quot;1&quot; cellpadding=&quot;0&quot;&gt;
    &lt;tr&gt;
      &lt;td&gt;
	&lt;v:url name=&quot;u1&quot; value=&quot;Home&quot; url=&quot;--http_path ()&quot; /&gt; |
      &lt;/td&gt;
      &lt;td&gt;
	&lt;v:url name=&quot;u2&quot; value=&quot;Settings&quot; url=&quot;--http_path ()||&#39;?settings&#39;&quot; /&gt; |
      &lt;/td&gt;
      &lt;td&gt;
	&lt;v:url name=&quot;u3&quot; value=&quot;Posts&quot; url=&quot;--http_path ()||&#39;?posts&#39;&quot; /&gt; |
      &lt;/td&gt;
      &lt;td&gt;
	&lt;v:url name=&quot;u4&quot; value=&quot;Maintenance&quot; url=&quot;--http_path ()||&#39;?maint&#39;&quot; /&gt;
      &lt;/td&gt;
    &lt;/tr&gt;
  &lt;/table&gt;
  &lt;div&gt;
    &lt;v:form type=&quot;simple&quot; name=&quot;f1&quot;&gt;
      &lt;v:text name=&quot;txt1&quot; /&gt;
      &lt;v:button name=&quot;b1&quot; action=&quot;simple&quot; value=&quot;Inner&quot;/&gt;
    &lt;/v:form&gt;
  &lt;/div&gt;
&lt;/v:page&gt;
</screen>
   </example>
  </refsect1>
</refentry>
 <refentry id="vc_xsd_stub">
  <refmeta>
    <refentrytitle>xsd-stub</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>xsd-stub</refname>
    <refpurpose>This is for internal use only.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_xsd_stub">
    <funcprototype id="vc_proto_xsd_stub">
        <funcdef>
            &lt;<function>xsd-stub</function> <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_xsd_stub">
    <title>Description</title>
    <para>
This control should never appear in the VSPX source.
It is for internal use only.
Before applying XML schema validation to the page,
Virtuoso replaces non-VSPX tags with this one when they reside inside v:page.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_xsd_stub">
    <title>Attributes</title>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_xsd_stub">
    <title>Declaration of type vspx_xsd_stub</title>
    <para>
</para>
    <screen>
create type vspx_xsd_stub under vspx_control
as ( vc_stub any ) temporary self as ref
</screen>
  </refsect1>
</refentry>
 <refentry id="vc_xsd_stub_script">
  <refmeta>
    <refentrytitle>xsd-stub-script</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>xsd-stub-script</refname>
    <refpurpose>This is for internal use only.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_xsd_stub_script">
    <funcprototype id="vc_proto_xsd_stub_script">
        <funcdef>
            &lt;<function>xsd-stub-script</function> <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_xsd_stub_script">
    <title>Description</title>
    <para>
This control should never appear in the VSPX source.
It is for internal use only.
Before applying XML schema validation to the page,
Virtuoso replaces non-VSPX tags with this one when they reside inside event script tag such as v:on-init.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_xsd_stub_script">
    <title>Attributes</title>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_xsd_stub_script">
    <title>Declaration of type vspx_xsd_stub_script</title>
    <para>
</para>
    <screen>
create type vspx_xsd_stub_script under vspx_control
as ( vc_stub any ) temporary self as ref
</screen>
  </refsect1>
</refentry>
 <refentry id="vc_xsd_stub_top">
  <refmeta>
    <refentrytitle>xsd-stub-top</refentrytitle>
    <refmiscinfo>vspx_control</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>xsd-stub-top</refname>
    <refpurpose>This is for internal use only.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <funcsynopsis id="vc_syn_xsd_stub_top">
    <funcprototype id="vc_proto_xsd_stub_top">
        <funcdef>
            &lt;<function>xsd-stub-top</function> <attribute>
            <parameter>debug-srcfile</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-srcline</parameter> (optional) </attribute>
          <attribute>
            <parameter>debug-log</parameter> (optional) </attribute>
 /&gt;</funcdef>
    </funcprototype>
   </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="vc_desc_xsd_stub_top">
    <title>Description</title>
    <para>
This control should never appear in the VSPX source.
It is for internal use only.
Before applying XML schema validation to the page,
Virtuoso replaces non-VSPX tags with this one when they reside outside v:page.
</para>
  </refsect1>
  <refsect1 id="vc_attrs_xsd_stub_top">
    <title>Attributes</title>
  <formalpara>
      <title>debug-srcfile</title>
      <para>URI of the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-srcline</title>
      <para>Line number in the source document where the tag comes from.</para>
  </formalpara>
  <formalpara>
      <title>debug-log</title>
      <para>This defines what sort of data are saved to the debugging log.
</para>
  </formalpara>
  </refsect1>
  <refsect1 id="vc_udt_xsd_stub_top">
    <title>Declaration of type vspx_xsd_stub_top</title>
    <para>
</para>
    <screen>
create type vspx_xsd_stub_top under vspx_control
as ( vc_stub any ) temporary self as ref
</screen>
  </refsect1>
</refentry>
</sect2>