The data stored in KOTA can best be described as meta data for the database tables. It defines the look of the forms inside kOOL by which the users edit the data in the database - whether it'll be a checkbox, a textfield or a select box etc.

KOTA is defined in /inc/kota.inc and it can be extended by plugins or by the installation specific file config/kota.inc. In addition to the definition of the array itself some KOTA specific functions are declared in this file too.

The structure of KOTA

$KOTA["ko_event"] => array(

"_multititle" => array(

"eventgruppen_id" => "ko_get_eventgruppen_name('@VALUE@')",

"startdatum" => "sql2datum('@VALUE@')",

"startzeit" => "sql_zeit('@VALUE@')",

),

"_listview" => array(

10 => array("name" => "startdatum", "sort" => "startdatum", "multiedit" => "startdatum,enddatum"),

20 => array("name" => "eventgruppen_id", "sort" => "eventgruppen_id"),

30 => array("name" => "kommentar", "sort" => "kommentar"),

40 => array("name" => "startzeit", "sort" => "startzeit", "multiedit" => "startzeit,endzeit"),

50 => array("name" => "room", "sort" => "room"),

),

"url" => array(

"pre" => "",

"form" => array(

"type" => "text",

"params" => 'size="60"',

),

),

[..]

);

There is such an entry for every database table that can be edited directly by the users. The first element is called „_multititle“ which defines the label to be used when multiediting this field. The field name serves as the key and the value can contain a function to be applied to the value ('@VALUE@') in the database before it will be rendered. In the above example the sql date format would get transformed in a nicer format.

The section "_listview" contains a numeric array with the different columns for the list display. The numbers give the order, so you can e.g. add a column through your plugin between two existing ones. Each entry is an array with a mandatory entry for name, which defines the database column and two optional entries. "sort" sets the column to be sorted for. If this stays empty, the user can't order by this column. The entry "multiedit" defines the columns used for multiediting this column in the list view. If this is not defined, the column given in "name" will be used. If no multiediting should be allowed for a column, then set "multiedit" to FALSE.

After that you'll find an entry for every field in this table which is an array itself. The first keys „pre“, „post“ and „list“ define the way the value should be treated before rendering in the form, after beeing submitted by the user and how it should get displayed in a list view. These keys don't have to exist.

The last key „form“ defines the type of form element used for this db field. See more about the possibilities further down.

Functions for „pre“, „post“, „list“, „_multititle“

They way the values are stored in the database might not be suited for display on the webpage. This is why there are these four possibilities to change the value at certain points of processing.

„multititle“	The keys used here will be used as titles if this field is beeing multiedited. Several keys are possible, separated by comma.
„pre“	This function is applied before the value is rendered in the html form.
„post“	After submitting the form the value for this field will be postprocessed by this function to ensure the value is in a given range and doesn't break the database. This a good place to work with format_userinput().
„list“	This is the way the value is being processed before it gets displayed in the list.

Most often you just want to prepare the value for HTML output which is handled by the function ko_html(). In this case you can just enter "ko_html" for "pre" e.g.

For "post" you might want to use one of the formatings available in the function format_userinput(). You can just pass the mode to "post", so you don't have to write the whole function call "format_userinput("@VALUE@", "js")" all the time.

The possibilities of these functions are almost endless because it is also possible to call any external function. The string "@VALUE@" will get substituted with the actual value from the database or the form submission.

The following example demonstrates this with a date field:

"startdatum" => array(

"pre" => "sql2datum('@VALUE@')",

"post" => "sql_datum('@VALUE@')",

"form" => array(...),

),

If it is not enough to work on the submitted value, you can call any function which will have more information available for postprocessing:

"nachname" => array(

"post" => (in_array("nachname", $COLS_LEUTE_UND_FAMILIE) ? "FCN:ko_multiedit_familie" : ""),

"form" => array(...),

),

First of all this postprocessing is only performed if the field „nachname“ is found in the given array. If this is the case, then you are able to call a function by specifing its name as „FCN:NameOfFunction“. This function will get two arguments the first being a reference to the submitted value and the second beeing an array with the following content:

array("table" => $table, "col" => $col, "id" => $id);

Where $table, $col and $id stand for the name of the table, the column and the id beeing worked on.

The different types for the inputs

You can use all types defined in the general form template /templates/ko_formular.tpl for the different db columns. The following table shows the most common used types. The third column shows the additional setting that can be made for the different types.

GENERAL	These can be set for every field	- params (string): html parameter that are passed to the form field - new_row (Boolean): Forces the next field to be on a new line - value: Current value - name: The html name of the input field. Is autogenerated at the creation of the form in the form koi[TABLE][col][id]. id is 0 for a new entry. - desc: The field's label. If not set, it will be assigned from the LL value kota_TABLE_FIELD
text	Input field	- params: e.g. 'size=“11“ maxlength=“11“'
textplus	This is basically an input field, but there is a select field presented for easier selection of already made entries.	- params: e.g. 'size=“0“' for the select field - params_PLUS: Parameters for the textfield to the right of the select. e.g. 'size=“60“ maxlenght=“200“'
textarea	Textarea	- params: e.g. 'cols=“60“ rows=“5“'
color	Input field with color chooser popup	- params: e.g. 'size=“10“ maxlength=“7“'
file	File upload	- params: e.g. 'size=“60“' The file will be saved as /my_images/kota_TABLE_COLUMN_ID.EXT
select	Single select	- params: e.g. 'size=“0“' - values: Array with the values for the available options - descs: Array with the labels for the available options
doubleselect	Multiple select with two select boxes	same as select plus - avalues: Array with the values for the selected options - adescs: Array with the labels for the selected options - avalue: Comma separated list of the selected values - js_func_add: JS function to be called upon selection of an entry. Defaults to double_select_add.
peopleselect	Doubleselet to choose one or more people from ko_leute	same as doubleselect The adminfilters will be applied, so a user will only see the people he has access to.
dynselect	A dynamic select with size > 1 which can change the list items using an AJAX call. Will be rendered as optgroup-select when multiediting.	Same as select
dyndoubleselect	As dynselect but multiple values may be selected using a second select holding the selected entries.	Same as doubleselect

The generation of the form: ko_multiedit_formular()

Once the KOTA is configured correctly, the generation of the form is a matter of one function call, here you see the example to edit a smallgroup:

$form_data = array(„title“ => $title, „submit_value“ => $submit_value, „action“ => $action);

ko_multiedit_formular("ko_kleingruppen", "", $id, "", $form_data);

In the array $form_data some values are set to be used in the form:

title: The title above the form. e.g. „Edit smallgroup“
submit_value: The value of the submit button. e.g. „Save“
action: The action to be performed after submission of the form. e.g. „submit_edit_kg“
cancel: Action to be performed upon cancelling the form, e.g. "list_kg"

The function itself has following parameters:

$table	db table
$columns=““	the columns to be edited. All of them if empty
$ids=0	the ids of the entries to be edited. 0 for a new entry
$order=““	define the column and ASC or DESC for the ordering of the different entries
$form_data=““	values as specified above
$return_only_group=FALSE	Boolean that lets you receive the $group array as return value, which enables you to add other input fields - not defined in KOTA - and pass the adapted $group array to the form template.

Save the submitted values: kota_submit_multiedit()

After the submission of the form the function kota_submit_multiedit() handles the whole postprocessing and storing in the database. The function accepts 3 arguments

&$error: Error id if there is an error with the processing
$rights=““: An array with access rights for the ids of the edited entries. If not empty, only the entries are stored, that are set to true in this array.
$log_type: Specify the logtype for this operation. If empty, then it will be „multiedit“.TABLE.