The kOOL Table Array - KOTA

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

Form Layout

The _form_layout array can be used to precisely define the layout of a single-edit form for a table. It is a field in the $KOTA array of the respective table. Let's for example consider a table called 'car'. Then the _form_layout of that table could be defined the following way:

$KOTA['car']['_form_layout'] = array(
	'general' => array(
		'sorting' => 10,
		'groups' => array(
			'general' => array(
				'sorting' => 10,
				'group' => FALSE,
				'rows' => array(
					10 => array('manufacturer' => 6, 'model' => 6),
					20 => array('age' => array('colspan' => 6, 'onOwnRow' => TRUE)),
					30 => array('description' => 12),
				),
			),
		),
	),
	'interior' => array(
		'sorting' => 20,
		'groups' => array(
			'electronics' => array(
				'sorting' => 10,
				'group' => TRUE,
				'rows' => array(
					10 => array('navigation' => 6, 'radio' => 6),
					20 => array('media_system' => array('colspan' => 6, 'onNewRow' => TRUE)),
				),
			),
			'seats' => array(
				'sorting' => 20,
				'group' => TRUE,
				'appearance' => 'success',
				'rows' => array(
					10 => array('heatable' => 6, 'customizable' => 6),
				),
			),
		),

	),
	'technical_data' => array(
		'sorting' => 30,
		'groups' => array(
			'engine' => array(
				'sorting' => 10,
				'group' => TRUE,
				'rows' => array(
					10 => array('hp' => 6, 'torque' => 6),
					20 => array('co2' => 6, 'fuel' => 6),
				),
			),
			'driving_performance' => array(
				'sorting' => 10,
				'group' => TRUE,
				'rows' => array(
					10 => array('from_0_to_100' => 6, 'max_speed' => 6)
				)
			)
		),
	),
	'_default_cols' => 6,
	'_default_width' => 6,
	'_ignore_fields' => array('color'),
);

In the following, the different elements and attributes of this toy form_layout will be explained.

Tabs build the top level hierarchy. The example contains 3 tabs (on lines 2, 16 and 38). If there is only one tab, it won't be displayed as a tab. The title of the tab will be fetched from the locallang values (key: 'kota_group_title_cars_interior' for the 'interior' tab). The sorting of the tabs can be defined by setting the 'sorting' field (as shown on lines 3, 17 and 39).
Groups are one level below the tabs in the hierarchy. Each tab can contain any number of groups. If you want the group to be graphically displayed as such, you can set the 'group' field to TRUE (as shown on line 21). The title in that case will be fetched from the locallang values (key: 'kota_group_title_cars_interior_electronics' for the 'interior' -> 'electronics' group). Again the sorting can be set by setting the 'sorting' field (as shown on line 19).
Groups can have different appearances (remember: if you set 'group' to FALSE, then the group won't have any special graphical appearance as such). The different appearances correspond to the contextual types of the bootstrap front-end framework. The default appearance is 'primary'. An example is shown on line 30.
The fields are arranged in rows. See line 9 for an example: Each row is an array that contains entries of the following form: 'fieldName' => fieldWidth. Each row has a total width of 12, so a field of width 6 will span exactly half the row.
All fields that have a KOTA form definition but are not described in the _form_layout will be appended to the 'general' group in the 'general' tab. If you don't want a field with a form definition to appear in the single edit form, you can add it to the '_ignore_fields' array (as shown on line 60).
If fields are appended automatically, then they will have a width equal to _default_cols (line 58). If such a field ends up on a single line, you can use the _default_width (line 59) to set the width of a field in that case.

koFormLayoutEditor

The koFormLayoutEditor class offers functions for manipulating the _form_layout arrays. This can come in handy if you want to add/remove fields from within a plugin. Consider lines 10 and 24 of the example _form_layout definition: there the value of the array entry is not just the width of the field but an array. This array can contain the following entries:

colspan: this sets the width of the field. If not set, then the value of _default_cols will be used.
onOwnRow: when manpulating the _form_layout with the koFormLayoutEditor class, then this field will always be on an own row, no matter how other fields are moved around.
onNewRow: when manpulating the _form_layout with the koFormLayoutEditor class, then this field will always be on a new row, no matter how other fields are moved around.

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.

Datenschutzerklärung