FormEntry Projects

Quick Links:

• Introduction
• Configuration
• Definitions
• Javascript
• Imports/Exports

A 'project'. is simply a name which identifies yet another configuration file, in addition to the site defaults (local_config.php). This allows you to define a named set of control values. You invoke a project by just passing the parameter 'project=name' on the URL when FormEntry is invoked or select it from the projects.php SELECT list.

Projects allow you to create one installation of the application and yet provide tailored versions for differing sets of your users. For instance, you might have one project for your HR people so they can modify a table relating to personal issues. Another project might allow operations to see data in a table related to access controls. Using projects keeps each independent of the other and separates the connection details for data and definition tables.

The project name identifies a PHP file in $LDB[projects_dir] which is included after the application starts. In the local_config we could specify:

    $LDB[projects_dir] = '/home/http/conf/formentry_projects';

In this case a project named 'people' would resolve to a configuration file '/home/http/conf/formentry_projects/people.php'. This is a PHP file and must start with <? and end with ?>. Details in this file are the same as for local_config. Keep in mind variables set in a project file override whatever is set in local_config.

While projects are not absolutely necessary since you can always provide all the database connection details in local_config.php, but as soon as you have more than one use of FormEntry they immediately become vital. You are encouraged to use projects from the start.

A Complete Example

Let's assume you want several HR applications using FormEntry:.

1. Update non-vital personnel data (e.g. mailing addresses)
2. Update vital personnel data (e.g. salaries, deductions)
3. Update identifying personnel data (e.g. name changes, social security numbers)

A very simple database table for this data might look like this:

DROP TABLE IF EXISTS people;
CREATE TABLE people (
  employeenum INT NOT NULL PRIMARY KEY,
  fname VARCHAR(20) NOT NULL,
  mname VARCHAR(20),
  lname VARCHAR(64) NOT NULL,
  address1 VARCHAR(64) NOT NULL,
  address2 VARCHAR(64),
  city VARCHAR(64) NOT NULL,
  state VARCHAR(2) NOT NULL,
  zip VARCHAR(12) NOT NULL,
  salary FLOAT(8,2) NOT NULL,
  payrollperiod CHAR(1) NOT NULL
);

Here's a fragment of the local_config.php file:

    $LDB[form_sqltype] = 'mysql';
    $LDB[form_sqlhost] = 'localhost';
    $LDB[form_sqldb]   = 'HR';
    $LDB[cfg_sqltype] = 'pgsql'
    $LDB[cfg_sqlhost] = 'support.mycompany.mydomain';
    $LDB[cfg_sqldb]   = 'formentry';
    $LDB[cfg_sqluser] = 'FE_prod';
    $LDB[cfg_sqlpass] = '^%y#zz.4';
    $LDB[projects_dir] = '/home/http/conf/formentry_projects';
    $CFG[projects_allow_list] = array('hrsupport');
    $LDB[maintable] = '';
    $CFG[allow_list] = array('hradmin');
    $CFG[allow_add] = 0;
    $CFG[allow_delete] = 0;

In this case we provide all the details for the defintion general access to only one non-HR user, an admin. We define full access to the definition table, but not everything needed for a project yet. We're going to define three projects - each with somewhat different definitions, allowing changes to only some columns by varying users.

Project hrchange

Now we create projects for each of our three applications (as described elsewhere). The first project is 'hrchange' which allows a few HR users to update a set of columns in the database.

    <?
    // This is file '/home/http/conf/formentry_projects/hrchange.php'.
    $LDB[form_sqluser] = 'hrdb1';
    $LDB[form_sqlpass] = '*^%%$d5';
    $LDB[maintable] = 'people';
    $CFG[allow_list] = array('hr1', 'hr2');
    $LAF[title] = "HRCHANGE: Update Simple Details in HR";
    ?>

In addition to the project configuration file, there is a definition table which describes to FormEntry exactly how the search page and pages for changing the data should be presented. The definition table for 'hrchange' limits only its users to only change a few things:

As you'd expect, all of the columns for our table are here, but if you look at this more closely, you'll notice several things from the summary screen even without looking at each column definition:

