Procedural File: main_api.lib.php

int api_add_access_url( string $u, [string $d = ''], [int $a = 1])

Adds an access URL into the database

Tags:

Parameters

string	$u	URL
string	$d	Description
int	$a	Active (1= active, 0=disabled)

boolean api_add_setting( string $val, string $var, [string $sk = null], [string $type = 'textfield'], [string $c = null], [string $title = ''], [string $com = ''], [string $sc = null], [string $skt = null], [int $a = 1], [int $v = 0])

Sets a platform configuration setting to a given value

Tags:

Parameters

string	$val	The value we want to record
string	$var	The variable name we want to insert
string	$sk	The subkey for the variable we want to insert
string	$type	The type for the variable we want to insert
string	$c	The category for the variable we want to insert
string	$title	The title
string	$com	The comment
string	$sc	The scope
string	$skt	The subkey text
int	$a	The access_url for which this parameter is valid
int	$v	The changeability of this setting for non-master urls

void api_add_url_param( $url, $param)

Parameters

	$url
	$param

void api_block_anonymous_users( )

Function used to prevent anonymous users from accessing a script.

Tags:

true api_check_password( string $password)

Checks a password to see wether it is OK to use.

Tags:

Parameters

string

$password

void api_chmod_R( $path, $filemode)

Parameters

	$path
	$filemode

bool api_clear_anonymous( [bool $db_check = false])

Clear the user ID from the session if it was the anonymous user. Generally used on out-of-tools pages to remove a user ID that could otherwise be used in the wrong context.

This function is to be used in conjunction with the api_set_anonymous() function to simulate the user existence in case of an anonymous visit.

Tags:

Parameters

bool

$db_check

database check switch - passed to api_is_anonymous()

boolean api_delete_category_settings( string $c, [int $a = 1])

Delete all the settings from one category

Tags:

Parameters

string	$c	Category
int	$a	Access URL

boolean api_delete_setting( string $v, [string $s = NULL], [int $a = 1])

Delete setting

Tags:

Parameters

string	$v	Variable
string	$s	Subkey
int	$a	Access URL

void api_display_array( array $info_array)

Displays the contents of an array in a messagebox.

Parameters

array

$info_array

An array with the messages to show

void api_display_debug_info( string $debug_info)

Displays debug info

Tags:

Parameters

string

$debug_info

The message to display

void api_display_language_form( )

Displays a form (drop down menu) so the user can select his/her preferred language.

The form works with or without javascript

void api_display_tool_title( mixed $titleElement)

Displays the title of a tool.

Normal use: parameter is a string: api_display_tool_title("My Tool")

Optionally, there can be a subtitle below the normal title, and / or a supra title above the normal title.

e.g. supra title: group GROUP PROPERTIES

e.g. subtitle: AGENDA calender & events tool

Tags:

Parameters

mixed

$titleElement

- it could either be a string or an array containing 'supraTitle', 'mainTitle', 'subTitle'

void api_display_tool_view_option( )

Display options to switch between student view and course manager view

Changes in version 1.2 (Patrick Cool) Student view switch now behaves as a real switch. It maintains its current state until the state is changed explicitly

Changes in version 1.1 (Patrick Cool) student view now works correctly in subfolders of the document tool student view works correctly in the new links tool

Example code for using this in your tools: //if ( $is_courseAdmin && api_get_setting('student_view_enabled') == 'true' ) //{ // display_tool_view_option($isStudentView); //} //and in later sections, use api_is_allowed_to_edit()

Tags:

void api_disp_html_area( string $name, [string $content = ''], [int $height = ''], [int $width = '100%'], [string $optAttrib = ''])

Displays the FckEditor WYSIWYG editor for online editing of html

Parameters

string	$name	The name of the form-element
string	$content	The default content of the html-editor
int	$height	The height of the form element
int	$width	The width of the form element
string	$optAttrib	optional attributes for the form element

string api_generate_password( [ $length = 8], int $length,)

Returns a difficult to guess password.

Tags:

Parameters

int	$length,	the length of the password
	$length

array api_get_access_urls( [ $from = 0], [ $to = 1000000], [ $order = 'url'], [ $direction = 'ASC'])

Get all available access urls in an array (as in the database)

Tags:

Parameters

	$from
	$to
	$order
	$direction

int api_get_anonymous_id( )

Gets an anonymous user ID

For some tools that need tracking, like the learnpath tool, it is necessary to have a usable user-id to enable some kind of tracking, even if not perfect. An anonymous ID is taken from the users table by looking for a status of "6" (anonymous).

Tags:

void api_get_cidreq( )

Returns the cidreq parameter name + current course id

void api_get_course_id( )

