VCV-Tags in XHTML Documents


VCV-Tags in XHTML Documents

This section describes which kind of tags and attributes VCV provides for using in XHTML documents.

Text Input

VCV supports two kinds of text inputs, Single Line and Multi Line. Note, that they may contain data you would not see as text, such as control characters, but VCV does not matter about it, it works on strings as character arrays.

Single Line

These are the XHTML form elements of the input tag with the types text and password, so this produces identical VCV code:

        <input type="text" name="login" size="20" />
        <input type="password" name="pwd" size="20" />

There are the following XHTML and VCV attributes for single line text boxes (there are some more XHTML attributes, but VCV does not care about them):

name
This attribute is required by the XHTML standard and specifies a unique name for this form field. User agents send this as key in a CGI request.

maxlength
Unlike the size attribute, this one does not only has a declarational meaning, it tells browser to accept not more characters (!) in the input than specified by the attribute value. VCV uses this value to truncate the submitted form data without any error (default). If you want the submission to fail in such a case, you can either check the string lengths before and after processing by VCV or tell VCV explicitly to care about it.

vcv:minlength
This attribute is used as the opposite to the one above, it is set to the minimal lenght of the input data. You can use is together with maxlength:
        <input type="text" name="var_word" vcv:minlength="2" maxlength="7" />

This example means, that the content of var_word has to be at least 2, but maximal 7 characters long.

vcv:type
VCV requires this attribute to interpret the receiving string as a certain VCV data class, such as a SQL Date in the vcv-classes manpage. It is set to String in the vcv-classes manpage by default.

vcv:pregex
Use this attribute instead of vcv:type if you want the given input to be in a certain format, matching this Perl Regular Expression. VCV will validate the input against this regex.

There are some limitations of single line text boxes: Incoming special characters with an ASCII value below 0x20 will be replaced with the space character (ASCII char 0x20). That is, because the XHTML input tag does not support characters such as newline (0x0A) or tab (0x09). (In fact input accepts these characters, but you cannot type them into the field, instead you need to copy&paste.)

Multi Line

This is a mapping for the XHTML element textarea.

        <textarea name="text" rows="10" cols="50" vcv:length="512">
        Text for setting an initial textarea content.
        </textarea>

A textarea is a bit more liberal than a Single Line text box, since it also allows tabs and newlines to be in the string, so there will not be any replacement of control characters.

VCV interprets the following attributes:

name
The unique text boxes name.

vcv:length
Since a textarea has no XHTML attribute to specify a maximal content length, there is a VCV one. The attribute value is the number of characters (not bytes!) the field may contain. This is to support multibyte character data such as Unicode™, because a length of 20 may be 20 ASCII characters, but it may also be 10 UTF-16 ones.

Submit Buttons

XHTML knows two kinds of submit buttons, input type="submit" and button type="submit". The following declarations are the same in the VCV meaning:

        <input type="submit" name="go" value="Let&apos;s go" />
        
        <button type="submit" name="go" value="Let&apos;s go">
        <!-- Here may also be an image or a 
          -  different text as given as value
        -->
        </button>

VCV processes the following attributes (as sent from the user agent):

name
This is the unique form elements identifier.

value
HTTP user agents send this string as submission value associated with the button. If you have more than one submit button in a XHTML form, you can use it to trigger different actions, dependent of the button clicked by the user. To tell VCV about these ``onSubmit'' callback handlers, call the VCV method registerButtonAction():
        registerButtonAction("btn_name", "btn_value", callback_handler)

The function referenced by callback_handler is called if the submit button named btn_name has the value btn_value; it receives a reference to the VCV form object representing the submitting form.

Select/Choice Controls

XHTML knows two kinds of selection, the first one is a Multiple Choice, that means you can select one or more items out of a set. The second one we name here Choose One, so you can choose only item at once.

Multiple Choice

