[ EN ]    [ DE ]   
kOOL Logo HomeAboutDownloadDocumentation
Rects
Documentation

  General kOOL concepts

Access rights

Each user can have a single module available or not. This can be checked with the function

ko_module_installed($module, $uid)

If the second parameter is not given the module will be checked for the currently logged in user.

 

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.

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
FORCE_SSL Set to TRUE to let kOOL redirect users who access the BASE_URL using http instead of https
$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)
SESSION_SAVE_PATH Set an absolute path to where PHP session data is to be stored. Leave this commented out if default location is to be used
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
$RECTYPES Array for each recipient type for addresses, each holding a mapping array.
$EVENT_COLOR Allows you to specify colors for events depending on data stored on each event (e.g. the location)
$EVENTS_SHOW_RES_FIELDS An array holding all fields from ko_reservation which the user is supposed to enter when creating new reservations by creating events. Defaults to startzeit, endzeit. Read comment in inc/ko.inc before changing this value!

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.

Rects
©Renzo Lauper, CH-5000 Aarau, All rights reserved