* @license GNU/GPL - See Dokeos license directory for details */ /** * lp_item defines items belonging to a learnpath. Each item has a name, a score, a use time and additional * information that enables tracking a user's progress in a learning path * @package dokeos.learnpath */ class learnpathItem{ var $attempt_id; //also called "objectives" SCORM-wise var $children = array(); //contains the ids of children items var $condition; //if this item has a special condition embedded var $current_score; var $current_start_time; var $current_stop_time; var $current_data = ''; var $db_id; var $db_item_view_id = ''; var $description = ''; var $file; //at the moment, interactions are just an array of arrays with a structure of 8 text fields //id(0), type(1), time(2), weighting(3),correct_responses(4),student_response(5),result(6),latency(7) var $interactions = array(); var $interactions_count = 0; var $launch_data = ''; var $lesson_location = ''; var $level = 0; //var $location; //only set this for SCORM? var $lp_id; var $max_score; var $min_score; var $name; var $next; var $parent; var $path; var $possible_status = array('not attempted','incomplete','completed','passed','failed','browsed'); var $prereq_string = ''; var $prereq_alert = ''; var $prereqs = array(); var $previous; var $prevent_reinit = 1; var $ref; var $save_on_close = true; var $status; var $title; var $type; // this attribute can contain chapter|link|student_publication|module|quiz|document|forum|thread var $view_id; var $debug = 0; //logging param /** * Class constructor. Prepares the learnpath_item for later launch * * Don't forget to use set_lp_view() if applicable after creating the item. * Setting an lp_view will finalise the item_view data collection * @param integer Learnpath item ID * @param integer User ID * @return boolean True on success, false on failure */ function learnpathItem($db_id, $user_id) { //get items table if($this->debug>0){error_log('New LP - In learnpathItem constructor: '.$db_id.','.$user_id,0);} $items_table = Database::get_course_table('lp_item'); $id = (int) $db_id; $sql = "SELECT * FROM $items_table WHERE id = $id"; //error_log('New LP - Creating item object from DB: '.$sql,0); $res = mysql_query($sql); if(mysql_num_rows($res)<1) { $this->error = "Could not find given learnpath item in learnpath_item table"; //error_log('New LP - '.$this->error,0); return false; } $row = mysql_fetch_array($res); $this->lp_id = $row['lp_id']; $this->max_score = $row['max']; $this->min_score = $row['min']; $this->name = $row['title']; $this->type = $row['item_type']; $this->ref = $row['ref']; $this->title = $row['title']; $this->description = $row['description']; $this->path = $row['path']; $this->masteryscore = $row['mastery_score']; $this->parent = $row['parent_item_id']; $this->next = $row['next_item_id']; $this->previous = $row['previous_item_id']; $this->display_order = $row['display_order']; $this->prereq_string = $row['prerequisite']; if(isset($row['launch_data'])){ $this->launch_data = $row['launch_data']; } $this->save_on_close = true; $this->db_id = $id; //error_log('New LP - End of learnpathItem constructor for item '.$id,0); return true; } /** * Adds a child to the current item */ function add_child($item) { if($this->debug>0){error_log('New LP - In learnpathItem::add_child()',0);} if(!empty($item)) { //do not check in DB as we expect the call to come from the learnpath class which should //be aware of any fake $this->children[] = $item; } } /** * Adds an interaction to the current item * @param int Index (order ID) of the interaction inside this item * @param array Array of parameters: id(0), type(1), time(2), weighting(3),correct_responses(4),student_response(5),result(6),latency(7) * @result void */ function add_interaction($index,$params) { $this->interactions[$index] = $params; //take the current maximum index to generate the interactions_count if(($index+1)>$this->interactions_count){ $this->interactions_count = $index+1; } /* if(is_array($this->interactions[$index]) && count($this->interactions[$index])>0){ $this->interactions[$index] = $params; return false; }else{ if(count($params)==8){//we rely on the calling script to provide parameters in the right order $this->interactions[$index] = $params; return true; }else{ return false; } } */ } /** * Closes/stops the item viewing. Finalises runtime values. If required, save to DB. * @return boolean True on success, false otherwise */ function close() { if($this->debug>0){error_log('New LP - In learnpathItem::close()',0);} $this->current_stop_time = time(); if($this->get_type() != 'sco'){ $this->status = $this->possible_status[2]; } if($this->save_on_close) { $this->save(); } return true; } /** * Deletes all traces of this item in the database * @return boolean true. Doesn't check for errors yet. */ function delete() { if($this->debug>0){error_log('New LP - In learnpath_item::delete() for item '.$this->db_id,0);} $lp_item_view = Database::get_course_table('lp_item_view'); $lp_item = Database::get_course_table('lp_item'); $sql_del_view = "DELETE FROM $lp_item_view WHERE item_id = ".$this->db_id; //error_log('New LP - Deleting from lp_item_view: '.$sql_del_view,0); $res_del_view = api_sql_query($sql_del_view); $sql_del_item = "DELETE FROM $lp_item WHERE id = ".$this->db_id; //error_log('New LP - Deleting from lp_item: '.$sql_del_view,0); $res_del_item = api_sql_query($sql_del_item); return true; } /** * Drops a child from the children array * @param string index of child item to drop * @return void */ function drop_child($item) { if($this->debug>0){error_log('New LP - In learnpathItem::drop_child()',0);} if(!empty($item)) { foreach($this->children as $index => $child) { if($child == $item){ $this->children[$index] = null; } } } } /** * Gets the current attempt_id for this user on this item * @return integer The attempt_id for this item view by this user, or 1 if none defined */ function get_attempt_id() { if($this->debug>0){error_log('New LP - In learnpathItem::get_attempt_id()',0);} if(!empty($this->attempt_id)) { return $this->attempt_id; } return 1; } /** * Gets a list of the item's children * @return array Array of children items IDs */ function get_children() { if($this->debug>0){error_log('New LP - In learnpathItem::get_children()',0);} $list = array(); foreach($this->children as $child){ if(!empty($child)) { //error_log('New LP - Found '.$child,0); $list[] = $child; } } return $list; } /** * Gets the credit information (rather scorm-stuff) based on current status and reinit * autorization. Credit tells the sco(content) if Dokeos will record the data it is sent (credit) or not (no-credit) * @return string 'credit' or 'no-credit'. Defaults to 'credit' because if we don't know enough about this item, it's probably because it was never used before. */ function get_credit(){ if(!empty($this->debug) && $this->debug>1){error_log('In learnpathItem::get_credit()',0);} $credit = 'credit'; //now check the value of prevent_reinit (if it's 0, return credit as the default was) if($this->get_prevent_reinit() != 0){ //if prevent_reinit == 1 (or more) //if status is not attempted or incomplete, credit anyway. Otherwise: //check the status in the database rather than in the object, as checking in the object //would always return "no-credit" when we want to set it to completed $status = $this->get_status(true); if(!empty($this->debug) && $this->debug>2){error_log('In learnpathItem::get_credit() - get_prevent_reinit!=0 and status is '.$status,0);} if($status != $this->possible_status[0] AND $status != $this->possible_status[1]){ $credit = 'no-credit'; } } return $credit; } /** * Gets the current start time property * @return integer Current start time, or current time if none */ function get_current_start_time() { if($this->debug>0){error_log('New LP - In learnpathItem::get_current_start_time()',0);} if(empty($this->current_start_time)) { return time(); }else{ return $this->current_start_time; } } /** * Gets the item's description * @return string Description */ function get_description(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_description()',0);} if(empty($this->description)){return '';} return $this->description; } /** * Gets the file path from the course's root directory, no matter what tool it is from. * @return string The file path, or an empty string if there is no file attached, or '-1' if the file must be replaced by an error page */ function get_file_path(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_file_path()',0);} $path = $this->get_path(); $type = $this->get_type(); if(empty($path)) { if($type == 'dokeos_chapter' OR $type=='chapter' OR $type == 'dir') { return ''; } else { return '-1'; } }elseif($path == strval(intval($path))){ //the path is numeric, so it is a reference to a Dokeos object switch($type) { case 'dokeos_chapter': case 'dir': case 'chapter': return ''; case TOOL_DOCUMENT: $table_doc = Database::get_course_table(TABLE_DOCUMENT); $sql = 'SELECT path FROM '.$table_doc.' WHERE id = '.$path; $res = api_sql_query($sql,__FILE__,__LINE__); $row = Database::fetch_array($res); $real_path = 'document'.$row['path']; return $real_path; case TOOL_STUDENTPUBLICATION: case TOOL_QUIZ: case TOOL_FORUM: case TOOL_THREAD: case TOOL_LINK: default: return '-1'; } }else{ return $path; } } /** * Gets the DB ID * @return integer Database ID for the current item */ function get_id(){ if($this->debug>1){error_log('New LP - In learnpathItem::get_id()',0);} if(!empty($this->db_id)) { return $this->db_id; } //TODO check this return value is valid for children classes (SCORM?) return 0; } /** * Gets the current count of interactions recorded in the database * @return int The current number of interactions recorder */ function get_interactions_count() { if($this->debug>1){error_log('New LP - In learnpathItem::get_interactions_count()',0);} $res = 0; if(!empty($this->interactions_count)){ $res = $this->interactions_count; } return $res; } /** * Gets the launch_data field found in imsmanifests (this is SCORM- or AICC-related, really) * @return string Launch data as found in imsmanifest and stored in Dokeos (read only). Defaults to ''. */ function get_launch_data(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_launch_data()',0);} if(!empty($this->launch_data)){ return $this->launch_data; } return ''; } /** * Gets the lesson location * @return string lesson location as recorded by the SCORM and AICC elements. Defaults to '' */ function get_lesson_location(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_lesson_location()',0);} if(!empty($this->lesson_location)){return $this->lesson_location;}else{return '';} } /** * Gets the lesson_mode (scorm feature, but might be used by aicc as well as dokeos paths) * * The "browse" mode is not supported yet (because there is no such way of seeing a sco in Dokeos) * @return string 'browse','normal' or 'review'. Defaults to 'normal' */ function get_lesson_mode(){ $mode = 'normal'; if($this->get_prevent_reinit() != 0){ //if prevent_reinit == 0 $my_status = $this->get_status(); if($my_status != $this->possible_status[0] AND $my_status != $this->possible_status[1]){ $mode = 'review'; } } } /** * Gets the depth level * @return int Level. Defaults to 0 */ function get_level(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_level()',0);} if(empty($this->level)){return 0;} return $this->level; } /** * Gets the maximum (score) * @return int Maximum score. Defaults to 100 */ function get_max(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_max()',0);} if(!empty($this->max_score)){return $this->max_score;}else{return 100;} } /** * Gets the minimum (score) * @return int Minimum score. Defaults to 0 */ function get_min(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_min()',0);} if(!empty($this->min_score)){return $this->min_score;}else{return 0;} } /** * Gets the parent ID * @return int Parent ID. Defaults to null */ function get_parent(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_parent()',0);} if(!empty($this->parent)) { return $this->parent; } //TODO check this return value is valid for children classes (SCORM?) return null; } /** * Gets the path attribute. * @return string Path. Defaults to '' */ function get_path(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_path()',0);} if(empty($this->path)){return '';} return $this->path; } /** * Gets the prerequisites string * @return string Empty string or prerequisites string if defined. Defaults to */ function get_prereq_string() { if($this->debug>0){error_log('New LP - In learnpathItem::get_prereq_string()',0);} if(!empty($this->prereq_string)) { return $this->prereq_string; }else{ return ''; } } /** * Gets the prevent_reinit attribute value (and sets it if not set already) * @return int 1 or 0 (defaults to 1) */ function get_prevent_reinit(){ if($this->debug>2){error_log('New LP - In learnpathItem::get_prevent_reinit()',0);} if(!isset($this->prevent_reinit)){ if(!empty($this->lp_id)){ $db = Database::get_course_table('lp'); $sql = "SELECT * FROM $db WHERE id = ".$this->lp_id; $res = mysql_query($sql); if(mysql_num_rows($res)<1) { $this->error = "Could not find parent learnpath in learnpath table"; if($this->debug>2){error_log('New LP - End of learnpathItem::get_prevent_reinit() - Returning false',0);} return false; }else{ $row = Database::fetch_array($res); $this->prevent_reinit = $row['prevent_reinit']; } }else{ $this->prevent_reinit = 1;//prevent reinit is always 1 by default - see learnpath.class.php } } if($this->debug>2){error_log('New LP - End of learnpathItem::get_prevent_reinit() - Returned '.$this->prevent_reinit,0);} return $this->prevent_reinit; } /** * Gets the score * @return float The current score or 0 if no score set yet */ function get_score(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_score()',0);} $res = 0; if($this->type == 'quiz'){ //get score directly from db and update current $item_view_table = Database::get_course_table('lp_item_view'); $check = "SELECT * FROM $item_view_table " . "WHERE lp_item_id = ".$this->db_id. " " . "AND lp_view_id = ".$this->view_id. " ". "AND view_count = ".$this->get_attempt_id(); $resq = api_sql_query($check,__FILE__,__LINE__); if(Database::num_rows($resq)>0){ $row = Database::fetch_array($resq); if(!empty($row['score'])){ //update current object score $this->current_score = $row['score']; $res = $this->current_score; } } }else{ if(!empty($this->current_score)) { $res = $this->current_score; } } //TODO check this return value is valid for children classes (SCORM?) if($this->debug>1){error_log('New LP - Out of learnpathItem::get_score() - returning '.$res,0);} return $res; } /** * Gets the item status * @param boolean Do or don't check into the database for the latest value. Optional. Default is true * @param boolean Do or don't update the local attribute value with what's been found in DB * @return string Current status or 'Nnot attempted' if no status set yet */ function get_status($check_db=true,$update_local=false) { if($this->debug>0){error_log('New LP - In learnpathItem::get_status()',0);} if($check_db) { if($this->debug>2){error_log('New LP - In learnpathItem::get_status(): checking db',0);} $table = Database::get_course_table('lp_item_view'); $sql = "SELECT * FROM $table WHERE id = '".$this->db_item_view_id."' AND view_count = '".$this->get_attempt_id()."'"; if($this->debug>2){error_log('New LP - In learnpathItem::get_status() - Checking DB: '.$sql,0);} $res = api_sql_query($sql); if(Database::num_rows($res)==1){ $row = Database::fetch_array($res); if($update_local==true){ $this->set_status($row['status']); } return $row['status']; } } else { if($this->debug>2){error_log('New LP - In learnpathItem::get_status() - in get_status: using attrib',0);} if(!empty($this->status)) { return $this->status; } } return $this->possible_status[0]; } /** * Gets the suspend data */ function get_suspend_data() { if($this->debug>0){error_log('New LP - In learnpathItem::get_suspend_data()',0);} if(!empty($this->current_data)){return $this->current_data;}else{return '';} } /** * Gets the total time spent on this item view so far * @param string Origin of the request. If coming from PHP, send formatted as xxhxx'xx", otherwise use scorm format 00:00:00 * @param integer Given time is a default time to return formatted */ function get_scorm_time($origin='php',$given_time=null){ //if($this->debug>0){error_log('New LP - In learnpathItem::get_scorm_time()',0);} $h = get_lang('h'); if(!isset($given_time)){ if(!empty($this->current_start_time)){ if(!empty($this->current_stop_time)){ $time = $this->current_stop_time - $this->current_start_time; }else{ $time = time() - $this->current_start_time; } }else{ if($origin == 'js'){ return '00:00:00'; }else{ return '00'.$h.'00\'00"'; } } }else{ $time = $given_time; } $hours = $time/3600; $mins = ($time%3600)/60; $secs = ($time%60); if($origin == 'js'){ $scorm_time = sprintf("%4d:%02d:%02d",$hours,$mins,$secs); }else{ $scorm_time = sprintf("%4d$h%02d'%02d\"",$hours,$mins,$secs); } return $scorm_time; } /** * Returns the item's title * @return string Title */ function get_title(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_title()',0);} if(empty($this->title)){return '';} return $this->title; } /** * Returns the total time used to see that item * @return integer Total time */ function get_total_time(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_total_time()',0);} if($this->current_start_time == 0){ //shouldn't be necessary thanks to the open() method $this->current_start_time = time(); } $time = $this->current_stop_time - $this->current_start_time; if($time < 0){ return 0; }else{ if($this->debug>2){error_log('New LP - In learnpathItem::get_total_time() - Current stop time = '.$this->current_stop_time.', current start time = '.$this->current_start_time.' Returning '.$time,0);} return $time; } } /** * Gets the item type * @return string The item type (can be doc, dir, sco, asset) */ function get_type() { $res = 'asset'; if($this->debug>0){error_log('New LP - In learnpathItem::get_type()',0);} if(!empty($this->type)) { //error_log('In item::get_type() - returning '.$this->type,0); $res = $this->type; } if($this->debug>2){error_log('New LP - In learnpathItem::get_type() - Returning '.$res.' for item '.$this->get_id(),0);} return $res; } /** * Gets the view count for this item */ function get_view_count(){ if($this->debug>0){error_log('New LP - In learnpathItem::get_view_count()',0);} if(!empty($this->attempt_id)){ return $this->attempt_id; }else{ return 0; } } /** * Tells if an item is done ('completed','passed','succeeded') or not * @return bool True if the item is done ('completed','passed','succeeded'), false otherwise */ function is_done(){ if($this->status_is(array('completed','passed','succeeded'))){ if($this->debug>2){error_log('New LP - In learnpath::is_done() - Item '.$this->get_id().' is complete',0);} return true; }else{ if($this->debug>2){error_log('New LP - In learnpath::is_done() - Item '.$this->get_id().' is not complete',0);} return false; } } /** * Tells if a restart is allowed (take it from $this->prevent_reinit and $this->status) * @return integer -1 if retaking the sco another time for credit is not allowed, * 0 if it is not allowed but the item has to be finished * 1 if it is allowed. Defaults to 1 */ function is_restart_allowed() { if($this->debug>2){error_log('New LP - In learnpathItem::is_restart_allowed()',0);} $restart = 1; $mystatus = $this->get_status(true); if($this->get_prevent_reinit() > 0){ //if prevent_reinit == 1 (or more) //if status is not attempted or incomplete, authorize retaking (of the same) anyway. Otherwise: if($mystatus != $this->possible_status[0] AND $mystatus != $this->possible_status[1]){ $restart = -1; }else{ $restart = 0; } }else{ if($mystatus == $this->possible_status[0] OR $mystatus == $this->possible_status[1]){ $restart = -1; } } if($this->debug>2){error_log('New LP - End of learnpathItem::is_restart_allowed() - Returning '.$restart,0);} return $restart; } /** * Opens/launches the item. Initialises runtime values. * @return boolean True on success, false on failure. */ function open(){ if($this->debug>0){error_log('New LP - In learnpathItem::open()',0);} if($this->prevent_reinit == 0){ $this->current_score = 0; $this->current_start_time = time(); $this->status = $this->possible_status[1]; $this->attempt_id = $this->attempt_id + 1; //open a new attempt }else{ if($this->current_start_time == 0){ //small exception for start time, to avoid amazing values $this->current_start_time = time(); } //error_log('New LP - reinit blocked by setting',0); } } /** * Outputs the item contents * @return string HTML file (displayable in an