A multiple choice is given either by input type="checkbox" (with the same name) or by select multiple="multiple":

        <input type="checkbox" name="multi" value="first" />
        <input type="checkbox" name="multi" value="second" />
        <input type="checkbox" name="multi" value="third" />
        
        <select size="3" name="multi" mulitple="multiple">
                <option value="first">1st</option>
                <option value="second">2nd</option>
                <option value="third">3rd</option>
        </select>

There is also a plain VCV (XML) syntax for declaring a multiple choice field in script code like PHP or ASP, if your CGI script dynamically creates the code for such a field:

        <?php // php code generating a select or checkboxes ... ?>
        <vcv:choose-multiple name="multi" values-of="array" />

The advantage of this kind of XHTML enhancement is, that is a so-called empty XML tag, that browsers do not display, but VCV will parse it.

The values-of attribute tells VCV that there exists a variable, that contains values used to validate the submitted selection. Note that there is no starting $ for Perl or PHP to be compatible with later reimplementations in C, Java, …. This variable has to be either an array or an (object) method returning an array:

        <vcv:choose-multiple name="multi" values-of="db_result->values()" />

This attribute can also be used in select tags, if your CGI script generates only the option's:

        <select size="1" name="multi" multiple="multiple" vcv:values-of="arrayFunction()">
        <php
        // arrayFunction() returns an array with the following options:
        foreach ...
        ?>
        </select>

Choose One

The XHTML elements for choosing one of number of items are input type="radio" and select without the multiple attribute:

        <input type="radio" name="one" value="first" />
        <input type="radio" name="one" value="second" />
        <input type="radio" name="one" value="third" />
        
        <select size="3" name="one">
                <option value="first">1st</option>
                <option value="second">2nd</option>
                <option value="third">3rd</option>
        </select>

There is also a direct VCV syntax for this kind of selection:

        <% // asp code generating a radio group %>
        <vcv:choose-one name="one" values-of="myList" />

General Options

VCV collects two values of a selection:

name
This is the name attribute of the selection, as required in input, select, vcv:choose-one or vcv:choose-multiple.

value or values-of
The value attribute will be used to collect all possible (= valid) values of a selection. Although most VCV implementations will store them in an array, think of it as a set (or enum for the C folks). For the dynamically generated code VCV needs a validation source, specified by values-of. Note that if used in a select tag you have to give the XML namespace prefix vcv, too. As mentioned above, values-of does not require a ``plain'' variable, also a method call will do it. If using VCV for programming languages with so-called early bindings, you cannot use the ``just in time'' validation of your form object, instead you always have to generate (and compile) the validation code. This is also recommended for interpreted programming languages with late bindings, because it increases script execution time.

File Uploads

This is also a kind of input tag: It is of type file:

        <input type="file" name="patch" size="50" maxlength="1024" accept="text/*" />
name
This is the required field name.

maxlength
This attribute has been designed for user agents to check the size of the file to upload; it is the maximal size (in bytes) the file has to be. While most (every?) browser ignores it, VCV does. To prevent data loss, it generates an error if the current file size exceeds this value instead of working with only a part of the file.

accept
The accept attribute should be used to tell the browsers file selection dialog to accept only certain MIME types. The experience shows, that no user agents uses this limitation, instead they let you upload what ever you want. You better use it with care, since checking a files MIME type may be a bit difficult, especially on some platforms. Note that VCV does not interpret, what the browser ``thinks'' this might be, because they seem to guess it instead of requesting magic files or the Windows® registry. So, most user agents send only a limited subset of common content types, such as the ``general'' application/octet-stream. VCV implementations should use magic files (as used by the common unix program file) to determine the content type, because this seems to be a very good technology.

VCV Options

The tag described in this subsection can be used for setting certain VCV options. The VCV-API offers also the setVCVOption() function for this.

vcv:option

        <vcv:option name="optName" value="optValue" />
name
This is the name of the option to set.

value
And this is the options value. See the setVCVOption() documentation for details about valid input formats.


Revision

This document: $Id: xhtml-tags.pod,v 1.1 2005/07/22 16:28:03 robertbienert Exp $

See http://vcv.sourceforge.net/spec/ for the latest revision.

 VCV-Tags in XHTML Documents