This section describes the (object-orientated) API VCV offers to you as web programmer. VCV implementations have to define this API. Object-orientated VCV implementations can define the API as methods, declared for objects of a class named VCV, while procedural ones need to declare some global variables, e.g. the option table; they should not use an object-like handle that is passed as additional function argument.

Terms Used In This Document

The following subsections and function declarations are written using a kind of ``pseudo-code'' for describing which data types the functions expect. There are this data types and conventions:


This is a boolean variable, having only the two values true or false.

This specifies a string variable in the programming languages default implementation, e.g. a scalar in Perl or std::string in C++.

This type stands for a (Perl) regular expression. Depending on the programming language, it can also be a string.

Other Keywords and Operators

This ``prefix'' shows that this parameter is treated as a constant value that will not be changed by the sub-routine.

This operator is used to show that something is passed as reference (not as pointer) to the function, it has the same meaning as in C++ or PHP.

Naming Conventions


The function here initializes the VCV framework; in object-orientated terminology it can be seen as a constructor, so its name may also be same as the class is named to (for C++, Java ...) or may have a special name, e.g. __construct for PHP 5.


This function creates and initializes a new VCV object; initialization means parsing the web form or form definition file into a handy data structur.

        VCV initVCV(const string formdef)
This is the file name of either a form definition file or the web form; it can be a relative path as well as a absolute location. VCV will parse this file.

The return value is a VCV object. If this function is implemented as an object constructor, it may not return a value.

Triggering Button Actions

The function in this subsection registers a callback handler that is triggered when the clicks a certain submit button on the web form. See Submit Buttons in the xhtml-tags manpage for details.


This function registers the callback handler callbackHandler for the HTML submit button btnName. It is called when the button's value is btnValue.

        registerButtonAction(const string btnName,
                const string btnValue, callbackHandler)
This parameter contains the button's name as string. The name is defined in the HTML form using the name attribute.

This string specifies the submit btnName has to have if callbackHandler should be called.

This is a reference (or pointer) to a function that is called if the requirements above are met. This function has to return a boolean value, where true means success. The handler is passed a reference to the current VCV Form object:
        boolean callbackHandler(& Form)

Registering Custom Classes

The functions in this section register new VCV content types for type-checking submitted data. For more about VCVs content classes see the vcv-classes manpage.


This function registers a new type that is validated against a Perl Regular Expression.

        registerClassAsRegExp(const string className, regex pRegExp)
This string gives the name of the new VCV content class.

This is the Perl Regular Expression the class is validated against. While most implementations prefer a string, you can pass a RegExp directly when using the Perl implementation.


This function registers a new type that is validated by a user defined sub-routine.

        registerClassUsingValidator(const string className, validatorHandle)
This string gives the name of the new VCV content class.

This is a reference/pointer to a validator function that checks if the given data matches certain content criteria. It returns true if the value to check meets the requirements, false otherwise. The function is called when type-checking the submitted CGI data. Its prototype looks like this:
        boolean validatorHandle(const string toCheck, string& out)

where toCheck is the incoming data, provided by VCV and out is a reference to an array field where the validated and converted (if valid) data is stored; this array is provided by the VCV Form object.

VCV Options

The functions in this subsection are used for getting and setting VCV options.


This function returns the value of the specified VCV option as string or an undefined value if there is no such option set.

        string getVCVOption(const string optName)
This argument specifies the name of the option, that value you want to get.


This function sets a specific VCV option. It is equivalent to the vcv:option tag.

        setVCVOption(const string optName, const optValue)
This argument specifies the name of the option you want to set.

This parameter is the value for optName. Its default type is string, so that no VCV implementation should have any problems declaring this function. VCV implementations may accept other types, too, e.g. boolean values.



This function validates the submitted information against the requirements collected by initVCV().

        boolean validate()

The return value is true if the submitted data is valid, false otherwise.


This document: $Id: api.pod,v 1.2 2005/09/02 16:05:27 robertbienert Exp $

See for the latest revision.