Returns the current course id (integer)

void api_get_course_info( [ $course_code = null])

Returns the current course info array.

Note: this array is only defined if the user is inside a course. Array elements: ['name'] ['official_code'] ['sysCode'] ['path'] ['dbName'] ['dbNameGlu'] ['titular'] ['language'] ['extLink']['url' ] ['extLink']['name'] ['categoryCode'] ['categoryName'] Now if the course_code is given, the returned array gives info about that particular course, not specially the current one.

Tags:

Parameters

$course_code

string api_get_course_path( [string $course_code = null])

Returns the current course directory

This function relies on api_get_course_info()

Tags:

Parameters

string

$course_code

The course code - optional (takes it from session if not given)

mixed api_get_course_setting( string $setting_name)

Gets a course setting from the current course_setting table. Try always using integer values.

Tags:

Parameters

string

$setting_name

The name of the setting we want from the table

string api_get_interface_language( )

Gets the current interface language

Tags:

int api_get_item_visibility( array $_course, string $tool, int $id)

Gets item visibility from the item_property table

Tags:

Parameters

array	$_course	Course properties array (result of api_get_course_info())
string	$tool	Tool (learnpath, document, etc)
int	$id	The item ID in the given tool

array api_get_languages( )

Return a list of all the languages that are made available by the admin.

Tags:

string api_get_language_isocode( )

Get language isocode column from the language table, taking the current language as a query

Tags:

string api_get_last_failure( [void 0 = ])

get the last failure stored in $api_failureList;

Tags:

Parameters

void

0

an api_get_navigator( )

Tags:

void api_get_path( one $path_type)

Returns a full path to a certain Dokeos area, which you specify through a parameter.

See $_configuration['course_folder'] in the configuration.php to alter the WEB_COURSE_PATH and SYS_COURSE_PATH parameters.

Tags:

Parameters

one

$path_type

of the following constants: WEB_PATH, SYS_PATH, REL_PATH, WEB_COURSE_PATH, SYS_COURSE_PATH, REL_COURSE_PATH, REL_CODE_PATH, WEB_CODE_PATH, SYS_CODE_PATH, SYS_LANG_PATH, WEB_IMG_PATH, GARBAGE_PATH, PLUGIN_PATH, SYS_ARCHIVE_PATH, INCLUDE_PATH, LIBRARY_PATH, CONFIGURATION_PATH

string api_get_self( )

Returns an escaped version of $_SERVER['PHP_SELF'] to avoid XSS injection

Tags:

void api_get_setting( string $variable, [string $key = NULL])

Returns the value of a setting from the web-adjustable admin config settings.

WARNING true/false are stored as string, so when comparing you need to check e.g. if(api_get_setting("show_navigation_menu") == "true") //CORRECT instead of if(api_get_setting("show_navigation_menu") == true) //INCORRECT

Tags:

Parameters

string	$variable	The variable name
string	$key	The subkey (sub-variable) if any. Defaults to NULL

array api_get_settings( [string $cat = null], [string $ordering = 'list'], [int $access_url = 1])

Gets all the current settings for a specific access url

Tags:

Parameters

string	$cat	The category, if any, that we want to get
string	$ordering	Whether we want a simple list (display a catgeory) or a grouped list (group by variable as in settings.php default). Values: 'list' or 'group'
int	$access_url	Access URL's ID. Optional. Uses 1 by default, which is the unique URL

array api_get_settings_categories( [array $exceptions = array()], [int $access_url = 1])

Gets the distinct settings categories

Tags:

Parameters

array	$exceptions	Array of strings giving the categories we want to exclude
int	$access_url	Access URL. Optional. Defaults to 1

array api_get_status_langvars( )

get the status langvars list

Tags:

array api_get_themes( )

Returns a list of CSS themes currently available in the CSS folder

Tags:

integer api_get_user_id( )

This function returns the id of the user which is stored in the $_user array.

Tags:

$user_info api_get_user_info( [$user_id $user_id = ''])

find all the information about a user. If no paramater is passed you find all the information about the current user.

Tags:

Parameters

$user_id

$user_id

(integer): the id of the user

string api_get_version( )

Get Dokeos version from the configuration files

Tags:

void api_is_allowed( $tool $tool, $action $action, [ $task_id = 0])

this fun

Tags:

Parameters

$tool	$tool	the tool we are checking ifthe user has a certain permission
$action	$action	the action we are checking (add, edit, delete, move, visibility)
	$task_id

boolean api_is_allowed_to_create_course( )

Check if current user is allowed to create courses

Tags:

boolean, api_is_allowed_to_edit( [bool $tutor = false], [bool $coach = false])

