VCV API


VCV API

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:

Types

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

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

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

Other Keywords and Operators

const
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

Initialization

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.

initVCV

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)
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.

registerButtonAction

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)
btnName
This parameter contains the button's name as string. The name is defined in the HTML form using the name attribute.

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

callbackHandler
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.

registerClassAsRegExp

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

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

pRegExp
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.

registerClassUsingValidator

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

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

validatorHandle
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.

getVCVOption

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)
optName
This argument specifies the name of the option, that value you want to get.

setVCVOption

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

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

optValue
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.

Validating

validate

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.


Revision

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

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

 VCV API