scoredisplay.class.php 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592
  1. <?php
  2. /* For licensing terms, see /license.txt */
  3. /**
  4. * Class ScoreDisplay
  5. * Display scores according to the settings made by the platform admin.
  6. * This class works as a singleton: call instance() to retrieve an object.
  7. * @author Bert Steppé
  8. * @package chamilo.gradebook
  9. */
  10. class ScoreDisplay
  11. {
  12. private $coloring_enabled;
  13. private $color_split_value;
  14. private $custom_enabled;
  15. private $upperlimit_included;
  16. private $custom_display;
  17. private $custom_display_conv;
  18. /**
  19. * Protected constructor - call instance() to instantiate
  20. */
  21. public function __construct($category_id = 0)
  22. {
  23. if (!empty($category_id)) {
  24. $this->category_id = $category_id;
  25. }
  26. // Loading portal settings + using standard functions.
  27. $value = api_get_setting('gradebook_score_display_coloring');
  28. $value = $value['my_display_coloring'];
  29. // Setting coloring.
  30. $this->coloring_enabled = $value == 'true' ? true : false;
  31. if ($this->coloring_enabled) {
  32. $value = api_get_setting('gradebook_score_display_colorsplit');
  33. if (isset($value)) {
  34. $this->color_split_value = $value;
  35. }
  36. }
  37. // Setting custom enabled
  38. $value = api_get_setting('gradebook_score_display_custom');
  39. $value = $value['my_display_custom'];
  40. $this->custom_enabled = $value == 'true' ? true : false;
  41. if ($this->custom_enabled) {
  42. $params = ['category = ?' => ['Gradebook']];
  43. $displays = api_get_settings_params($params);
  44. $portal_displays = [];
  45. if (!empty($displays)) {
  46. foreach ($displays as $display) {
  47. $data = explode('::', $display['selected_value']);
  48. if (empty($data[1])) {
  49. $data[1] = "";
  50. }
  51. $portal_displays[$data[0]] = [
  52. 'score' => $data[0],
  53. 'display' => $data[1]
  54. ];
  55. }
  56. sort($portal_displays);
  57. }
  58. $this->custom_display = $portal_displays;
  59. if (count($this->custom_display) > 0) {
  60. $value = api_get_setting('gradebook_score_display_upperlimit');
  61. $value = $value['my_display_upperlimit'];
  62. $this->upperlimit_included = $value == 'true' ? true : false;
  63. $this->custom_display_conv = $this->convert_displays($this->custom_display);
  64. }
  65. }
  66. //If teachers can override the portal parameters
  67. if (api_get_setting('teachers_can_change_score_settings') == 'true') {
  68. //Load course settings
  69. if ($this->custom_enabled) {
  70. $this->custom_display = $this->get_custom_displays();
  71. if (count($this->custom_display) > 0) {
  72. $this->custom_display_conv = $this->convert_displays($this->custom_display);
  73. }
  74. }
  75. if ($this->coloring_enabled) {
  76. $this->color_split_value = $this->get_score_color_percent();
  77. }
  78. }
  79. }
  80. /**
  81. * Get the instance of this class
  82. * @param int $category_id
  83. * @return ScoreDisplay
  84. */
  85. public static function instance($category_id = 0)
  86. {
  87. static $instance;
  88. if (!isset($instance)) {
  89. $instance = new ScoreDisplay($category_id);
  90. }
  91. return $instance;
  92. }
  93. /**
  94. * Compare the custom display of 2 scores, can be useful in sorting
  95. */
  96. public static function compare_scores_by_custom_display($score1, $score2)
  97. {
  98. if (!isset($score1)) {
  99. return (isset($score2) ? 1 : 0);
  100. } elseif (!isset($score2)) {
  101. return -1;
  102. } else {
  103. $scoreDisplay = self::instance();
  104. $custom1 = $scoreDisplay->display_custom($score1);
  105. $custom2 = $scoreDisplay->display_custom($score2);
  106. if ($custom1 == $custom2) {
  107. return 0;
  108. } else {
  109. return (($score1[0] / $score1[1]) < ($score2[0] / $score2[1]) ? -1 : 1);
  110. }
  111. }
  112. }
  113. /**
  114. * Is coloring enabled ?
  115. */
  116. public function is_coloring_enabled()
  117. {
  118. return $this->coloring_enabled;
  119. }
  120. /**
  121. * Is custom score display enabled ?
  122. */
  123. public function is_custom()
  124. {
  125. return $this->custom_enabled;
  126. }
  127. /**
  128. * Is upperlimit included ?
  129. */
  130. public function is_upperlimit_included()
  131. {
  132. return $this->upperlimit_included;
  133. }
  134. /**
  135. * If custom score display is enabled, this will return the current settings.
  136. * See also update_custom_score_display_settings
  137. * @return array current settings (or null if feature not enabled)
  138. */
  139. public function get_custom_score_display_settings()
  140. {
  141. return $this->custom_display;
  142. }
  143. /**
  144. * If coloring is enabled, scores below this value will be displayed in red.
  145. * @return int color split value, in percent (or null if feature not enabled)
  146. */
  147. public function get_color_split_value()
  148. {
  149. return $this->color_split_value;
  150. }
  151. /**
  152. * Get current gradebook category id
  153. * @return int Category id
  154. */
  155. private function get_current_gradebook_category_id()
  156. {
  157. $table = Database::get_main_table(TABLE_MAIN_GRADEBOOK_CATEGORY);
  158. $curr_course_code = api_get_course_id();
  159. $curr_session_id = api_get_session_id();
  160. if (empty($curr_session_id)) {
  161. $session_condition = ' AND session_id is null ';
  162. } else {
  163. $session_condition = ' AND session_id = '.$curr_session_id;
  164. }
  165. $sql = 'SELECT id FROM '.$table.'
  166. WHERE course_code = "'.$curr_course_code.'" '.$session_condition;
  167. $rs = Database::query($sql);
  168. $category_id = 0;
  169. if (Database::num_rows($rs) > 0) {
  170. $row = Database::fetch_row($rs);
  171. $category_id = $row[0];
  172. }
  173. return $category_id;
  174. }
  175. /**
  176. * Update custom score display settings
  177. * @param array $displays 2-dimensional array - every sub array must have keys (score, display)
  178. * @param int score color percent (optional)
  179. * @param int gradebook category id (optional)
  180. */
  181. public function update_custom_score_display_settings(
  182. $displays,
  183. $scorecolpercent = 0,
  184. $category_id = null
  185. ) {
  186. $this->custom_display = $displays;
  187. $this->custom_display_conv = $this->convert_displays($this->custom_display);
  188. if (isset($category_id)) {
  189. $category_id = intval($category_id);
  190. } else {
  191. $category_id = $this->get_current_gradebook_category_id();
  192. }
  193. // remove previous settings
  194. $table = Database::get_main_table(TABLE_MAIN_GRADEBOOK_SCORE_DISPLAY);
  195. $sql = 'DELETE FROM '.$table.' WHERE category_id = '.$category_id;
  196. Database::query($sql);
  197. // add new settings
  198. $count = 0;
  199. foreach ($displays as $display) {
  200. $params = [
  201. 'score' => $display['score'],
  202. 'display' => $display['display'],
  203. 'category_id' => $category_id,
  204. 'score_color_percent' => $scorecolpercent,
  205. ];
  206. Database::insert($table, $params);
  207. $count++;
  208. }
  209. }
  210. /**
  211. * @param int $category_id
  212. * @return false|null
  213. */
  214. public function insert_defaults($category_id)
  215. {
  216. if (empty($category_id)) {
  217. return false;
  218. }
  219. //Get this from DB settings
  220. $display = [
  221. 50 => get_lang('GradebookFailed'),
  222. 60 => get_lang('GradebookPoor'),
  223. 70 => get_lang('GradebookFair'),
  224. 80 => get_lang('GradebookGood'),
  225. 90 => get_lang('GradebookOutstanding'),
  226. 100 => get_lang('GradebookExcellent')
  227. ];
  228. $table = Database::get_main_table(TABLE_MAIN_GRADEBOOK_SCORE_DISPLAY);
  229. foreach ($display as $value => $text) {
  230. $params = [
  231. 'score' => $value,
  232. 'display' => $text,
  233. 'category_id' => $category_id,
  234. 'score_color_percent' => 0,
  235. ];
  236. Database::insert($table, $params);
  237. }
  238. }
  239. /**
  240. * @return integer
  241. */
  242. public function get_number_decimals()
  243. {
  244. $number_decimals = api_get_setting('gradebook_number_decimals');
  245. if (!isset($number_decimals)) {
  246. $number_decimals = 0;
  247. }
  248. return $number_decimals;
  249. }
  250. /**
  251. * Formats a number depending of the number of decimals
  252. *
  253. * @param float $score
  254. * @param bool $ignoreDecimals
  255. * @param string $decimalSeparator
  256. * @param string $thousandSeparator
  257. *
  258. * @return float the score formatted
  259. */
  260. public function format_score($score, $ignoreDecimals = false, $decimalSeparator = '.', $thousandSeparator = ',')
  261. {
  262. $decimals = $this->get_number_decimals();
  263. if ($ignoreDecimals) {
  264. $decimals = 0;
  265. }
  266. return api_number_format($score, $decimals, $decimalSeparator, $thousandSeparator);
  267. }
  268. /**
  269. * Display a score according to the current settings
  270. * @param array $score data structure, as returned by the calc_score functions
  271. * @param int $type one of the following constants:
  272. * SCORE_DIV, SCORE_PERCENT, SCORE_DIV_PERCENT, SCORE_AVERAGE
  273. * (ignored for student's view if custom score display is enabled)
  274. * @param int $what one of the following constants:
  275. * SCORE_BOTH, SCORE_ONLY_DEFAULT, SCORE_ONLY_CUSTOM (default: SCORE_BOTH)
  276. * (only taken into account if custom score display is enabled and for course/platform admin)
  277. * @param bool $disableColor
  278. * @param bool $ignoreDecimals
  279. *
  280. * @return string
  281. */
  282. public function display_score(
  283. $score,
  284. $type = SCORE_DIV_PERCENT,
  285. $what = SCORE_BOTH,
  286. $disableColor = false,
  287. $ignoreDecimals = false
  288. ) {
  289. $my_score = $score == 0 ? 1 : $score;
  290. if ($type == SCORE_BAR) {
  291. $percentage = $my_score[0] / $my_score[1] * 100;
  292. return Display::bar_progress($percentage);
  293. }
  294. if ($type == SCORE_SIMPLE) {
  295. $simpleScore = $this->format_score($my_score[0], $ignoreDecimals);
  296. return $simpleScore;
  297. }
  298. if ($this->custom_enabled && isset($this->custom_display_conv)) {
  299. $display = $this->display_default($my_score, $type, $ignoreDecimals);
  300. } else {
  301. // if no custom display set, use default display
  302. $display = $this->display_default($my_score, $type, $ignoreDecimals);
  303. }
  304. if ($this->coloring_enabled && $disableColor == false) {
  305. $my_score_denom = isset($score[1]) && !empty($score[1]) && $score[1] > 0 ? $score[1] : 1;
  306. $scoreCleaned = isset($score[0]) ? $score[0] : 0;
  307. if (($scoreCleaned / $my_score_denom) < ($this->color_split_value / 100)) {
  308. $display = Display::tag(
  309. 'font',
  310. $display,
  311. ['color' => 'red']
  312. );
  313. }
  314. }
  315. return $display;
  316. }
  317. /**
  318. * @param $score
  319. * @param integer $type
  320. * @param bool $ignoreDecimals
  321. * @return string
  322. */
  323. private function display_default($score, $type, $ignoreDecimals = false)
  324. {
  325. switch ($type) {
  326. case SCORE_DIV: // X / Y
  327. return $this->display_as_div($score, $ignoreDecimals);
  328. case SCORE_PERCENT: // XX %
  329. return $this->display_as_percent($score);
  330. case SCORE_DIV_PERCENT: // X / Y (XX %)
  331. return $this->display_as_div($score).' ('.$this->display_as_percent($score).')';
  332. case SCORE_AVERAGE: // XX %
  333. return $this->display_as_percent($score);
  334. case SCORE_DECIMAL: // 0.50 (X/Y)
  335. return $this->display_as_decimal($score);
  336. case SCORE_DIV_PERCENT_WITH_CUSTOM: // X / Y (XX %) - Good!
  337. $custom = $this->display_custom($score);
  338. if (!empty($custom)) {
  339. $custom = ' - '.$custom;
  340. }
  341. return $this->display_as_div($score).' ('.$this->display_as_percent($score).')'.$custom;
  342. case SCORE_DIV_SIMPLE_WITH_CUSTOM: // X - Good!
  343. $custom = $this->display_custom($score);
  344. if (!empty($custom)) {
  345. $custom = ' - '.$custom;
  346. }
  347. return $this->display_simple_score($score).$custom;
  348. break;
  349. case SCORE_DIV_SIMPLE_WITH_CUSTOM_LETTERS:
  350. $custom = $this->display_custom($score);
  351. if (!empty($custom)) {
  352. $custom = ' - '.$custom;
  353. }
  354. $score = $this->display_simple_score($score);
  355. //needs sudo apt-get install php5-intl
  356. if (class_exists('NumberFormatter')) {
  357. $iso = api_get_language_isocode();
  358. $f = new NumberFormatter($iso, NumberFormatter::SPELLOUT);
  359. $letters = $f->format($score);
  360. $letters = api_strtoupper($letters);
  361. $letters = " ($letters) ";
  362. }
  363. return $score.$letters.$custom;
  364. break;
  365. case SCORE_CUSTOM: // Good!
  366. return $this->display_custom($score);
  367. }
  368. }
  369. /**
  370. * @param array $score
  371. * @return float|string
  372. */
  373. private function display_simple_score($score)
  374. {
  375. if (isset($score[0])) {
  376. return $this->format_score($score[0]);
  377. }
  378. return '';
  379. }
  380. /**
  381. * Returns "1" for array("100", "100");
  382. * @param array $score
  383. * @return float
  384. */
  385. private function display_as_decimal($score)
  386. {
  387. $score_denom = ($score[1] == 0) ? 1 : $score[1];
  388. return $this->format_score($score[0] / $score_denom);
  389. }
  390. /**
  391. * Returns "100 %" for array("100", "100");
  392. */
  393. private function display_as_percent($score)
  394. {
  395. $score_denom = ($score[1] == 0) ? 1 : $score[1];
  396. return $this->format_score($score[0] / $score_denom * 100).' %';
  397. }
  398. /**
  399. * Returns 10.00 / 10.00 for array("100", "100");
  400. * @param array $score
  401. * @param bool $ignoreDecimals
  402. *
  403. * @return string
  404. */
  405. private function display_as_div($score, $ignoreDecimals = false)
  406. {
  407. if ($score == 1) {
  408. return '0 / 0';
  409. } else {
  410. $score[0] = isset($score[0]) ? $this->format_score($score[0], $ignoreDecimals) : 0;
  411. $score[1] = isset($score[1]) ? $this->format_score($score[1], $ignoreDecimals) : 0;
  412. return $score[0].' / '.$score[1];
  413. }
  414. }
  415. /**
  416. * Depends on the teacher's configuration of thresholds. i.e. [0 50] "Bad", [50:100] "Good"
  417. * @param array $score
  418. * @return string
  419. */
  420. private function display_custom($score)
  421. {
  422. $my_score_denom = $score[1] == 0 ? 1 : $score[1];
  423. $scaledscore = $score[0] / $my_score_denom;
  424. if ($this->upperlimit_included) {
  425. foreach ($this->custom_display_conv as $displayitem) {
  426. if ($scaledscore <= $displayitem['score']) {
  427. return $displayitem['display'];
  428. }
  429. }
  430. } else {
  431. if (!empty($this->custom_display_conv)) {
  432. foreach ($this->custom_display_conv as $displayitem) {
  433. if ($scaledscore < $displayitem['score'] || $displayitem['score'] == 1) {
  434. return $displayitem['display'];
  435. }
  436. }
  437. }
  438. }
  439. }
  440. /**
  441. * Get score color percent by category
  442. * @param int Gradebook category id
  443. * @return int Score
  444. */
  445. private function get_score_color_percent($category_id = null)
  446. {
  447. $tbl_display = Database::get_main_table(TABLE_MAIN_GRADEBOOK_SCORE_DISPLAY);
  448. if (isset($category_id)) {
  449. $category_id = intval($category_id);
  450. } else {
  451. $category_id = $this->get_current_gradebook_category_id();
  452. }
  453. $sql = 'SELECT score_color_percent FROM '.$tbl_display.'
  454. WHERE category_id = '.$category_id.'
  455. LIMIT 1';
  456. $result = Database::query($sql);
  457. $score = 0;
  458. if (Database::num_rows($result) > 0) {
  459. $row = Database::fetch_row($result);
  460. $score = $row[0];
  461. }
  462. return $score;
  463. }
  464. /**
  465. * Get current custom score display settings
  466. * @param int Gradebook category id
  467. * @return array 2-dimensional array every element contains 3 subelements (id, score, display)
  468. */
  469. private function get_custom_displays($category_id = null)
  470. {
  471. $tbl_display = Database::get_main_table(TABLE_MAIN_GRADEBOOK_SCORE_DISPLAY);
  472. if (isset($category_id)) {
  473. $category_id = intval($category_id);
  474. } else {
  475. $category_id = $this->get_current_gradebook_category_id();
  476. }
  477. $sql = 'SELECT * FROM '.$tbl_display.'
  478. WHERE category_id = '.$category_id.'
  479. ORDER BY score';
  480. $result = Database::query($sql);
  481. return Database::store_result($result, 'ASSOC');
  482. }
  483. /**
  484. * Convert display settings to internally used values
  485. */
  486. private function convert_displays($custom_display)
  487. {
  488. if (isset($custom_display)) {
  489. // get highest score entry, and copy each element to a new array
  490. $converted = [];
  491. $highest = 0;
  492. foreach ($custom_display as $element) {
  493. if ($element['score'] > $highest) {
  494. $highest = $element['score'];
  495. }
  496. $converted[] = $element;
  497. }
  498. // sort the new array (ascending)
  499. usort($converted, ['ScoreDisplay', 'sort_display']);
  500. // adjust each score in such a way that
  501. // each score is scaled between 0 and 1
  502. // the highest score in this array will be equal to 1
  503. $converted2 = [];
  504. foreach ($converted as $element) {
  505. $newelement = [];
  506. if (isset($highest) && !empty($highest) && $highest > 0) {
  507. $newelement['score'] = $element['score'] / $highest;
  508. } else {
  509. $newelement['score'] = 0;
  510. }
  511. $newelement['display'] = $element['display'];
  512. $converted2[] = $newelement;
  513. }
  514. return $converted2;
  515. } else {
  516. return null;
  517. }
  518. }
  519. /**
  520. * @param array $item1
  521. * @param array $item2
  522. * @return int
  523. */
  524. private function sort_display($item1, $item2)
  525. {
  526. if ($item1['score'] === $item2['score']) {
  527. return 0;
  528. } else {
  529. return ($item1['score'] < $item2['score'] ? -1 : 1);
  530. }
  531. }
  532. }