Function that removes the need to directly use is_courseAdmin global in tool scripts. It returns true or false depending on the user's rights in this particular course.

Optionally checking for tutor and coach roles here allows us to use the student_view feature altogether with these roles as well.

Tags:

Parameters

bool	$tutor	Whether to check if the user has the tutor role
bool	$coach	Whether to check if the user has the coach role

bool api_is_anonymous( [int $user_id = null], [bool $db_check = false])

Tells whether this user is an anonymous user

Tags:

Parameters

int	$user_id	User ID (optional, will take session ID if not provided)
bool	$db_check	Whether to check in the database (true) or simply in the session (false) to see if the current user is the anonymous user

boolean api_is_coach( )

Check if the current user is a course or session coach

Tags:

boolean api_is_course_admin( )

Check if the current user is a course administrator

Tags:

bool api_is_course_coach( )

Check if the current user is a course coach

Tags:

bool api_is_course_tutor( )

Check if the current user is a course tutor

Tags:

boolean api_is_platform_admin( [ $allow_sessions_admins = false])

Check if current user is a platform administrator

Tags:

Parameters

$allow_sessions_admins

boolean api_is_plugin_installed( $plugin_list, $plugin_name)

Checks to see wether a certain plugin is installed.

Tags:

Parameters

	$plugin_list
	$plugin_name

True api_is_self_registration_allowed( )

Tags:

boolean api_item_property_update( $_course $_course, $tool $tool, $item_id $item_id, $lastedit_type $lastedit_type, $user_id $user_id, [$to_group_id $to_group_id = 0], [$to_user_id $to_user_id = NULL], [string $start_visible = 0], [unknown_type $end_visible = 0])

update the item_properties table (if entry not exists, insert) of the course

Tags:

Parameters

string	$start_visible	0000-00-00 00:00:00 format
unknown_type	$end_visible	0000-00-00 00:00:00 format
$_course	$_course	: array with course properties
$tool	$tool	: tool id, linked to 'rubrique' of the course tool_list (Warning: language sensitive !!)
$item_id	$item_id	: id of the item itself, linked to key of every tool ('id', ...), "*" = all items of the tool
$lastedit_type	$lastedit_type	: add or update action (1) message to be translated (in trad4all) : e.g. DocumentAdded, DocumentUpdated; (2) "delete"; (3) "visible"; (4) "invisible";
$user_id	$user_id	: id of the editing/adding user
$to_group_id	$to_group_id	: id of the intended group ( 0 = for everybody), only relevant for $type (1)
$to_user_id	$to_user_id	: id of the intended user (always has priority over $to_group_id !), only relevant for $type (1)

int api_max_sort_value( $user_course_category, $user_id, int $user_course_category:)

Find the largest sort value in a given user_course_category

