# DaDaBIK Documentation

Project name: DaDaBIK (DaDaBIK is a DataBase Interfaces Kreator)
Author: Eugenio Tacchini (eugenio.tacchini@unicatt.it)
Web site: http://www.dadabik.org/
Last release: 4.2 (released February 18, 2007). This documentation is about the 4.2 release, if you need the documentation for a previous release please read the documentation file included in each download package.
License: DaDaBIK is released under the GPL license.
Support: If you need general support for DaDaBIK, please use the support forum and not my e-mail address, I immediately receive via e-mail all the posts. Contact me directly only if you have particular requests, or just to say: "Thank you" :)

# Introduction

DaDaBIK is a free PHP application that allows you to easily create a highly customizable front-end for a database in order to search, insert, update and delete records; all you need to do is specifying a few configuration parameters.

Starting from version 4.0 alpha DaDaBIK uses the ADOdb Database Abstraction Library in order to support as many DBMS as possible, at the moment it has been tested on MySQL, PostgreSQL, Oracle and MS SQL Server.

The strength of DaDaBIK lies in its ability to be customized. For each field of a table you can choose:

- if the field should be included or not in the search/insert/update form and results table
- its label (what will appear in the form near the input field)
- its content format (e.g. numeric, alphabetic, e-mail, url......)
- the input type (e.g. select, date, text, rich text editor, password......)
- the possible values, also driven from another table (foreign key support)
- and more...

DaDaBIK also allows you to handle multiple tables. Other features include file uploading, export to CSV, checking for possible duplication during an insert, authentication and authorization restrictions on view/update/delete, e-mail notices, table aliases.

The graphic layout of DaDaBIK is customizable to help you to embed its forms in your own site.

DaDaBIK differs from other applications like PHPMyAdmin since it doesn't enable the complete administration of a database, but rather to easily create a simple and customizable Web application that manages a group of tables by allowing search/insert/update/delete operations. DaDaBIK's target user is not the DB administrator but rather the final user.
DaDaBIK is available in Italian, English, Dutch, German, Spanish, French, Portuguese, Croatian, Polish, Catalan, Estonian, Rumanian, Hungarian, Swedish, Slovak and Finnish.

# Requirements

- PHP

- should work from version 4.05
- magic_quotes_gpc = on in php.ini (this is the default setting)
- magic_quotes_sybase = on in php.ini if you use DaDaBIK with MS SQL server, Oracle or another DBMS that escape ' with '' instead of \' (for MySQL and PostgreSQL the default magic_quotes_sybase = off is ok)
- PHP upload enabled if you want to use the upload feature (see PHP manual for php.ini and file permissions settings)

- MySQL

- version >= 3.23.x (not tested with previous releases but probably works)

- PostgreSQL

- Only tested with 8.x version, probably works with 7.x version too.

- Oracle

- Version >= 9.

- MS SQL Server

- Only tested with 2000 version.

- A pre-existent database with AT LEAST ONE table to manage, with DaDaBIK you can't create databases and tables!!

# Installation

1. Copy everything which is contained in the directory program_files in a directory under your Web server
2. Open the file /include/config.php with a text editor and edit it (specify at least $dbms_type, $host, $db_name, $user, $pass, $site_url, $site_path)
3. Run the file http://your_host/your_dir/install.php to install DaDaBIK
4. Open the file http://your_host/your_dir/index.php in your browser and have fun!! You can now start using DaDaBIK.
   You can now insert, search, update, delete the records of the tables contained in the database $db_name. You should have set a primary key for each table managed with DaDaBIK if you want to delete and update records, otherwise DaDaBIK won't show you the corresponding buttons.
   Also the "search similar record" feature during the insert needs a primary key.
   The "insert e-mail notice" feature needs a primary key auto increment field to work.

Please send me the URL of your site (just to be aware of it) if you are using DaDaBIK in a public site.

Please leave the link
Powered by: DaDaBIK
somewhere if you use DaDaBIK; it isn't compulsory but I would really appreciate it.

# Upgrade from previous versions

1 - If you want to upgrade from 3.0 beta or 3.0 to 3.1 beta without loosing your configuration you don't need to re-install DaDaBIK:

- Replace all the old files with the new ones (keep your upload folder if you want to save the uploaded files )
- Update your /include/config.php file using your old configuration settings
- Run the file http://your_host/your_dir/upgrade.php to upgrade DaDaBIK

