FormHandler - Manual / Getting Started / How To Use The Database Option

Manual / Getting Started / How To Use The Database Option

How To Use The Database Option

Description:

When you use the database option, FormHandler will take care of the saving and loading of the data. Below is explained how it works and what you can expect from FormHandler.

Database Requirements

FormHandler can use the following databases:

mysql - MySQL (www.mysql.com)

postgresql - PostgreSQL (www.postgresql.org)

access - Microsoft Access (Windows only)

mssql - Microsoft SQL Server (www.microsoft.com/sql)

By default, FormHandler uses the MySQL database communication layer. You can change this default value in the config file. You can also change this when you set the table which FormHandler should use.

To let FormHandler save and load the data from your database, you have to make a table. This table has to have at least one primary key!!! This is very important, otherwise FH cannot save and load the data from your database!

After creating the table you have to let FormHandler know which table it should use. You can do this in two ways, depentend on if you have a database connection open:

Let FormHandler open a new connection to the database

Let FormHandler use an already opened connection

Please note that when you want to use the database functionality, you have to include the file class.dbFormHandler.php and use the constructor $form = new dbFormHandler()!

Below is explained how each way works:

Let FormHandler open a new connection to the database

If you want to let FormHandler create a new connection to the database, you should supply the needed data to make a new connection. You can do this with the functions dbInfo and dbConnect.
In these functions you have to set all the needed data to connect to the database. Check them out in the manual to find out what arguments are passed trough.

Example:

<?php

// include the dbFormHandler
include("FH3/class.dbFormHandler.php");

// create a new form
$form = new dbFormHandler();

// set the database info
$form -> dbInfo( "myDB", "myTable", "mysql" );
$form -> dbConnect( "localhost", "username", "password" );

// here comes the rest of the form
// ............

// set the data handler
// (NOTE the onSaved, this is different then onCorrect!)
$form -> onSaved("doSomething");

// display the form
$form -> flush();

// the data handler...
// NOTE the two arguments!!!!
function doSomething( $id, $data )
{
// do something here...
}

?>

After passing all the needed data you have to add some fields to the form. This time however you have to name the fields exactly the same as in the table! All fields which are simular will be saved / loaded correctly. All other fields will be ignored!

This is all whats needed to make a good working form which is using a database to save all the data. Easy huh?! ;-)

Let FormHandler use an already opened connection

When you want to let FormHandler use an already opened connection, you have to give the connection resource and the table name to FormHandler. You can do this with the function setConnectionResource.

Example:

<?php
/**
* Your Database Connection (In This Example MySQL)
*/
$connection = mysql_connect( "localhost", "username", "password" );

// connection made ?
if( $connection )
{
    // select the database
    if( !mysql_select_db( "database", $connection ) )
    {
        // could not select database!
        die('Could not select the database! Error: ' . mysql_error() );
    }
}
// could not connect to the database
else
{
    die('Could not make a connection to the database! Error: ' . mysql_error() );
}

// include the formhandler
include('FH3/class.dbFormHandler.php');

// create a new form
$form = new dbFormHandler();

// set the database info
$form -> setConnectionResource( $connection, "myTable", "mysql" );

// here comes the rest of the form
// ............

// set the data handler
// (NOTE the onSaved, this is different then onCorrect!)
$form -> onSaved("doSomething");

// display the form
$form -> flush();

// the data handler...
// NOTE the two arguments!!!!
function doSomething( $id, $data )
{
    // do something here...
}

?>

Inserting

Inserting data is extreme easy. If you just have created a form like explained above, the only thing you have to do is run the script.

Remember: Fields which have the same name as the column names in the table will be saved into the database. All the other fields are ignored.

So, if you have a MySQL table which looks like this:

CREATE TABLE `myTable` (
  id int(6) unsigned NOT NULL auto_increment,
  title varchar(50) NULL,
  text text NULL,
  PRIMARY KEY (id)
)

A form like below wil be correct and the data will be saved into the table.

<?php

// include the class
include("FH3/class.dbFormHandler.php");

// create a new formhandler object
$form = new dbFormHandler();

// set the database info
$form -> dbInfo   ( "myDb", "myTable" );
$form -> dbConnect( "localhost", "username", "password" );

// the fields + button
$form -> textField( "Title", "title", FH_STRING, 20, 50 );
$form -> editor   ( "Text", "text", FH_TEXT, "images/uploads" );
$form -> submitButton( "Save" );

// set the data handling function
$form -> onSaved  ( "doRun" );

// display the form
$form -> flush();

// the data handling function
// NOTE: 2 arguments! This differs from the function onCorrect!!
function doRun ( $id, $data )
{
    echo " The data is saved with id ".$id."!\n";
}
?>

Editing records

Editing records works the same as inserting records. Your form is excactly the same. The only thing which you have to do is to let FormHandler know which record should be edited. You can do this by passing the id of the record trough the URL:

myScript.php?id=4

In this example, record 4 will be edited. If you have multiple primary keys, you have to pass them as an array:

myScript.php?id[]=4&id[]=en

That's all! Really!

If you want you can change the var name which FormHandler will check. By default, this is set to "id". You can change it in the config file with the var FH_EDIT_NAME.

NOTE!!! If you don't want users to edit specified records you have to make sure that they can't! FormHandler DOES NOT HANDLE THIS!

Latest change: 16 October 06 / 09:53

Manual / Getting Started / How To Use The Database Option

Comments