Chapter 7. Using Pre-Built formVista Components on a Web Page

Using pre-built components is very easy. You just have to set up your PHP enabled webpages with a few calls at various places and the framework takes care of the rest.

For this section, please refer to the formVista DemoShell component gallery. We will be referring to various examples there.

7.1. A Typical formVista PHP Page

Here is an example of a typical web page set up to host a single formVista component. For purposes of demonstration, it uses the “Complete Form” component from the Component Gallery.

<?php
// include the formVista processor and configuration generated
// by Configure.
include_once( "./config.php" );
// this component posts back to this page so the second 
// argument is NULL.
vistaLoad( "/fvml/form_complete", NULL  );
// if any components need to get data they do it now
vistaEvent( "GetData" );
// here components process any commands sent to them.
vistaProcessCmd();
?> 
<!-- your HTML begins here. -->
<HTML>
<HEAD>
<?php  
// style sheets needed by loaded components.
vistaEvent( "CSSIncludes" );
// javascript files needed by components.
vistaEvent( "JavascriptIncludes" );
?>
<!-- put your extra javascript includes or styles`heet
includes here -->
<SCRIPT LANGUAGE="javascript">
<?php 
// some components output custom javascript functions.
vistaEvent( "Javascript" ); 
?>
<!-- put any additional javascript calls you might want here -->
</SCRIPT>
</HEAD>
<!-- from here down it's just normal HTML with a few vista commands thrown in -->
<body bgcolor="#FFFFFF" marginheight="0" marginwidth="0" leftmargin="0" topmargin="0">
<table width="100%"> <tr> <td width="20%"> &nbsp; </td> <td valign="top">
<?php 
// this is where the component gets displayed.
vistaShow( "form_complete" );       
?>
<br> <br>
<?
// special event to handle divmenu components.
vistaEvent( "RenderSubmenus" );
// some tags like htmleditor need this event.
vistaEvent( "Footer" ); 
?>
</BODY>
</HTML>

This is all that's required to host any standard formVista component. This page will do the displaying of the form, the validation on submit, the dumping of data into the database and displaying feedback to the user.

Now we move on to describe each section of the page in more detail.

7.1.1. Loading the formVista Processor

First you have to load in formVista. This is typically done using the config.php file generated by the formVista setup.php script. This file:

loads in the formVista processor.
connects to the database server and selects the database identified in the configuration
starts the processor which in turn automatically starts the session.

To load the processor and accomplish all of this you add the line:

<?php
include_once( "./config.php" );
?>

This must be added at the very top of the file. There must be no spaces between the start of the file and the <?php.

If the config.php file is in some other directory you'll have to change the “./config.php” to point to the right place.

config.php is generated from a config.in.php file by the setup.php script.

7.1.2. Loading a Component

The next step is to load a component. Component files are always stored in an fvml directory. To load a component you use the vistaLoad() command giving it the name of the component such as:

<?
vistaLoad( "/fvml/form_complete", NULL );
?>

The first parameter is the path to the FVML file relative to the root of the application.

The second parameter is the page that the component should link or post to. If it's NULL the component will link back to the same page it was loaded on. Since we have set it to NULL, the form_complete component will post back to the same page.

Don't confuse loading a component with seeing the component. vistaLoad() only loads the component into memory. At this point in the page, the component is just sitting there in memory waiting for commands or events.

7.1.3. Getting Data

Many components, such as calendar or report components, need to run queries on a database before they are displayed. This is called the “Getting Data” step and typically happens right after components are loaded. You may or may not have any components loaded that are interested in getting data but to make your pages able to host any kind of component you should do a:

<?
vistaEvent( "GetData" );
?>

somewhere near the top.

This “raises an event”. Different components are interested in different events. In the vast majority of cases you don't even need to know what events a component is interested in. Components will ignore events that do not apply to them.

Here we are saying “Ok components loaded on the page, if any of you need to go get data from the database now is the time to do it”. If you have a component loaded that has an <onGetData> section in it, it will be run at this time. The simple report example runs it's query at this point in the page.

7.1.4. Processing Commands

The next thing to do is handle commands. In formVista components send commands back to themselves. Command processing is what happens when someone presses on the SUBMIT button on a form or the NEXT/PREV links on a list, or the VIEW ENTRY link on a calendar. This is the point where if the user has asked the component to do something it's taken care of.

However, before the command is actually processed formVista will check to see if any fields need to be validated. For instance, our form_complete component checks to make sure the first field is filled in. This is called form field validation. If the user made a mistake and form field validation fails an error will be generated. However, that error will not be shown here. formVista will hold it until later. (See vistaShow() below).

To get components to process any commands directed at them you just do a:

<?
vistaProcessCmd();
?>

7.1.5. Automatic Javascript Includes

Sometimes components need to use javascript features. These can be as simple as a popup window to something as advanced as a cascading menu system or an HTML editor. formVista will take care of bringing in all the javascript libraries required by any components on the page. All you have to do is raise the JavascriptIncludes event somewhere in the HEAD section.

To tell components “ok, now include any javascript files you might need” do a:

<?
vistaEvent( "JavascriptIncludes" );
?>

somewhere in the HEAD section of the page.

7.1.6. Cascading Style Sheets

Just like the javascript files above, components may use their own stylesheets. To tell components on the page “ok, now include any stylesheet files you might need” do a:

<?
vistaEvent( "CSSIncludes" );
?>

somewhere in the HEAD section.

7.1.7. Dynamic Javascript Functions

Sometimes formVista components need to actually write their own custom javascript functions. For instance, the dropdown menu component does this as does the HTML Editor. You must have a <script language=”Javascript”> section in your webpage and in that section you need to include a:

<?
vistaEvent( "Javascript" );
?>

If you do not do this some components, like the drop down menus, will not work on your page.

7.1.8. HTML

At this point in the page you can just start including HTML just like you normally would. formVista doesn't restrict what you can do. You can load applets or flash movies. You can even include PHP code.

7.1.9. Rendering the component

To actually show the component or it's feedback if there is any, simply include:

<?
vistaShow("form_complete");
?>

at the point where you'd like the component to be displayed. The component will know whether or not it should display the component, a validation error or a feedback component.

7.1.9.1. Feedback

As we mentioned in the Processing Commands section above, components may or may not do form field validation. If form field validation fails, such as in the case where the user fails to enter something in the first field, the component will have feedback to show. Instead of displaying the error at the point where we're processing the command high up in the page, we hold the error until you're ready to show it.

Form field validation errors are displayed inside the component itself. For example, let's say the user did not enter something into the required field in our form_complete form, the feedback message “Required” will be displayed in red inside the form. This allows the user to fix the mistake and try again without having to re-enter anything.

Feedback also might be what the component has to say when something was done successfully. In this case components use other components as “feedback”. For instance, if the form_complete component successfully validates the form fields and add the new row to the database, the component may want to display the new table to the user as feedback and include a “Your entry has been added” message.

Thus, feedback may be an error or a success message. Feedback is what the component has to say back to the user.

However, the person fielding the component on the webpage is shielded from all of these details.

7.1.10. Footer Events

The divmenu component, htmleditor tags and others need to do some processing at the end of the page. These two events are put before the closing body tag.

<?
// special event to handle divmenu components.
vistaEvent( "RenderSubmenus" );
// some tags needs this event.
vistaEvent( "Footer" ); 
?>