2 - If you want to upgrade from 3.1 beta to 3.2 beta or 3.2 without loosing your configuration you don't need to re-install DaDaBIK, but note that, since the authentication model has changed a lot from 3.1 beta to 3.2 beta, an automatic procedure to import the old DaDaBIK users is not available, so this information will be lost after the upgrade:

- Replace all the old files with the new ones (keep your upload folder if you want to save the uploaded files )
- Update your /include/config.php file using your old configuration settings
- Run the file http://your_host/your_dir/upgrade_3.2.php to upgrade DaDaBIK

3 - If you want to upgrade from 3.2 beta or 3.2 or 4.0 Alpha or 4.0 Beta or 4.0 Beta 2 to 3.2 or 4.0 Alpha or 4.0 Beta or 4.0 Beta 2 or 4.0 without loosing your configuration you don't need to re-install DaDaBIK:

- Replace all the old files with the new ones (keep your upload folder if you want to save the uploaded files )
- Update your /include/config.php file using your old configuration settings

4 - If you want to upgrade from 3.2 beta or 3.2 or 4.0 Alpha or 4.0 Beta or 4.0 Beta 2 or 4.0 to 4.1 beta or 4.1 release candidate 1 without loosing your configuration you don't need to re-install DaDaBIK:

- Replace all the old files with the new ones (keep your upload folder if you want to save the uploaded files )
- Update your /include/config.php file using your old configuration settings
- Run the file http://your_host/your_dir/upgrade_4.1.php to upgrade DaDaBIK

5 - If you want to upgrade from 4.1 beta or 4.1 release candidate 1 to 4.1 release candidate 2 or 4.1 release candidate 3 or 4.1 or 4.2 beta or 4.2 without loosing your configuration you don't need to re-install DaDaBIK:

- Replace all the old files with the new ones (keep your upload folder if you want to save the uploaded files )
- Update your /include/config.php file using your old configuration settings
- Run the file http://your_host/your_dir/upgrade_4.1_rc2.php to upgrade DaDaBIK

As an example, if you want to upgrade from 3.2 to 4.1 release candidate 2 both steps 4 and 5 have to be executed.

# Configuration

Introduction
The configuration of DaDaBIK can be managed at two different levels:

1. Some general configuration parameters can be set from the file /include/config.php, just by opening it with a plain text editor and editing it. The file is self-explanatory. At this level you can, for example, set the database you want to manage with DaDaBIK, or enable/disable some DaDaBIK features
2. For a more analytic tuning you are supposed to use the administration section http://your_host/your_dir/admin.php. At this level you can choose the table you want to include/exclude and, for each table, create your own DaDaBIK interface, choosing for example the field you want to include/exclude from the forms, the content of each field, the labels....
   Also the administration section is self-explanatory, so in the following paragraph we will explain in detail only the interface configurator, which is the core of the DaDaBIK configuration; you can reach it from the home page of the administration section.

The graphic customization can be done by changing the files /include/header.php and /include/footer.php and by using the CSS files /css/styles_screen.css and /css/styles_print.css, the former is the main one, the latter is used only when you print a page produced by DaDaBIK.
From the files under /include/languages you can customize all the sentences DaDaBIK uses.

Interface configurator
Here is the meaning of all the parameters you can set for each table field:

- Label: what will be displayed as label of the field in the form
- Field type, select among:
  - text: a text box
  - textarea: a textarea box
  - rich_editor: a rich text editor that allows to easily insert/modify HTML content, works only with MS Internet Explorer
  - password: a password text box
  - insert_date: the current date will be automatically inserted into this field when you insert a new record in your table; you should not include an insert_date field in the insert/update form, see below to understand how to include/exclude a field from a form. Note that the corresponding database field type must be date
  - update_date: the current date will be automatically inserted into this field when you update a record in your table; you should not include an update_date field in the insert/update form, see below to understand how to include/exclude a field from a form. Note that the corresponding database field type must be date
  - date: three select fields: day, month, year. Note that the corresponding database field type must be date
  - select_single: an HTML listbox field, see below to understand how to specify the items
  - generic_file: an input field that allow the user to browse in his file system and upload a file. You need to specify the allowed file extensions in config.php. Note that the corresponding database field type must be varchar
  - image_file: the same as the above, but in this case DaDaBIK supposes that the file is an image and shows it when the record is displayed. You need to specify the allowed file extensions in config.php. Note that the corresponding database field type must be varchar
  - ID_user: the username of the current user will be automatically inserted into this field when you insert a new record; you should not include an ID_user field in the insert/update form, see below to understand how to include/exclude a field from a form. Note that the corresponding database field type must be alphanumeric (e.g. char, varchar....)
  - unique_ID: a unique ID generated by using the PHP function unique_ID() in conjunction with microtime(), getmypid() and md5() will be automatically inserted in this field when you insert a new record into your table; you should not include a unique_ID field in the insert/update form, see below to understand how to include/exclude a field from a form
