Each module can have 4 different access levels numbered from 1 to 4. 0 means no access rights at all. The access rights for a single module for a user can be access through the function

ko_get_access($module, $uid, ...)

The second parameter may be omitted to get the access rights for the currently logged in user. After calling this function the global array $access will be filled with $access[$module]['ALL'], $access[$module]['MAX'] and $access[$module][$id] for each group (reservation item, event group, account etc). They all will contain a value between 0 and 4 where ALL will contain the ALL rights, MAX the maximum value over all single groups.

If you only need the ALL and/or MAX values you may also call

$all = ko_get_access_all($col, $uid, &$max)

This function may be a little faster as it doesn't apply all the group rights.

Access rights (OLD as of R39)

There are four different access levels per module called view (1), new (2), edit (3) and mod (4). A higher one always contains all the rights of the lower one. Usually they are stored in the variables called $group_view, $group_new, $group_edit, $group_mod and are being assigned in the function ko_get_admin(). The following example shows this for the events module „daten“:

list($item_view, $item_new, $item_edit, $item_mod) = ko_get_admin("daten",

$_SESSION["ses_userid"],

$group_view,

$group_new,

$group_edit,

$group_mod);

In the easiest case $group_* are just boolean. The second possibility is, that this variables are arrays containing the rights for different objects e.g. event groups identified by their ids. In the third case the access rights are actually stored in item_* which are return by ko_get_admin for every single item, e.g. used with reservations. The information for the reservation items is still stored in group_* but with item_* it is easier to get the rights for single items.

item_* is also used for people if the access is not granted to all people but is limited through a filter preset. Then item_* hold the information for every id of ko_leute whether the user may access it or not.

AJAX

All the AJAX functions are contained in /inc/js-ajax.inc, so you just have to include this in MODULE/index.php. With createRequestObject() an XMLHttpRequest object will be created which can be used to send requests back to the server with the function sendReq():

function sendReq(serverFileName, variableNames, variableValues, handleResponse)

serverFileName is the file on the server that should be called
variableNames: a comma separated list of variables that will get passed to the server (GET)
variableValues: a comma separated list of the values to the beforedefined variables
handleResponse: a javascript function to handle the response from the server

The functions called via AJAX for the different modules are stored in MODULE/inc/ajax.php. The first thing is to check for a valid session id passed to the server. This session is being restored for the duration of this php script to be able to check access rights, then the demanded action will be executed. Usually this script generates the necessary html code directly which will be passed to the javascript function do_element. This function expects the following string:

HTML-ELEMENT@@@HTML-CODE

This way the html element with the given id will be replaced with the html code after „@@@“. This makes it possible to refill the main content area „main_content“ with new content e.g. You can also have two or three elements replaced by new html code at once by just appending more of the above elements:

HTML-ELEMENT@@@HTML-CODE@@@HTML-ELEMENT@@@HTML-CODE

Template for lists

All the list views in kOOL are done by the template ko_list.tpl or ko_list2.tpl. ko_list.tpl is the older version where lists where done mostly manually. This method is now deprecated.

The new way is by using ko_list2.tpl which is accessed through the class kOOL_listview. Some of this class' methods are described in the following table. For a full reference check the source file in inc/class.kOOL_listview.php.

Example code to render a list is shown just below this table. But it might be best to check the kOOL source to find real life examples.

Class method	Description
init($module, $table, $editColumns="", $start="", $limit="")	Initialise the list by passing the module, the DB table, the edit columns (edit, delete, etc), the start and limit of a paged view
setAccessRights($data)	Allows you to pass access rights usually retrieved from ko_get_admin() to define rights for the rows in the list. Set to FALSE if no check is needed.
setActions($data)	Set the actions for each of the editColumns. This will be the value passed to the index.php script upon clicking the action button (e.g. edit or delete).
setStats($total, $start="", $limit="")	Pass the total number of entries and optionally start and limit, which usually get stored in a session variable per module.
setSort($enable, $action="", $current="", $current_order="")	Set values for sorting. The first parameter enables or disables the sorting. The others define the action handled by module/inc/ajax.inc and the currently order by column.

Example code to render a list with class.kOOL_listview

$rows = db_get_count("ko_eventgruppen", "id", $z_where);

ko_get_eventgruppen($es, $z_limit, $z_where);