This function is used when we are moving a course to a different category and also when a user subscribes to a courses (the new courses is added to the end of the main category

Tags:

Parameters

int	$user_course_category:	the id of the user_course_category
	$user_course_category
	$user_id

void api_not_allowed( [bool $print_headers = false])

Displays message "You are not allowed here..." and exits the entire script.

Tags:

Parameters

bool

$print_headers

Whether or not to print headers (default = false -> does not print them)

void api_number_of_plugins( $location)

Determines the number of plugins installed for a given location

Parameters

$location

string api_parse_tex( $textext, string $text)

Apply parsing to content to parse tex commandos that are seperated by [tex] [/tex] to make it readable for techexplorer plugin.

Tags:

Parameters

string	$text	The text to parse
	$textext

void api_plugin( $location)

including the necessary plugins

Tags:

Parameters

$location

void api_protect_admin_script( [ $allow_sessions_admins = false])

Function used to protect an admin script.

The function blocks access when the user has no platform admin rights. This is only the first proposal, test and improve!

Tags:

Parameters

$allow_sessions_admins

void api_protect_course_script( [boolean $print_headers = false])

Function used to protect a course script.

The function blocks access when

• there is no $_SESSION["_course"] defined; or
• $is_allowed_in_course is set to false (this depends on the course

visibility and user status).

This is only the first proposal, test and improve!

Tags:

Parameters

boolean

$print_headers

Option to print headers when displaying error message. Default: false

void api_return_html_area( $name, [ $content = ''], [ $height = ''], [ $width = '100%'], [ $optAttrib = ''])

Parameters

	$name
	$content
	$height
	$width
	$optAttrib

void api_send_mail( string $to, string $subject, string $message, [string $additional_headers = null], [string $additional_parameters = null])

Send an email.

Wrapper function for the standard php mail() function. Change this function to your needs. The parameters must follow the same rules as the standard php mail() function. Please look at the documentation on http: //www. php. net/manual/en/function. mail.php

Parameters

string	$to
string	$subject
string	$message
string	$additional_headers
string	$additional_parameters

void api_session_clear( )

Clear the session

Tags:

void api_session_destroy( )

Destroy the session

Tags:

void api_session_register( string $variable)

save a variable into the session

BUG: function works only with global variables

Tags:

Parameters

string

$variable

variable - the variable name to save into the session

void api_session_start( [string $already_installed = true])

Start the Dokeos session.

The default lifetime for session is set here. It is not possible to have it as a database setting as it is used before the database connection has been made. It is taken from the configuration file, and if it doesn't exist there, it is set to 360000 seconds

Tags:

Parameters

string

$already_installed

variable - the variable name to save into the session

void api_session_unregister( string $variable)

Remove a variable from the session.

Tags:

Parameters

string

$variable

variable - the variable name to remove from the session

bool api_set_anonymous( )

Sets the current user as anonymous if it hasn't been identified yet. This

function should be used inside a tool only. The function api_clear_anonymous() acts in the opposite direction by clearing the anonymous user's data every time we get on a course homepage or on a neutral page (index, admin, my space)

Tags:

bolean api_set_failure( string $failureType)

Fills a global array called $api_failureList

This array collects all the failure occuring during the script runs The main purpose is allowing to manage the display messages externaly from the functions or objects. This strengthens encupsalation principle

Tags:

Parameters

string

$failureType

- the type of failure

void api_set_setting( string $var, string $value, [string $subvar = null], [string $cat = null], [int $access_url = 1])

Sets a platform configuration setting to a given value

Parameters

string	$var	The variable we want to update
string	$value	The value we want to record
string	$subvar	The sub-variable if any (in most cases, this will remain null)
string	$cat	The category if any (in most cases, this will remain null)
int	$access_url	The access_url for which this parameter is valid

void api_set_settings_category( string $category, [string $value = null], [int $access_url = 1])

Sets a whole category of settings to one specific value

Parameters

string	$category	Category
string	$value	Value
int	$access_url	Access URL. Optional. Defaults to 1

resource api_sql_query( string $query, [string $file = ''], [string $line = 0])

Executes an SQL query You have to use addslashes() on each value that you want to record into the database

Tags:

Parameters

string	$query	- SQL query
string	$file	- optional, the file path and name of the error (__FILE__)
string	$line	- optional, the line of the error (__LINE__)

true api_status_exists( mixed $status_asked)

Check if status given in parameter exists in the platform

Tags:

Parameters

mixed

$status_asked

the status (can be either int either string)

true api_status_key( mixed $status)

Check if status given in parameter exists in the platform

Tags:

Parameters

mixed

$status

the status (can be either int either string)

array api_store_result( resource $result)

Store the result of a query into an array

Tags:

Parameters

resource

$result

- the return value of the query

string api_time_to_hms( integer $seconds)

Transform a number of seconds in hh:mm:ss format

Tags:

Parameters

integer

$seconds

the number of seconds

void api_trunc_str( string $text, [integer $length = 30], [string $endStr = '...'], [boolean $middle = false])

truncates a string

Tags:

Parameters

string	$text	text - text to truncate
integer	$length	length - length of the truncated text
string	$endStr	endStr - suffix
boolean	$middle	middle - if true, truncates on string middle

unix convert_mysql_date( $last_post_datetime $last_post_datetime)

convert sql date to unix timestamp

Tags:

Parameters

$last_post_datetime

$last_post_datetime

standard output date in a sql query

void copyr( the $source, the $dest, [an $exclude = array()], [copied_files $copied_files = array()])

function adapted from a php.net comment

copy recursively a folder

Parameters

the	$source	source folder
the	$dest	dest folder
an	$exclude	array of excluded file_name (without extension)
copied_files	$copied_files	the returned array of copied files

void domesticate( string $input)

handling simple and double apostrofe in order that strings be stored properly in database

Tags:

Parameters

string

$input

variable - the variable to be revised

language get_lang( $variable, [ $notrans = 'DLTT'])

Whenever the server type in the Dokeos Config settings is set to test/development server you will get an indication that a language variable is not translated and a link to a suggestions form of DLTT.

Tags:

Parameters

	$variable
	$notrans

void get_setting( $variable, [ $key = NULL])

DEPRECATED, use api_get_setting instead

Parameters

	$variable
	$key

void is_allowed_to_edit( )

void shorten( $input, [ $length = 15])

Parameters

	$input
	$length

boolean string_2_boolean( string $string)

This function converts the string "true" or "false" to a boolean true or false.

This function is in the first place written for the Dokeos Config Settings (also named AWACS)

Tags:

Parameters

string

$string

"true" or "false"