- Content type: the content determines what check procedure DaDaBIK should use during an insert/update and how a field value is displayed; select among:
  - alphabetic: only alphabetic characters allowed
  - alphanumeric: all characters allowed
  - numeric: only numeric characters allowed
  - url: only URL with a correct syntax allowed, support from http/https/ftp protocols and port numbers; field displayed as a URL link
  - email: only e-mail address with a correct syntax allowed; field displayed as a mailto: link
  - html: all characters allowed; DaDaBIK doesn't perform a conversion from special characters to HTML entities with htmlspecialchars for the fields having this content type. For example, this content type can be used to enter a full custom URL in the standard format used on web pages. eg: <a href="#">Link Text</a> entered in the field will produce Link Text displayed in DaDaBIK (where # is the actual link).
  - phone: only phone numbers with a correct syntax - e.g. +39025689781 - allowed
  - city: not available for the moment
- The following parameters are used to choose if a field must be displayed and used in the various sections of DaDaBIK: Field present in the search form?/Field present in the results page?/Field present in the details page?/Field present in the insert/update form?
- Is the field a required one? Choose if the field should be required during insert and update procedures
- Check for duplicated entries during insert? Choose if the field value should be checked for possible duplication during the insert procedure
- Other choices allowed? Choose if the field, a select_single one, can accept also values other than the pre-set options during an insert/update. If the user add a different value, it is included in the list of pre-set options. Note that, if the field is a foreign key (see Primary key field for a definition), the "other" value is used to insert a new record in the primary key table. The use of this option together for a foreign key field makes sense only if there is just one linked field. This feature requires a table (the one containing the foreign key) with a primary key which is an auto-increment field.
- Option to include: specify the possible options of a select field e.g. ~~teacher~manager~student~, in this example the first option is blank.
- Primary key field: if a field is a select_single, and the options must be driven from another table (so the field can be considered foreign key for DaDaBIK, regardless of a real dbms foreign key declaration), specify here the corresponding primary key
- Primary key table: specify here the table that contains the primary key field
- Linked fields: the fields in the primary key table you want to display. Imagine you have a table albums_tab that contains information about CDs. In this table you have a field ID_author that "links" the table authors_tab. If you want to display, for each record, first_name_author and last_name_author of author_tab, you have to use ID_author as primary key, authors_tab as primary key table, first_name_author~last_name_author as linked fields
- Order by: the linked field by which you want to order the items in the listbox
- Order type: the order type (ASC or DESC, if you leave blank ASC is the default) to be used on the "Order by" field
- Search operator: specify is_equal, contains, starts_with, ends_with, greater_than, less_than or a group of this operator separated by "/". E.g. if you specify just "contains" DaDaBIK will use always the contains operator for this field during the search; if you use "exactly/contains" DaDaBIK will create for this field a listbox with the operators exactly/like, the user can then choose the preferred one during each search operation
- Prefix: for text, textarea and rich_editor fields you can choose a prefix default value for your field, e.g. "http://" if your field need to be filled with a Web url; the prefix will be displayed directly in the insert form, but if the user doesn't fill-in the field it will be considered as blank
- Default value: for text, textarea and rich_editor fields you can choose a default value for your field, the value will be displayed directly in the insert form
- Width: the width of an input box, used with text, password, textarea and rich_editor boxes
- Height: the height of an input box, used with textarea and rich_editor boxes
- Maxlength: the maximum number of characters allowed in the input box, used with text, password, textarea, rich_editor boxes and select_single
- Hint: the text of a hint for the user that will appear during the insert/update procedure near the input field
- Separator: you can safely leave the default one, ~

# Authentication

An authorization model is available to prevent unauthorized accesses and to allow users to:

- Delete only their own records
- Modify only their own records
- View only their own records

The owner of a record is the user who entered it.
To enable authentication, each table you want to protect must have a field whose field type is set to ID_user; you also have to set $enable_authentication = 1 in /include/config.php. By setting the parameters $enable_delete_authorization, $enable update authorization and $enable_browse_authorization you can then customize your authorization model.
There are two types of users: normal users and administrator users. Administrator users can view and manage users list by using DaDaBIK itself.
DaDaBIK is released with the following default administrator user:

- username: root
- password: letizia

DaDaBIK uses by default the table users_tab to store user information, but you can also use your own users table, changing the $users_table_* parameters in /include/config.php. User passwords are md5 encrypted.
Before inserting a new user it is necessary to create the encrypted password by following the "create password" link.

# Multiple function views: creating two instances of DaDaBIK

Sometimes it is necessary to have one view for users where they can only view the data and a second view for the database administrators to manage the data being displayed. This will help you set up two instances of DaDaBIK to look at the same database.

1. Install your first instance of DaDaBIK using the default DaDaBIK table prefixes contained in the /include/config.php file (last two variables in the file).
   http://your_host/your_dir/install.php

   If you want things to look the same in both installations like headers, footers, logos, etc., you can make those changes now so that you only have to make them once; otherwise you can worry about prettying it up later.

2. Copy your entire DaDaBIK folder into a new folder you wish to use for the second instance: http://your_host/your_dir/ <-- all contents copied to: http://your_host/your_dir/admin-dir-name/

3. Open /include/config.php from the /your_dir/admin-dir-name/include/ folder and change the table prefix and table list name in this file to something like:
   dadabik_admin_
   and
   dadabik_admin_table_list

   It does not matter what your prefixes are -- just so long as they are different from the first install prefixes.

   Also in /include/config.php, change the $site_url to the correct URL for the admin area so the correct installation is used.

4. Now, install your second instance of DaDaBIK:
   http://your_host/your_dir/admin-dir-name/install.php