• The key, employeenum, is hidden. While it appears in the form, it is not shown in the HTML <form> shown our users.
  
  
• You can see that lname is underlined - meaning it is searchable.
  
  
• The name fields, fname, mname, lname, are marked 'read-only' which you cannot tell directly from this summary. Notice that address2 is not required.
  
  
• Two columns, salary, payrollperiod, are crossed out. They will not even show up in the HTML <form>.
  
  
• There is little verification enabled here, except for employeenum, salary. In the real world you probably want something better. Zipcode could be checked with a regular expression at least.
  
  

After the project is ready and you have made your changes to the definitions, the <form> is ready for the HR users. We provide this link for the users:

   /formenty/form.php?project=hrchange

The form presented to HR users for this project just allows the user to enter part or all of the last name. Unless there are hundreds of people with the same last name (certainly possible in a large company), this will be 'close enough'. As you can see, we searched for 'son' and got one hit (Johnson-Dvorak). When the user selected 'Edit', we see the page to the right.

Here is what our 'hrchange' users see. The name fields are there, but cannot be changed. The address-related fields can be modified (notice state is a drop-down list). If you look under the covers, you'd find that employeenum is a hidden field in the HTML <form>. Clicking on 'Save Data' will save the data back into the datebase and take you back to the search screen.

Project hrvital

The next project is 'hrvital' which allows one HR user to update a set of columns in the database.

    <?
    // This is file '/home/http/conf/formentry_projects/hrvital.php'.
    $LDB[form_sqluser] = 'hrdb2';
    $LDB[form_sqlpass] = '*^)9::5';
    $LDB[maintable] = 'people';
    $CFG[allow_list] = array('hrlead');
    $LAF[title] = "HRVITAL: Update Vital Details in HR";
    ?>

Now we create the 'hrvital' project and definition table, just like before. This looks very much like that for 'hrchange' except salary is not crossed out as this can be changed. The search page is unchanged. The URL for our users would be /formenty/form.php?project=hrvital.

Here is what our 'hrvital' user sees. As before, the name fields are there, but cannot be changed and the address-related fields can be modified. There is a new field for this user, salary. This time we demonstrate some of the error checking that is done by the Javascript. In the first error, you can see the value for salary is not a valid number and in the second the salary is too large (not within the range 300-3000).

Project hrall

The next project is 'hrall' which allows one HR user to update all columns in the database, as well as add or remove people from the database.

    <?
    // This is file '/home/http/conf/formentry_projects/hrall.php'.
    $LDB[form_sqluser] = 'hrdb3';
    $LDB[form_sqlpass] = '*ss(k25';
    $LDB[maintable] = 'people';
    $CFG[allow_list] = array('hrhead');
    $CFG[allow_add] = 1;
    $CFG[allow_delete] = 1;
    $LAF[title] = "HRALL: Update Any Detail in HR";
    ?>

Now we create the 'hrall' project and definition table, just like before. This looks very much like that the others, except now all fields are modifiable. The URL for our users would be /formenty/form.php?project=hrall.

The search page has changed. First we can see that we've made salary searchable - just to prove we can. Next we show the result of not providing any search criteria (just click on select) and we see the entire database (ours is pretty small). Lastly, note that we can now delete people from the database, as well as add someone.

Here is what our 'hrall' user sees. If you first look behind the error message, you can see that all fields are changable - except for the employee number. We can't change this because it's the table key. If the employee number needs changing, you must add a new user. This might make a case that employee number should not be a key.

Now to the error message. This is another Javascript check on salary, but what you can't tell is that we just tried to save the record and had not changed the salary. The salary was incorrect in the database. This either means the condition in the definition needs changing or the person needs a serious raise.

This is what the user sees when you select "Add a New Record" and looks just like an Edit, except this time, the employee number may be specified. Since this is a table key, whatever the user enters will be a key -- and must be unique. This might make a case that employee number should not be a key and you should be using an auto-increment field for the key.

Quick Links:

• Introduction
• Configuration
• Definitions
• Javascript
• Imports/Exports

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