Contents

We have information about the database, and various settings, and also some general notes.

Setup

So, you want to install the thing do you?

Universal array

There are six universal arrays that are required.

These should all be of the same length. Shortname, type, length and required should not be changed after installation, and behaviour is undefined in such situations. (I suggest that if required is changed, the worst that could happen would that you could get application error messages when editing entries (saying that a field is required, but hasn't been filled in). Type might result in bigger errors, shortname would probably result in losing information.)

Once you've made sure the settings file contains all it needs to, and all the databases are created, you can run setup.php which will do, something.

Database format

There is one table in the database.
The structure is determined by the settings file at installation/initialisation.
The first field is always id, size 10 NOT NULL auto_increment int, which is the primary key.
The last field is always requireverification tinyint(1) NOT NULL.

The example "short courses" system has the following structure:

This is a hold over from the original courses system, so that the databases are compatible. For a new system, with no data, it may be better to have requireverification after id.

Into the future there maybe an additional field flagging items as "hidden", there should be an install time option which should not be changed, whether this is the case or not. Such a field would have to be not the last field if backwards compatibility was important. Mind you, when installing the new system

Adding new datatypes

The following files should be modified (as of 12 April 2009) when adding new data types:

At the moment, import.php does not do proper type checking (at least, not for all types, only for number and date).

Both add.php and edit.php no longer need to be changed, val.php and form.phphave count down the number of places from four (two each in add.php and edit.php) to two. val.php and form.php are simply included in the appropriate places in add.php and edit.php yay!

Database access and escaping.

All database access should be done through the functions provided in the file dbaccess.php which should be included at the top of all files. Database escaping should be happening in these functions, thus, no need to worry in other spots. HTML escaping should happen before it is displayed (in display.php and edit.php) not when adding to the database.

Settings and options

This describes, hopefully, all the possible settings and options for the settings.php file (or whichever name you use). Not all of these have to be defined in all cases. Where the order matters, it is noted.

database

$dbname
The database name
$dbserver
The database server (most likely "localhost")
$dbpass
The password for the database user
$dbuser
The database user.
$tbprefix
What prefix to use before the table name (not needed, but included to make it easier to switch between different, but similar, systems)
$tbname=$tbprefix.''
The table name to be used

Authentication

There are four possible levels:

As you go down the list, permissions accumulate (so at 4, adding, editing and deleting do not need authentication, but at 3, deleting does). Certain things, such as verification, deletion, and viewing the dashboard page, always require authentication.

Permissions thus cascade for the three things that are permitted (I could have added verification and dashboard to number 5, but they just always require authentication regardless.

$authenticationlevel=7;
Authentication level, 0, can't do anything. 1 require login to do everything, 2 require login to do everything but add, etc.

The QDSCSUAP (authent.php) system is used. When trying to take an action, depending on the number, the file will be included thus requiring authentication. See authent.php for how this system works, and for how to change the password. For our purposes, just include the file everywhere an action needs to be checked if they have permissions or not.

Verification

Levels:
$verificationlevel=2;
A number from the list above.
$displayneedverification = true;
Boolean. If true, display items that require verification. Can be overridden by a ?displayneedverification= option in the GET requrest. (In the GET request, the following numbers are possible: 0 is false, 1 is true, and show everything else as well, 2 is true, and show only items needing verification.)
define ('DISPLAY_VERIFICATION_CHECKBOX',true);
Whether to display the verification check box on the edit form.

Sending email settings

It is possible to make the system send an email when a new record is added. These settings determine if that happens, and the format of the email when it is sent. As of 29/11/2010, there is the possibility that this feature simply doesn't work. It hasn't been tested for a bit.

define ('GT_SEND_MAIL',true);
Whether to send an email whenever a new record is added.
$GT_email_subject
The emails subject line. Should no contain new line characters.
$GT_email_beforerecord
What should be before the record in the email. (E.g. "Dear all, here is another fascinating confession, I hope you enjoy.", perhaps if going to a list.)
$GT_email_afterrecord
What should come after the record in the email. (E.g. "As always, if you wish to unsubscribe, please go to ...", again, if for a list.)
$GT_email_from
Which email address should the email be "from"?
$GT_email_additionalheaders
String to be inserted at the end of the email header. This is typically used to add extra headers (From, Cc, and Bcc). Multiple extra headers should be separated with a CRLF (\r\n). (Not required for adding the "from header".)
$GT_email_to
To whom should the email be sent? (Could be a list email if it is configured to allow that.)

Other settings

$errlev //sort of a debug thing, 0 nothing shows, silently fails (or dies), 7 everything show, including debug msgs.

$displayadminlinks=true; //displays the edit, delete and verification links for each item

table structure

shortname, type and size should all be arrays of exactly the same length. Don't change them after setting up the system.

headings, explanation and required are also arrays, also should be the same length as the previous three. 'Required' shouldn't be changed after setting up the system (such behaviour is undefined in the system), but the other two can be.

As well as these, each item will have some things that will be for each. An ID, and a "verify" binary option thingy.
$shortname
an array of strings. Certain names are reserved, and should not be used here.
Terms and words that can not be used include:

The ordering here for $shortname is what order it will be displayed when outputting the data. See also $formordering for the order of the fields on the add and edit screens. This will also be the name of the field in the DB table.

Allowed types

possible types are:

the following types don't work 100% just now. :

Both URL's and emails maybe validated when added/edited.
multichoice, select, url, and email are all equivelent to text ('varchar') for the database.

$type an array of strings, the number being the same number as shortname, and each string has to be one of the given types. /* the length of text and number fields text, select, url, email: any within limits of DB (varchar in a MySQL db) multichoice: Length must be long enough to include all possible options, and a seperator between each one. date: 10 (Make sure it is always ten, it probably won't work otherwise.) number: within limits of DB (int in a MySQL db) binary: 1 (It would be really silly to have this anything other then one, anything else will result in undefined behaviour.) textarea: whatever, 3000 is about 400 words. image: maximum size in kb for the image. Max filename length is always 256. */ $length = array $heading //label and heading, also known as long name, Have it for URL's as well, it is needed at least for adding/editing. //will add a class to the label tag of "required", and force a check for the item. Otherwise class is "notrequired" $required array, same length as previous arrays Only required if you are going to have select types, an array of arrays. $select For each shortname which is type "select" (as defined in the previous arrays) (or into the future, multiplechoice), have that shortname as the key, pointing to an array which has all the possible options. Only required if you are going to have multichoice types, an array of arrays. $multichoice For each shortname which is type "multichoice" (as defined in the previous arrays), have that shortname as the key, pointing to an array which has all the possible options. Same as select.
$multiplesize
int "This sets the number of visible choices for many from many menus." - HTML 3.2 Reference. Multichoice
define ('MULTI_SEPARATOR',' / ');
what separates items in a multi-select in the DB and when exported. Should not be the same as the constant COMMA because, if it is, when exporting, well... Also, it would be good if this looked good when displaying, a good choice might be " / ".
define ('SHOW_MULTI_HELP',true);
Whether to show multiple choice help.
//Which text/select should the URL be anchored to, if any? If blank, will display as an extra item in the table. //this is required for every URL, if you don't want the URL to link off something, have blank. //However, don't have multiple URLs linking off the one item. It will be invalid, and only the first will be used. $urlanchor for those types defined as URLs //Will add a class to the TD tag when displaying. An array of arrays, the key is the shortname, pointing to an array. For the shortname, have an array of possibilities. Each possibility, if in the table, will be displayed as <td class="...">... $tdcssclass = array ( 'continent' => array (' Not applicable','Africa', 'Americas', 'Asia', 'Europe', 'Oceania'), 'country' => array ('UK','South Africa','USA') /* 'xxx' => array ('',''), */ );//what class should be added, must have the same number as things as above. $tdcssclassclass=array ( 'continent' => array ('nocolour','cone','ctwo','cthree','cfour','cfive'), 'country' => array ('csix','cseven','ceight') /*'xxx' => array ('','')*/ );
define ('SELF_LINK_URL',true)
URL's not anchored above to a specific text, should link to themselves. (They will be displayed regardless.)
define ('DATESPAST',true);
dates can be in the past (but still after afteryear)
For dates, an array, with the shortname again being they key. Each date type should be included in each setting. // dates must be before (or on) this year, and after (or on) this year. $afteryear = array ('todate'=> '2008', 'fromdate'=> '2008' ); $beforeyear = array ('todate'=> '2020', 'fromdate'=> '2020' );
define('TEXTAREAWIDTH',100);
for all textarea the width of the text area box.
define('TEXTAREAHEIGHT',10);
for all textarea the height of the text area box.
define('SHOW_TEXTAREA_HELP',false);
If "The total number of characters should not be more than 3000. This limit is enforced by stripping all extra characters from the input." Should be displayed before the text area fields.
define ('BINARY_TRUE_DISPLAY','true');
what should be display for binary options set to true.
define ('BINARY_FALSE_DISPLAY','false');
what should be display for binary options set to false.
define ('UPLOAD_DIR','uploads/');
Where uploads (such as images) are placed. Should be accessible from the web if you want images to be displayed. Folder must exist, and be writable by php. Should end in /

strings

Each of these can be as long as you want, and include HTML. You should include <span> or <div> tags around this text, at least, it will make it more likely to be compliant HTML.

$beforeform string Text to be displayed before the add and edit forms: Can include HTML. $afterform string text to be displayed /after/ the add and edit forms: Can include HTML. $beforetable string text to be displayed before table $aftertable string to be displayed after table $legend string legend for the frameset around the form, and for the title, heading and other things.

misc

$formordering
array of numbers, the order in which items should be displayed in the form, i.e. when adding or editing items. Starts from zero. Each number corresponds to the shortname setting. As of 13/11/2010 this has been disabled. As of this writing, form2.php is where the stuff is.
define ('URLTESTHTTP',true)
constant if true, will check for the existence of $urlbegin at the start of URLs and add it if not there. $urlbegin = array('http://','https://');// can be either a string, or array of strings. If none of the array are at the start, and the constant above is true, will insert the first item in the array. Strongly suggested to only allow HTTP HTTPS and FTP.
define ('SIZE_OF_TEXT_TO_DISPLAY_IN_TABLES',50);
// how many characters from text areas should be displayed in the table format.
define ('SIZE_OF_ELLIPSE_TITLE_TEXT_IN_DISPLAY',50);
// there is an ellipse displayed after the text mentioned above. It has a title (tool tip) with more of the item, how much should be displayed? (This ellipse links to the single view for the whole row.)
define ('LENGTH_TEXT_FIELD',20);
//the length of the text boxes when editing or adding items.
$displaynumbers
boolean, will display a string "There are exactly $numrows items in the database. Not all may be displayed.<br".IBBR.'>' if true.
define ('DUP_SELECT',true);
//Boolean used in form.php, should the current selection be duplicated and selected (which allows, sort of, changes to be made to the select options), or should it only be included once? See ~ 137, 145 in form.php.
$orderby
string, a comma separated list of items from the $shortname array. When displaying in table format, the results are initially presented sorted by the first, then the second, etc. It is plausible that this may not work as expected. File a bug report if that is the case.

Castle captcha like system

All the following must be defined.

define ('INCLUDE_CASTLE',true);
Should we use the Castle 'captcha' like system?

Please see Castle help for possible options, and meanings for the following:

define ('CASTLE_CAPTCHA',1);
Which captcha to use?
define ('CASTLE_OPTPARM1','Please enter the text "castle" in the box.');
Optional paramater one. (For captcha 1, a question to answer.)
define ('CASTLE_OPTPARM2','castle');
Optional paramater two. (For captcha 1, the answer to the question.)
define ('CASTLE_USEJS',false);
whether to use JS to make things slightly more difficult for bots (and impossible to use without JS).
define ('DATE_FORMAT', 'Y-m-d'); string How to format dates when displaying them. See the PHP date function. http://www.php.net/date $xhtmlc boolean //XHTML compliant? It is intended that for every "single" (self closing) tag (e.g. br, input etc.), that IBBR be added. If this is true, ' /' is then inserted. If it is false, nothing happens. if ($xhtmlc) { $ibbr=' /'; define ('IBBR',' /'); } else { $ibbr=''; define ('IBBR',''); } $versionofsoftware int or string.

JavaScript settings

define ('INCLUDE_CC',true);
boolean, if true, will include javascript to change the case of text fields.
define('INCLUDE_FILTER',true);
boolean, if true, filtertable.js will be included after the table, so that the table can be filtered.

export settings

The following settings are used by the export.php file:

define ('COMMA',',');
string delimiter for the CSV, if not defined ',' is used. (If using multichoice, be sure MULTI_SEPARATOR is not the same as COMMA.)
define ('QUOTE','"');
string enclosure for the CSV, if not defined, '"' is used.
define ('EXPORT_FILE_NAME',date('Y-m-d').'.csv');
what the name of the file should be by default. If not defined 'export.csv' is used.
define ('ALLOW_EXPORT',true);
Whether or not to allow anyone to export (that is download) all the records, and any uploaded files.

Notes and issues

Import and export

Both import (import.php)and export (export.php & archivefolder.php) work to a limited extent. However, neither is particularly robust. Import in particular is quite, fragile. As mentioned above import does not do proper type checking; as mentioned in bug 0035, and in the help file, import has trouble with quotes. Import takes CSV file, preferably one that's been exported from the system and has the same COMMA and QUOTE values. By default, the CSV file is treated as having headings, and the first line is ignored. If this is false, as part of your get request, add "?dhh=false".

Program stuff, and how the program is written

$stupidswitch is, as far as I can tell, only set to true in the dashboard. If the stupid switch is set, don't load up the settings file.

Changing data types, size and shortname (changing unchangable)

It is strongly discouraged that you change "type", "size" or "shortname" after setting up the system. If you do, and if you don't follow these instructions, the whole system could crash down upon you. (Even if you do follow these instructions, the system might crash, remember, there is no warranty for any of this.) You might be better off exporting everything, deleting everything in the database, and starting from scratch to setup the system with the new settings. Then, import.

Precautions

In all cases, you should make sure that no one is using the system while you are changing these. How to do that is left as an exercise to the reader

Shortname

You tell me.

Type

Change the type array in the settings file as you like. (Update all other settings as you go, including size if you are going from select to multichoice, for example.) If the type you are moving from is incompatible with the type you are moving to, make sure to update the database removing all incompatible entries.

Size

Change the size in the settings file. Update the size in the database (making sure it is the correct database and table).

Adding extra fields/columns

Update the settings file. Make sure that the settings file is consistent (all the required arrays have the same number of entries). Using a tool like phpmyadmin, add the extra column into the database, making sure it is the same size (length) as you entered in the settings file.

Available CSS Classes

The following classes are generally available for forms

'formelement'
In a div, wrapped around each form element (the labels, form controls etc.)
'required' and 'notrequired'
Indicate if a particular field is required or not. It is up to you to show, using CSS, that a class is required, the program will provide no other indication. This are attached to the same label tags as have 'heading' (see next entry) as a class.
'heading' and 'explanation'
The heading and explanation will be echoed within label tags and will come attached with these attributes.
'jscontrol'
Where possible, all JavaScript controls have this class.
'helptext'
"Help text", which can be turned on and off, have this attribute. This includes how many chars a textarea field type can have, and how many entries there are in the table. Only used in spans.
'warning'
Text areas use JavaScript to limit the number of characters entered. If too many are entered, a warning (with classes "helptext" and "warning") is displayed. Only used in spans.