The Generic Control Panel system allows the quick and easy creation of control panels for a table in a database, allowing for addition, alteration and deletion of data whilst enforcing referential integrity if necessary.
To create a control panel for the Generic Control Panel system, the definitions for the control panel must be stored in a text file with a .cgf extension in the directory specified by the system (by default, the system searches for .cgf files in the ./cgf folder).
Each tag is specified in square brackets [ ] and will always have a matching end tag [/ ]. Any parameters for a tag are specified between the start and end tag in the form xxx="yyyy" Note that the quotes are always necessary even if the value is numeric.
A .cgf file in it's simplest form comprises of a title, a database definition, a master table definition and at least one form element. EG:
[title]Companies[/title]
[database]
dsn="addressbook"
uid="eb0s0021"
pwd=""
[/database]
[master]
table="company"
uKey="company_id"
nameField="company_name"
autoUpdate="false"
x="0"
y="40"
[/master]
[input]
caption="Company name"
field="company_name"
datatype="text"
x="250"
y="40"
[/input]
The [title] tag indicates the title that will appear on the button for the control panel and also on the control panel itself as the main heading.
The [database] tag contains all the information on how to connect to the database that the table to be administered is in. This is done either by specifying a dsn, uid and password (dsn, uid, pwd) or by providing a complete connection string (using the connectionString parameter).
The [master] tag specifies the table (and other necessary values) which is to be administered using the Generic Control Panel system. It requries the table name (table), the unique key of the table (uKey) which must be numeric, the name field (nameField) which is the field that will be displayed in the list of records, whether or not the list of records should update automatically (autoUpdate) - can be either "true" or "false", and the x and y coordinates (x,y) of the position that the list of records should be placed in.
There are currently 5 types of form elements. Input boxes ([input]) which allow for either numeric (int, shortint, numeric etc.) or text (char, varchar) fields, select boxes ([select])/muliableselect([clselect]) which allow selection of a value from another table, checkboxes ([checkbox]) which allow for boolean (bit) values and text area's ([textarea]) free text to meno fields.
In order to preserve referential integrity within the database (ie. in a relational database, deleting an item in one table that is referenced by an item in another table would break referential integrity), the [eri] tag is provided to make the system first checks to see if the record can be deleted safely in as many table as needed.
The [eri] tag has the following parameters:
Each [eri] tag included in the control panel instructs the system to check against a specified field (foreignKey) with datatype (datatype) in a table (table) (if dsn, uid & pwd or connectionString are specified it uses that to connect otherwise it uses the connection of the master table) to see if the record is referenced by any records in that table.
If the user tries to delete a record that is referenced by records in another table, the system will display an error message (errorMsg) and a list of the records (displaying the nameField and ordered by orderField) and can then (if desired) provide the user with a means of resolving the problem. This functionality is specified by the two boolean parameters: merge & delete.
If 'merge' is true then the system will, on encountering a record that cannot be deleted, provide the user with the means to change any records in other tables that point to the record to point to some other record in the same table.
If delete is true then the system will, on encountering a record that cannot be deleted, provide the user with the ability to delete the records in the table that point to the offending record.
If both merge and delete are true then the user will have the option to choose which action to perform.
If neither merge or delete is true then the system will simply not allow the record to be deleted.
All .cgf files go into a folder called 'cgf'. The sub folders inside the generic folder each have a folder name which is used as the title of the page. The folders may be hidden by adding a @ sign in front of the first character of the folder name and therefore the folder is hidden.
Also the files within the folders can be hidden too. This is also done by placing a @ sign in front of the first character of the file name.
A file can call by using either a querstring or form with the id of genricfile and the value the
subdicrtory/filename (?genricfile=northwind\northwind.cgf)
see ref,readonly
A file can call by using either a querstring or form with the id of load and the value the
subdicrtory/filename (?load=northwind\northwind.cgf)
see ref,readonly
A record can called by using either a querstring or form with the id of ref and the value the
from the Ukey paramerter in the [master] section of your .cgf file.
see readonly
A record can be made readonly by using readonly = "true" in the input sections of your .cgf file.
A record can be made updateonly by using updateonly = "true" in the [master] section of your .cgf file.
The String is optional and can be written as follows: Announcements(""). Therefore if this is used, the function will use the system's ("live") variable in order to work out the announcements group.
If String=text, then the announcements will use this as the Name of the announcements group and bring up all announcements relevant to the text name i.e. Samples.
If String=number, then the announcements will show the announcement as a number by
The following code is a full example of a .cgf file. This control panel is used to administer the "country" table in the lookup database. It has inputs for the country name and country abbreviation code, it has a select box to select the language spoken in that country. 3 other tables reference countries in the country table so referential integrity checks are included for these.
[title]Countries[/title]
[required]64[/required]
[database]
dsn="lookup"
uid="eb0s0004"
pwd=""
[/database]
[master]
table="country"
uKey="country_id"
nameField="country"
x="0"
y="40"
[/master]
[input]
caption="Country name"
field="country"
datatype="text"
x="250"
y="40"
[/input]
[input]
caption="Country code"
field="code"
datatype="text"
maxlength="3"
x="250"
y="70"
[/input]
[select]
allowNull="true"
caption="Primary language"
table="languages"
field="language_id"
datatype="number"
nameField="language_name"
localKey="id"
x="250"
y="100"
[/select]
[eri]
dsn="samplesystem"
uid="uk90483"
pwd=""
table="samplestores"
foreignKey="country_id"
datatype="number"
nameField="store_name"
errorMsg="One or more records in the samplestores table refer to the item you are trying to delete. These record(s) are:"
merge="true"
delete="false"
[/eri]
[eri]
dsn="addressbook"
uid="eb0s0021"
pwd=""
table="location"
foreignKey="country_id"
datatype="number"
nameField="address1,address2"
errorMsg="One or more records in the location table refer to the item you are trying to delete. These record(s) are:"
merge="true"
delete="false"
[/eri]
[eri]
dsn="lookup"
uid="eb0s0004"
pwd=""
table="state_zone"
foreignKey="country_id"
datatype="number"
nameField="state_zone_name"
errorMsg="One or more records in the state_zone table refer to the item you are trying to delete. These record(s) are:"
merge="true"
delete="false"
[/eri]