formVista(tm) Programmers Documentation

Documentation generated from the source code

Yermo Lamers

http://www.formvista.com/contact.html

For PHP Programmers.

This documentation was generated using phpDoc http://www.phpdoc.org and comes straight from inline comments in the source code. It is intended for PHP programmers who want to understand how formVista(tm) is put together and possibly how to extend it to develop new options, validators, tags or components.

This documentation does not cover building application using FVML. It strictly covers the PHP class heirarchies and supporting functions that make up the framework and implement the FVML language.

For information about FVML syntax, placing components onto PHP enabled webpages and theming please refer to the formVista(tm) Users Guide and Component Reference. ../formvista_guide/book1.html

Another good source of information is present in the formvista_demoshell sample application available on the formvista website.

Overview

Configuration

Before use, formVista(tm) based applications must be configured. formVista(tm) includes a reuseable setup system which makes PHP applications installable into commodity environments by generating configuration files and database schemas. Additionally it has the ability to upgrade database schemas in-place which makes managing an installed base of applications much easier.

To start your own project the best approach begins with copying the existing demoshell to a new directory, edit the configuration files in conf/* and edit the setup screens in setup_local/*.

For more information on the setup system please refer to:

formVista Setup System (setup.php)
database setup (setupDatabase.fvml)
application specific setup callbacks (app_setup.php)
install support functions (install.php)
support files including php_extensions.txt,default_settings.txt,infile_list.txt,symlink_list.txt, among others in the conf/* directory
master configuration file containing FVAPP_NAME

Be sure to try out the sample application to see the setup system in action.

The formVista Processor

The core of the formVista(tm) framework is the formVista processor class found in formVista.php. It manages the connection to the datastore, parses FVML files to construct object trees that are the in-memory representation of formVista components, routes commands to the right component and manages events raised on the page. It also acts as a gatekeeper for all output generated by formVista tags and components. Additionally it contains a number of convenience and debugging methods including a execution time and memory usage profiler.

Only one formVista process class is instantiated per page. The vistaStart() function in simpleVista.php is typically how the class is instantiated. See one of the config.php files in the demo application for more information.

The simpleVista Interface

Since one the primary target audiences consists of non-programming web designers a simpler interface needed to be provided that involved as little notation as possible. This is how the simpleVista.php came into being. This provides a very simplified procedural interface to the formVista class and keeps the number of arguments down to an absolute minimum. The goal is to make it as easy on webdesigners to field components as possible.

Largely the simpleVista functions call on a webpage are independent of any components that are loaded thanks to the command and event system in the processor. Typically in order to host formVista components the designer must include in the very top of the file before any HTML is added:

include the config.php for the app. This calls vistaStart()
vistaProtect() if the page is password protected
vistaLoad() for each component to be used
vistaGetData() to invoke onGetData
vistaProcessCmd() to process any commands

And then in various sections in the body of the webpage:

vistaEvent() "CSSIncludes" to bring in the style sheets
vistaEvent() "JavascriptIncludes" to bring in the javascript includes
vistaEvent() "Javascript" for custom javascript functions
vistaEvent() "MenuHeader" to support divmenu.php
vistaShow() for each component to display it
vistaEvent() "RenderSubmenus" to support divmenu.php
vistaEvent() "Footer" to support some js.php tags

The demo has exhaustively comments examples such as post.php.

Component Classes

Every tag in the FVML has a corresponding PHP class that implements it. Component tags are the top level tags in FVML and are always called component. The class that gets instantiated is based on the name=".." attribute to the component tag. (See clog_post.fvml for an example of a form component).

Upon parsing the component tag, the formVista processor will search the VISTA_CLASSPATH for a subdirectory under components with the same name as the name attribute. In the case of name="form" the processor would look for components/form/form.php. The names of component classes all end in Ctrl. So for instance the name of the form component class would be fv_formCtrl.

Component classes are all subclasses of fv_baseComponent. See the Components subpackage for a list of component classes currently available.

TagHandler/Widget Classes

Other tags below the level of the component .. tag are often called "Widgets" and are implemented using taghandler classes. All taghandler classes are subclass of fv_baseWidget. There are four kinds of taghandler classes:

Normal tags that appear in the body section such as fv_inputWidget input field
Command handler tags that appear in command processing section such as fv_feedbackWidget
Javascript options tags that appear in the body section such as fv_PopupCalendarOption
Validator tags that can appear either in the body section or in command handlers such as fv_validate_isAlpha

Like component classes, tag handler classes are contained in their own php files that follow a naming convention.

Normal tags and command handlers have an fv_ prefix and a Widget suffix such as fv_inputWidget
javascript tags have an fv_ prefix and an Option suffix such as fv_PopupCalendarOption
validator tags have an fv_validate_ prefix such as fv_validate_isAlpha

Upon parsing a tag, the formVista processor will search the VISTA_CLASSPATH for a subdirectory under widgets for normal taghandlers, options for javascript options or validators for validator tags.

In the case of normal taghandlers, the processor will look for a subdirectory with the same name as the tag under the widgets subdirectory. For example, in the case of an htmleditor tag the processor would look for widgets/htmleditor/htmleditor.php.

js and validate tags themselves are located in validate.php and js.php respectively. These tags operate a little differently in that they behave like the processor in that they load in and instantiate a taghandler class. This tag is brought in based on the name= attribute given to the js or validate tag. In the case of js options, the class files are located under the options directory. For validators, it's the validators directory.

A special note on option and validator classes, you have to remember that the option and validator classes are children of their respective js or validate tag. So if you want the parent of the js or validate tag you have to get "the parents parent". See fv_validate_isAlpha for instance.