FormEntry Installation and Configuration

Quick Links:

Installation is quite straight forward. The application is distributed as a compressed tar file (.tgz). Un-tar this (e.g. tar xzf formentry-1.0.tgz) in your HTDOCS directory (name will be 'formentry', although you may rename this as you wish). Now configure the application by creating your local configuration file.

Configuration

FormEntry reads a local PHP configuration file by the name of local_config.php. You create this file the first time by copying it from model_config.php. Subsequent releases of this application will provide new versions of model_config.php. Be sure that you compare your local_config.php with the new model_config.php and make the necessary changes to your local_config.php. The local_config file controls a number of things:

Defaults details about the database for the data (host, type, userid etc.)
Defaults details about the database for the definitions (host, type, userid etc.)
Directory where project files can be found
Naming convention for definition tables
Defaults for links to be added to headers
Default titles
Defines additional languages supported
SQL for definition table
Background colors for various tables
Local functions for triggers and SQL overrides
Enable/disable edit, add or delete of rows. Enabling security requires your application to protect the web pages with web server access controls like those described at the Apache site. Your ultimate security is based on the authorization for the SQL user being used.
Background colors used in the HTML

Since this is coded in PHP and is part of the local installation, any of the features could be controlled based on parameters passed to the initial program or can vary based on environment variables like REMOTE_USER etc. Keep in mind that the local_config file is written in PHP and you must follow PHP syntax. This means it is very flexible and allows you to tailor the environment extensively, but also means small errors in local_config.php can render the application useless.

local_config Variables

See comments in the model_config.php file for a complete list of the variables used in FormEntry. Some of the more interesting variables in the local_config.php file that you will want to set include:

$LDB[form*] The database connection details are controlled by these variables for the table of data to be modified by the user.
$LDB[cfg*] The database connection details are controlled by these variables for the definition table managed by FormEntry.
$LDB[projects_dir] specifies the path to a directory where project files can be found. If this is relative (does not start with '/'), it is assumed to be relative to DOCUMENT_ROOT in the web server. For security, it is best to place this directory outside of where you installed the application (so one cannot get to the files using a web browser).
$CFG[allow_list] specifies which users may use this application. Using this requires web server access controls.
$CFG[title] Specifies the HTML title for the pages.
$CFG[allow_add] is a boolean. If set it allows the user to add records to the table.
$CFG[allow_delete] is a boolean. If set it allows the user to delete records from the table.
$CFG[commonjs] and $CFG[formjs] specify the URLs to Javascript files.
$CFG[stylesheet], $CFG[defsstylesheet], and $CFG[formstylesheet] specify the URLs to cascading stylesheets for the application.
$CFG[bulk*] controls details when doing 'bulk' imports as described elsewhere.
$CFG[deftable_create] provides an SQL create statement for the definition table.
$CFG[langtable_create] provides an SQL create statement for the language definition table.

See the model_config.php file provided with the distribution and read the comments for specific details.

Cascading Stylesheets

The look of formentry pages is controlled by several variables in the local_config file:

$CFG[stylesheet] controls the basic page.
$CFG[defsstylesheet] controls details when administering FormEntry and setting the details for each project form.
$CFG[formstylesheet] controls details of the form the end user interacts with.
$CFG[formjs] contains a few constants for background colors.

A very large number of details on each page use their own class. This allows you to control many of details of the look of a page. For instance the stylesheets allow you to use a different font or background color compared for a required field compared to a normal field. Each project can have its own stylesheets by simply setting the correct $CFG variable.

Not quite everything is controlled in the CSS files. A few details of the look and feel are controlled by JavaScript constants in form.js. If you want to change the background color of the field in focus (now a light yellow), you'll want to modify the constants in form.js.

You should avoid modifying the distributed files directly since the next release of FormEntry will replace the changes you have made. Rather you should start by copying the file using a new name change the associated local_config variable and then modify the new file.

Language Support

Support for multiple languages in FormEntry consists only of a means for the installation to provide changes to the page generated for the user. This includes alternatives in each definition for label, select values, hint, HTML comment, and the default value.

In the local_config.php the variable $CFG[languages] is provided and must specify at least one language as well as it's abbreviation. Additionally, you must also provide $CFG[config_language] and $CFG[default_language] as shown in this fragment:

    //  Language support. Must have at least one and it must be the default.
    $CFG[languages] = array('English' => 'EN', 'Suomi' => 'FI', 'Uppercase' => 'UC');
    $CFG[config_language] = 'EN';      // Language definition table is in
    $CFG[default_language] = 'UC';     // Default language to show forms in

In this case we provide for three languages, where English was used for the definitions. In this case when you Edit each definition, you see two additional links as seen above. Selecting one of these links gives you a prompt like that on the right -- inviting you to provide a replacement string in the new language.

This language support is far from complete. We have provided only a way to provide the basic web page in a new language. Informational and error messages generated by FormEntry are still in English or the configuration language.

Overriding SQL Methods

FormEntry provides a means for the local installation to modify the SQL just before it is executed - providing the ultimate control of the data. To enable this, all the installation needs to provide is a subroutine of the correct name for each of the basic SQL methods: select, insert, update and delete.

In each case FormEntry will detect the override subroutine and pass it a set of parameters sufficient to generate the proper SQL command. The SQL command is then executed with no further modification. We used this feature recently to take a conventional application and eliminate any case when the data was really lost. Rather our database had a flag which was used to indicate which row was actually 'active'. Our goal was to never delete update or delete data from the database, but only insert new rows and use the active flag to control what rows were 'live'. Ask to see the code if this application interests you.

All override subroutines all return an SQL statement and may be defined in the local_config.php file or in the project configuration file. The routines and parameters are:

OVERRIDE_FormSelect($table, $query, &$searchcol) where $table is the name of table, $query is an array of columns and search values and $searchcol is an array of col,values for HTML output.
OVERRIDE_FormInsert($table, $keys, $vals)) where $table is the name of table, $keys is a comma delimited set of keys to be inserted, and $vals is a comma delimited set of values for keys to be inserted.
OVERRIDE_FormUpdate($table, $sets, $prikey, $prival) where $table is the name of table, $sets is a comma delimited set of key=value strings, $prikey is the primary key, and $prival is primary key value.
OVERRIDE_FormDelete($table, $key, $val) where $table is the name of table, $key is the primary key, and $val is primary key value.

Quick Links:

Direct questions to: Terry Gliedt tpg@hps.com (Include 'Formentry' in the subject line so my SPAM filter lets your message through.)

This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. See http://www.gnu.org/copyleft/gpl.html