5. This will create additional tables with your admin prefix for all your original DaDaBIK tables also. You should remove them by going to the admin interface for the second instance you just installed and uninstall those tables.

   For this example, we'll assume you used the following:
   1st install: "dadabik_" table prefix with "dadabik_table_list" table list name
   2nd install: "dadabik_admin_" table prefix with "dadabik_admin_table_list" table list name

   In the admin for the 2nd install (http://your_host/your_dir/admin-dir-name/admin.php), "uninstall" each table you see beginning with "dadabik_".

6. Now you can manage both instances independent from each other through:
   http://your_host/your_dir/admin.php
   and
   http://your_host/your_dir/admin-dir-name/admin.php

   Beyond this, you can add password protection to your admin area through .htaccess (do a search in the support forums for this or goog it for tons of info) or other methods.

# Security

Since the files install.php could be used by malicious users in order to re-install your DaDaBIK installation, it is a good practice to protect it or to delete it if you don't need to re-install DaDaBIK or a single DaDaBIK table.

# Coding guidelines

If you want to contribute to the DaDaBIK code you have to follow some coding guidelines; this document: http://www.evolt.org/article/PHP_coding_guidelines/18/60247/ fits most of DaDaBIK coding style rules, in particular follow the sections:

- Tabs v. spaces
- Variable names
- Loop indices
- Function names
- Function arguments
- Including braces
- SQL code layout
- Quoting strings
- Shortcut operators
- Turn on all error reporting

In addition and/or modification to the above document sections, here are other rules:

- The first brace must be put on the first line of the block.
  Examples:
  if (isset($username_user)){ is ok
  if (isset($username_user))
  { is wrong
- if, else, while , for....closing brace must be followed by a // end if, // end else, // end while, // end for.....comment.
  Examples:
  if (isset($username_user)){
  echo 'Username set';
  } // end if
  else {
  echo 'Username not set';
  } // end else
- Array name must be plural and terminate with the _ar suffix.
  Examples:
  $users_ar is ok
  $user, $users, $user_ar are wrong
- Global variables must not be used, functions must receive as parameters all the variables they need. Exceptions are made for: $conn, $quote, $current_user, $current_user_is_administrator, $submit_buttons_ar, $normal_messages_ar and all configuration variables (the ones set in /include/config.php)
- $_GET variables are not used directly; corresponding variables are set in index.php.
  Examples:
  if (isset($_GET["page"])){
  $page = $_GET["page"];
  } // end if
  After the above setting, the $page variable is used in the code.

Other coding rules should be learned looking for the DaDaBIK code. Please contact me if you have any doubts.

# FAQs

I am looking for an old version of DaDaBIK, can anybody help me with a link to DaDaBIK 3.0 ??
Old releases of DaDaBik can be found at sourceforge.

I get:
"[06] Error: during database connection.
MySQL server said: Client does not support authentication protocol requested by server; consider upgrading MySQL client".
Why?
It is due to the new authentication protocol introduced with MySQL 4.1.x; here:
http://dev.mysql.com/doc/mysql/en/old-client.html you can find several solutions.

I get [08] Error Message
I get "Error during query execution"
Please open the file include/config.php, look for the variable named $debug_mode. Set it to 1, so that you'll be able to see what the error is. If you still cannot figure it out post the error message in the support forum.

I can't see the edit/delete record icons in the results view
You did not set a primary key in the table, so you are able to see the records but DaDaBik cannot edit/delete them.

I get this message:
"Call to undefined function mysql_server_info......"
The version of PHP you're using is prior to 4.0.5, please comment relative lines in common_start and set the mysql version (variable $mysql_server_version) by hand e.g. 32306 for 3.23.6.
Otherwise ask your sys-admin to upgrade PHP to some more recent version.

I get "your database is empty" error, why?
You first have to set up a database and then you can install DaDaBik.
For more info on what DaDaBik's purpose is please see documentation

Are multiple primary keys supported?
Not yet. Not planned. If you're interested in developing it please contact me (eugenio.tacchini at unicatt.it).

How to set magic_quotes_gpc to On in php.ini?
If you can't access the php.ini file try placing a file called .htaccess in the main folder of your DaDaBIK installation.
The content of this .htaccess file must be:
php_flag magic_quotes_gpc On
further reference for this problem can be found here

Page not showing after Insert/Update.
Open include/config.php and make sure the variable $site_url is set to the the complete path to your DaDaBIK installation.
(E.g http://www.yoursite.com/dadabik_folder/)

How to change graphic layout etc?
The role of the files is self-explicatory
include/header.php
include/footer.php
This takes care of the general styles
css/style.css
These two functions take care of forms and results table styles
change build_form() and build_results_table()

# Known bugs and limitations

- Malicious users could use PHP scripts for setting session variables to particular values in order to bypass the login procedure and get unauthorized access to DaDaBIK. These scripts must be hosted on the same domain where the DaDaBIK target installation is hosted.
- Insert/search/update fail if one or more field names contain blank spaces or dots (e.g. "my field" or "my.field" are not allowed, use "my_field" instead).
- Quote characters, such as ' ` ", could lead to problems if used in table and field names.
- Primary keys composed by multiple columns are not handled.
- The "check for duplicated" doesn't work with file types: DaDaBIK doesn't warn about similarity when two files have a similar name; furthermore, the "check for duplicated" feature causes uploads to fail during insert, in particular the files are not uploaded if some possible duplicated records are found and the user decides to insert it anyway.
- HTML content is not set correctly as "Default value" (interface configurator).
- When a new option of a select_single field with linked fields is inserted, the current user is not inserted in the ID_user field of the linked table.
- Estonian, Polish, Croatian, Spanish and Slovak languages are not completed.
- Using field names containing the value set for $alias_prefix, $null_checkbox_prefix, $select_type_select_suffix, $year_field_suffix, $month_field_suffix, $day_field_suffix could lead to unexpected results; you can change the value of the above variables editing /include/config.php
- Insert/update don't work correctly on PostgreSQL and Oracle if the user choose "Other...." from a select_single field menu and the field has some linked fields.
- DaDaBIK needs table names in lower case to work on PostgreSQL.
- DaDaBIK doesn't work correctly on Oracle if table and/or field names are in mixed case.
- The sql logging feature doesn't work on Oracle and produces an "LOGSQL Insert Failed" message.
- The rich editor interface (TinyMCE) is displayed in english only.
- The insert e-mail notice doesn't work on PostgreSQL and Oracle.
- The field renaming feature of the administration page doesn't work as expected if the renamed field is used in one of the following properties: "Primary key field", "Linked fields", "Order by" in the interface configurator related to any of the tables. In particular, after the renaming, you will get "[08] Error: during query execution" messages from the DaDaBIK front end; you should edit the above properties by hand, renaming the field in the interface configurator.
- The "refresh installation" admin operation doesn't work correctly and could lead to an interface configurator settings loss if the installation is the result of an upgrade from a DaDaBIK version < 4.1 rc2; the "refresh installation" bug is considered fixed only for tables installed (DaDaBIK installation from scratch or single table installation from the admin interface) using a DaDaBIK version >= 4.1 rc2.