$list->init("daten", "ko_eventgruppen", array("chk", "edit", "delete"), $_SESSION["show_start"], $_SESSION["show_limit"]);

$list->setAccessRights(array("edit" => $group_edit, "delete" => $group_edit));

$list->setActions(array("edit" => array("action" => "edit_gruppe"), "delete" => array("action" => "delete_gruppe", "confirm" => TRUE)));

$list->setStats($rows);

$list->setSort(TRUE, "setsorteventgroups", $_SESSION["sort_tg"], $_SESSION["sort_tg_order"]);

$list->render($es);

Template for forms

Most of the forms in kOOL are rendered through the template ko_formular.tpl. This can either be done through the function ko_multiedit_formular() which renders the form according to the definitions in KOTA or by manually defining an array with all the necessary information about the form. It is also possible to mix these two methods to manually extend a form defined by KOTA to add other form elements. See the form to enter new reservations for an example.

The following table shows the available form elements:

Input type	Description
text	A single lined text field (<input type=“text“ />)
text_mylist	A single lined text field with a button to paste values from mylist into it
textplus	Select field with the current values and a text field in the second column to add one, that is not in the list yet.
password	Password input field
textarea	A multicolumn, multirow textarea (<textarea>)
file	A file input field to upload files.
jsdate	A date select input with a DHTML popup to graphically select a date.
color	Input field to enter a HEX value for a color. With a color picker popup
label	Just text, no input element
checkbox	Checkbox
radio	Radio buttons
select	A simple select field
doubleselect	Two select fields next to each other to choose several elements
dyndoubleselect	For group module. The options of the select are refilled dynamically on selection
peopleselect	A doubleselect with people from ko_leute to select.
html	An html code which can contain anything - also other form elements
" "	Three spaces in a row will output an empty row - as a little divider.

Settings vs userprefs

Two different kinds of settings exist in kOOL. The settings are globally and the userprefs are only valid for a single user. The settings can usually only be changed by an admin user.

Settings are only updated in the database, new ones have to be added manually. This makes the contents of the table ko_settings the ultimate reference for the available settings. The userprefs are generated on demand for every user that sets them.

In some occasions there are default values stored as a setting that can be overwritten by a userpref. When a new login is created there are some userprefs that are created as well. These values can be defined in /lib/inc/ko.inc or in /web/config/ko-config.php, depending on whether they should be server- or only installation-wide. The submenus play a special role among the userprefs as they are generated automatically on creation of a new login according to the available modules. The available submenus per module are stored in /lib/inc/submenu.inc.

The following table shows the settings from ko_settings:

Setting	Description
cache_sms_balance	Number of Clickatell credits left. Value is cached so it doesn't have to be fetch from clickatell on every export.
cal_jahr_num	Number of month displayed in the yearly calendar
cal_woche_end	Last hour in the weekly calendar
cal_woche_start	First hour in the weekly calendar
change_password	Allow users to change their own password
daten_access_calendar	Define access rights for event module by event groups only (0) or by event groups and calendars (1)
daten_mark_sunday	Mark sundays in listview of events or not
daten_monthly_title	Column from ko_event to be used as title in calendar.
daten_pdf_show_comment	Add comments for events in monthly pdf export
daten_pdf_show_time	Display the hours in pdf export or not
daten_perm_filter_ende	End of the global filter for events (YYYY-MM-DD)
daten_perm_filter_start	Start of the global filter for events (YYYY-MM-DD)
daten_title_length	Maximum length of title in calendar, longer titles will be truncated
default_view_MODULE	Default view for a module MODULE
dp_commentrow	Columns from ko_event to be used as comment rows in pdf rota
dp_deadline_tag	Day of the deadline for the reminder for rota team leaders
dp_deadline_woche	Week of the deadline for the reminder for rota team leaders
dp_dienste	Integer: 1=Use all teams for export, 2=Only use selected ones
dp_fontsize	Fontsize for rota team export
dp_freetext_dienste	Comma separated list of rota teams, for which a free text may be entered
dp_leaderrole	ID of role from group module which marks the team leaders
dp_list_separator	Set a string to be used as separator between the team members
dp_mailtext_1	Text for reminder email
dp_mailtext_2	Text for email being sent to the rota team members
dp_mark_empty	Set to 1 to mark empty entries in rota pdf export
dp_max_templates	Number of templates used by a rota team for each event group
dp_namenformat	Integer specifing the layout of the name: 1=Firstname L., 2=Firstname La., 3= F. Lastname, 4=Firstname Lastname, 5=Firstname
dp_orderby	Can be "vorname" or "nachname" to sort the people selects by first or last name
dp_superdienste	Use superteams or not
dp_teamrole	ID of role from group module which marks the team members
dp_titel	Title for the rota export
dp_use_colors	Set to 1 to use colors for event groups in pdf rota
dp_use_presets	Set to 1 to enable the use of presets for rota shedulling
familie_col_name	A serialized array of the names of the columns for the family fields
fileshare_mailtext	Text to be sent for a fileshare email
geburtstagsliste_deadline_minus	Number of days back the birthdays should get displayed
geburtstagsliste_deadline_plus	Number of days ahead the birthdays should get displayed
info_email	Email used as sender for mails sent out of kOOL
info_name	Name of your organisation. Can be used as sender address for mail merge letters.
info_address	See info_name
info_zip	See info_name
info_city	See info_name
info_phone	See info_name
info_url	See info_name
leute_col_name	Serialized array of the names of the columns of ko_leute
leute_hidden_mode	0 for always display hidden addresses, 1 for never, 2 for "according to user setting"
login_edit_person	Let logged in users edit their own address data
mailing_mails_per_cycle	Number of mails to be sent on each call of mailing.php (through cronjob)
mailing_max_recipients	Maximum number of recipients for mailing mails. An error is thrown if more recipients are to be addressed. Set to 0 for no limit
mailing_only_alias	If this option is set then mailing emails are only allowed to recipients given by an email alias, direct sending using IDs is not allowed.
modules_dropdown	Use dropdown menu or not ("ja"/"nein")
ps_filter_sel_ds1_koi[ko_donations][person][0]	Serialized filter array of filter preset to be applied to the people select in the donations form.
res_allow_multires_for_guest	Allow guest user to reserve more than one item at once
res_mandatory	Comma separated list of mandatory fields for new reservations
res_mark_sunday	Mark sundays in listview of reservations or not
res_monthly_title	Column of ko_reservation to be used as title in calendar
res_pdf_show_comment	Add comments for reservations in monthly pdf export
res_pdf_show_time	Display hours on PDF export in reservation calendar
res_perm_filter_ende	End of the global filter for events (YYYY-MM-DD)
res_perm_filter_start	Start of the global filter for events (YYYY-MM-DD)
res_send_email	Recipients of alerts on new reservations
res_show_persondata	Display details about owner of reservations to guest user
res_title_length	Maximum length of title in calendar, longer titles will be truncated
show_dateres_combined	Combine reservations for events in calendar
show_leute_cols	Default columns to be displayed in leute module
show_limit_daten	Number of events / event groups per page in list view
show_limit_donations	Number of donations per page in list view
show_limit_dp	Number of rota teams per page in list view
show_limit_fileshare	Number of webfolders per page in list view
show_limit_groups	Number of groups per page in list view
show_limit_kg	Number of smallgroups per page in list view
show_limit_leute	Number of addresses per page in list view
show_limit_logins	Number of logins per page in list view
show_limit_logs	Number of log entries per page in list view
show_limit_news	Number of news / newsletters per page in list view
show_limit_reservation	Number of reservations per page in list view
show_limit_tapes	Number of tapes per page in list view
show_passed_groups	Displayed terminated groups
sms_country_code	Default country code to use for mobile numbers with not country code
sms_sender_ids	Comma separated list of allowed senderIDs for sms messages
tapes_clear_printqueue	Clear print list after printing
tapes_guess_series	Guess serie from tape title
tapes_new_minus	Number of days back events should be searched for for a new tape
tapes_new_plus	Number of days ahead events should be searched for for a new tape
tapes_preacher_from_dienst	Serialized array assigning rota teams to tape groups to specify where to get the preacher from
tracking_add_roles	If set to 1 the group selection when creating a tracking will show the roles also, otherwise only a group may be selected
tracking_order_people	Defines the way the people in a tracking list should be sorted. By role (role), first name (vorname) or last name (nachname)

Session variables

Settings about the current session are stored in session variables. Some of them get stored in userprefs on change so they will be the same when the user logs in again. Obviously their is information about the currently logged in user stored in the session as well.

This table shows the most important session variables:

Session variable	Description
ses_userid	User id of the logged in user
ses_username	Login of the logged in user
show	Current show case
show_start	Start of the list view
show_limit	Number of entries per page in the list view
sort_*	Sorting of the current list
sort_*_order	Sorting order of the current list
submenu_left	Comma separated list of the closed submenus to the left
submenu_right	Comma separated list of the open submenus to the right
submenu_left_closed	Comma separated list of the closed submenus to the left
submenu_right_closed	Comma separated list of the open submenus to the right

Multiediting

Multiediting allows a user to edit one or more columns of several database entries at once. The necessary form is generated by the function ko_multiedit_formular() and the information about the form elements is taken from KOTA. So if you can't or don't use KOTA for some forms you can still define the columns there, where multiediting should be possible.

In order for the editing icons to appear for a certain column, you must specify them in $KOTA:

$KOTA[db_table]["_listview"][num]["multiedit] = db_column;

e.g.: $KOTA["ko_event"]["_listview"][10]["multiedit"] = "startdatum,enddatum";

For every column in the list view zero, one or several columns from the database may be defined that will be edited in the multiedit form. Several columns might be useful for dates for example to have start and enddate in the same form.

If a user clicks on a multiedit icon the action „multiedit“ is issued. So there must be code to catch this action and to read in the selected rows and columns and pass them to the function ko_multiedit_formular().

ko_multiedit_formular($db_table, $do_columns, $do_ids, $order);

On submission of the form the action „submit_multiedit“ is issued which must be caught again in MODULE/index.php. You only have to check the access rights and call the function kota_submit_multiedit() to store the submittted values.

To raise the level of security for the multiedit action, a hash is generated with the columns and rows to be edited, which will be checked against the submitted values.

The same functionality may also be used for normal forms, where ko_multiedit_formular() takes a forth parameter which contains some form_data like the value for the form's title, the submit button's text, the cancel action and the submit action.

Installation specific configurations: ko-config.php

For a new installation of kOOL the default ko-config.php will be copied from /lib/install/default/config where most of the values are still empty. With the webbased installation most of these values can be set graphically but may be edited at any later point in time.

The following table shows the available options:

Variable/constant	Description
$HTML_TITLE	Title used in the browser's window
$MODULES	Array with the modules available to this installation
$WEB_LANGS	An array of languages available to this installation. All languages defined here must also be present in $LIB_LANGS set in ko.inc
$GET_LANG_FROM_BROWSER	Boolean which specifies whether kOOL should try to detect the browsers languages. The user can still change the language manually.
$mysql_user, $mysql_pass, $mysql_server, $mysql_db	Account information to access the kOOL database. You may specify a portnumber after the domainname if MySQL doesn't run on the default port.
$ldap_enabled	Boolean which enables or disables the use of an LDAP directory for the addresses
$ldap_admin, , $ldap_admin_pw, $ldap_server, $ldap_dn, $ldap_login_dn	Accont information for the LDAP account which is able to write and delete records. $ldap_dn holds the full dn to the directory in the DIT, e.g. „ou=kOOL_XY,dc=your,dc=ldap,dc=server“. $ldap_login_dn defines the dn where logins with access to LDAP will be stored, defaults to "ou=login,$ldap_dn" if left empty.
$BASE_URL	Absolute URL of this kOOL installation
$BASE_PATH	Absolute path to the web folder
$smarty_dir	Directory with the smarty subdirectories templates, templates_c etc.
$SMS_PARAMETER	Account information for the Clickatell user: user, pass und api_id. Optionally "sender_id" may be specified as a string or an array of possible values. These sender IDs have to be registered with Clickatell first.
$FAST_FILTER_IDS	Filter ids for the fast filter for the addresses (IDs from database table ko_fiter)
$PLUGINS	Plugins (see documentation about plugins)
WARRANTY_GIVER, WARRANTY_URL, WARRANTY_EMAIL	Name and URL of the warranty giver of this installation of kOOL. The warranty email address is used for error and bug reports, if set.
WEBFOLDERS	Boolean which enables or disables the use of webfolders through WebDAV
$WEBFOLDERS_BASE	Base path for the webfolders.
$WEBFOLDERS_BASE_HTACCESS	Base path for the .htaccess files used in the webfolders to define access rights
$FAMFUNCTION_SORT_ORDER	Array which specifies the order in which the names of families are concatenated
KOOL_ENCRYPTION_KEY	String containing the encryption key used for access through get.php. The other end of the communication has to use the same key, e.g. TYPO3 extension kool_base
ALLOW_SSO	Boolean to allow single signon from e.g. TYPO3 extension kool_sso
ENABLE_FILESHARE	Boolean to enable the old fileshare module (deprecated)
$LEUTE_EMAIL_FIELDS	Array containing the column names of ko_leute containing an email address. Default is set in ko.inc. By settings this the checkboxes to define the preferred address will show in the edit form for addresses.
$LEUTE_MOBILE_FIELDS	Array Same as $LEUTE_EMAIL_FIELDS but for mobile numbers.
LEUTE_ADMIN_GROUPS_NEW_ONLY	Boolean to only force groups for persons when adding new records (not when editing)
$LEUTE_EXPORT_CHILDREN_COLUMNS	Columns to be exported for children lists where parents data should be added. See explanation under "Overwrite default" in "Documentations for Admins".
SESSION_TIMEOUT	Set the lifetime in seconds of the kOOL session for this installation. Overwrites settings in php.ini.
SESSION_TIMEOUT_WARNING	Boolean to have a warning displayed if the current kOOL session is about to time out in less than 3 minutes.
SESSION_TIMEOUT_AUTO_LOGOUT	Boolean to redirect the user to the front page after the kOOL session has timed out. This way the user sees that she is no longer logged in. (Use with caution)
EXPORT2EZMLM	Boolean. If set to TRUE the members of a group can automatically be exported to an ezmlm mailinglist (see ezmlm.org).
DP_DISABLE_OLD	Boolean. Set to TRUE to disable the old way to store rota members and leaders (by assigning the directly in the person's record). Assignment to rota teams only possible through groups. If set to FALSE (default) then both ways work.
FORCE_FAM_FIRSTNAME	Boolean. FALSE by default which exports families as "Fam. Lastname" unless specified differently for this particular family. If set to TRUE an exported family will always have a value for firstname, like "Fam Firstname+Firstname Lastname".
$PDFLATEX_PATH	Path to the LaTeX executable pdflatex used to compile LaTeX files. Only set this if pdflatex can't be found by Apache (e.g. if LaTeX is installed locally).
$INCLUDE_PATH_SMARTY	Set the path to the smarty library. This path will be added to PHP's include_path. Only needed if you can't change php.ini on your server.
EMAIL_SET_RETURN_PATH	Set this to TRUE to use the email headers "Return-Path" for outgoing mails from kOOL. Some shared hosters don't allow to set the Return-Path, in this case just set this to FALSE.
$SMALLGROUP_ROLES	Array containing the different possible roles in a smallgroup. 'L' and 'M' are set by default for leader and member. Only use single captial letters and define their names to be shown as LL values "kg_roles_X".
$SMALLGROUPS_ROLES_FOR_NUM	Array of smallgroup roles (see $SMALLGROUP_ROLES) to be used to calculate number of members for each smallgroup. Defaults to 'M' to only count members but not leaders or other roles.
$ICAL_URL	Specify a URL to be used as base URL for iCal links for events. If not set $BASE_URL will be used.
$RESICAL_URL	Specify a URL to be used as base URL for iCal links for reservations. If not set $BASE_URL will be used.
$LDAP_SCHEMA	Define the schemas to be used for addresses exported to LDAP. Find default configuration in inc/ko.inc

At the end of ko-config.php the file config/leute_formular.inc is included which defines the layout of the form for addresses. This file can be edited in the tools module.

Support for different languages

Most parts of kOOL are ready to be used in different languages. In /inc/ko.inc the file /inc/lang.inc gets included where most of the logic behind this is stored:

As a first step the available languages are evaluated from $WEB_LANGS and $LIB_LANGS
Then set_lang is evaluated from a GET request to reset the language
If no language is set after this and the Option $GET_LANG_FROM_BROWSER is set, the language is set according to the settings of the user's browser
If still no language is set the default language ($LANG[0]) is chosen
After including LL files from plugins the actual $LOCAL_LANG array is built according to the specified language

The localized strings for the different languages are stored in single files /locallang/locallang.XY.php and can be edited in the tools module.

It is possible to add a file locallang.XY_ZZ.php where ZZ is the region code of the country XY (e.g. en_US, or de_CH). This region file will be included after the main file for this language, so you can use this file to override language settings for this region which are different then they are set in the default language file.

To get a localized string in PHP the function getLL() may be used.