Before version 0.25, most forms where written by hand in HTML, directly in the PHP code. This was boring to edit, and could lead to errors. Since then, it has been fully rewritten with a more powerful template system.
The first goal of that system was to have a faster integration of skins and CSS things, as we were waiting for a new graphic design. The second goal was to help writing things faster and remove the possibility of having things without user input validation.
At present, there is 3 main template functions, here's how it works.
1. General idea
The main principle is to describe what you want to edit, and send it to the template functions. These functions then handle the rest: drawing of HTML forms using the preferences in the skin (CSS not yet implemented ATM) and SQL. What I call describe here is mostly SQL tables. Anyway, you will understand more with examples.
2. dtcDatagrid() function
Many times, it's needed to represent the values in the SQL as a grid or table of values. Each line of the table drawn in the HTML form represent a line in the SQL table. Each lines can be edited or deleted, and it's possible to create a new entry.
Let's say you have a table called my_table in SQL like this:
id | login | fruit | color | like_it
1 | alex | apple | green | yes
2 | alex | grapes | black | no
3 | roger | apple | green | yes
4 | roger | grapes | black | no
Then you will want to display it like this:
Fruits that you like:
Fruit Color Do you like it? Action
[Apple......] [Green....]\/ [X] Yes [ ] No [ Save ] [ Delete ]
[Grapes.....] [Black....]\/ [ ] Yes [X] No [ Save ] [ Delete ]
[...........] [Blue.....]\/ [X] Yes [ ] No [ New ]
With the controls being like this (hard to display on a text if I don't explain): input text, pop-up, radio button and then submit buttons.
Then the code is simply like this:
$dsc = array(
"title" => "Fruits that you like:",
"table_name" => "my_table",
"action" => "fruits_editor",
"forward" => array("login"),
"where_condition" => "login='alex'",
"cols" => array(
"id" => array(
"type" => "id",
"display" => "no",
"legend" => "id")
"fruit" => array(
"type" => "text",
"legend" => "Fruit",
"color" => array(
"type" => "popup",
"values" => array("blue","green","black"),
"display_replace" => array("Blue","Green","Black"),
"legend" => "Fruit"),
"like_it" => array(
"type" => "radio",
"values" => array("yes","no"),
"legend" => "Do you like it?")));
$my_fruit_editor = dtcDatagrid($dsc);
I wont explain all, as most is easy to guess.
- "table_name" is the name of the table in the SQL.
- "action" will be written as a input hidden HTML control so you can use the dtcDatagrid() function more than once in a single form.
- "forward" is a simple variable that will be forwarded as input hidden control so you have in after your user click on the buttons and is optional.
- "where_condition" will be used as a WHERE close in all SQL query to SELECT, INSERT and UPDATE data in SQL and is optional.
- "cols" describe all the SQL columns that you want to display and edit. Each element of this array is the name of the SQL field to use.
Then for each of the type of control you want to use there are some options that you can select. At least "type" and "legend" (text to be displayed so the user know what he is editing like "Color") must be filled.
Some types have mandatory parameters like pop-ups and radio buttons MUST have at least "values" to set the allowed values, with "display_replace" that contains the values to display in the HTML instead of the values in SQL (in this example, it's used to have the color's first letter with upper case).
Note that all the SQL tables that you want to edit with this function must have an auto-increment value so it's possible for the template function to identify the item that is to be edited or deleted.
3. dtcListItemsEdit() function
This function is used mostly (but not only) by the user control panel, for example for subdomains, emails, ssh, or ftp accounts. It works almost the same as the dtcDatagrid() but has some other field that you need to fill (mainly for titles).
Also, if you want to use this function in the user panel, you have to set a "where_list" option so that a defined user cannot edit the values of an other admin. It's also mandatory to check that parameter. In the subdomain editor for example, a call to:
checks that the logged user owns the domain that is being edited, and then the folowing option is added:
"where_list" => array(
"domain_name" => $domain["name"]),
On the same way, this function edit the values of the config table. It's used only in admin/inc/dtc_config.php (and this is also currently where this function resides). Nothing special to tell about it, it works the same way, even if internally it's a bit different. Maybe I have to add that there is no "table_name" in it as there is only the table config to be edited with it.
5. Field Validation
If you use a pop-up, radio buttons or check box, the template system will check against the allowed values. If they are not correct, the SQL wont be sent. If you use a text, text area or password, then an addslashes() call will be added to escape the variable. So it's quite safe to use those functions.
Moreover, it's possible to add the following checks on the format of each variable:
- subdomain - a valid subdomain
- subdomain_or_ip - a valid subdomain or IP address
- ip_addr - an ip address
- domain_or_ip - a valid domain name or IP address
- dtc_login - a login within DTC namespace (that is: 4 to 16 chars with only letters and numbers plus the - (dash) char)
- dtc_login_or_email - a login within DTC namespace or an email
- dtc_pass - a dtc password within DTC namespace
- email - an email address
- number - a valid number (composed of 0 to 9 char only)
Just use "check" => "subdomain" for example, if you want to add this type of checks.
some changes made on 28.03.2007
Not quite sure where to put this so I will just describe it here.
I have added a new type "readonly" this will create a read only text box.
I have also added some new parameters that will be used by text, read only and password but have only been tested with read only.
[hide_create] => "yes" -> Can be used to hide a field in creation mode, it will only be displayed in edit mode
[callback] -> this routine will be called to get further data it will need to display. The id (autoinc) will be passed to the routine and
it is expected that an array will be returned containing 2 values:
"value" => $value,
"happen" => $happen);