Merge pull request #7 from moodleuulm/LMS-5474

Allow admin to define the internal term representation

classes/data_controller.php

@@ -18,8 +18,12 @@
  * Semester customfield data controller
  *
  * Semesters are encoded as YYYYS, where YYYY is the year when the semester begins and
- * S is 0 = summersemester and 1 = wintersemester. So 20191 stands for WiSe 2019/2020.
- * Exception: 0 stands for semesterindepentent.
+ * S is the identifier of the term.
+ *
+ * The identifier of the term is depending on the admin setting customfield_semester/internaltermrepresentation.
+ * By default, it is 0 = summer term and 1 = winter term. So YYYYS = 20191 stands for the winter term 2019/20.
+ *
+ * In addition to that, there are term-independent terms which are represented by YYYYS = 1.
  *
  * @package   customfield_semester
  * @copyright 2020 Justus Dieckmann WWU
@@ -66,9 +70,18 @@ class data_controller extends \core_customfield\data_controller {
      * @param \MoodleQuickForm $mform
      */
     public function instance_form_definition(\MoodleQuickForm $mform) {
+        global $CFG;
+
+        // Require local library.
+        require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+        // Get config from DB.
+        $config = get_config('customfield_semester');
+
+        // Compose the field values.
         $field = $this->get_field();
         $formattedoptions = array(
-                1 => get_string('semesterindependent', 'customfield_semester')
+                self::get_termindependent_representation() => get_string('semesterindependent', 'customfield_semester')
         );
         $showmonthsintofuture = $this->get_field()->get_configdata_property('showmonthsintofuture');
         $endtime = new DateTime("+$showmonthsintofuture months");
@@ -78,20 +91,29 @@ class data_controller extends \core_customfield\data_controller {
 
         $beginofsemesters = $this->get_field()->get_configdata_property('beginofsemesters');
         for ($year = $beginofsemesters; $year <= $endyear; $year++) {
-            $formattedoptions[$year * 10] = get_string('summersemester', 'customfield_semester', $year);
+            $formattedoptions[$year * 10 + self::get_summerterm_representation()] =
+                    get_string('summersemester', 'customfield_semester', $year);
 
-            if ($year == $endyear && $endsemester == 0) {
+            if ($year == $endyear && $endsemester == self::get_summerterm_representation()) {
                 break;
             }
 
-            $formattedoptions[$year * 10 + 1] = get_string('wintersemester', 'customfield_semester',
-                    $year . '/' . substr($year + 1, 2, 2));
+            $formattedoptions[$year * 10 + self::get_winterterm_representation()] =
+                    get_string('wintersemester', 'customfield_semester', $year . '/' . substr($year + 1, 2, 2));
+        }
+
+        // The values were composed in CUSTOMFIELD_SEMESTER_PRESENTATION_ASC order here.
+        // If the admin wants to present them in CUSTOMFIELD_SEMESTER_PRESENTATION_DESC order, we need to reverse the array now.
+        if ($config->termpresentationorder == CUSTOMFIELD_SEMESTER_PRESENTATION_DESC) {
+            $formattedoptions = array_reverse($formattedoptions, true);
         }
 
+        // Build the field widget.
         $elementname = $this->get_form_element_name();
         $mform->addElement('select', $elementname, $this->get_field()->get_formatted_name(), $formattedoptions);
         $mform->setDefault($elementname, $this->get_default_value());
 
+        // Add the required flag if necessary.
         if ($field->get_configdata_property('required')) {
             $mform->addRule($elementname, null, 'required', null, 'client');
         }
@@ -129,22 +151,24 @@ class data_controller extends \core_customfield\data_controller {
     /**
      * Returns the human readable Semester name for a semesterid.
      *
-     * @param int $value the semesterid (YYYYS as descibed at the top of the file).
+     * @param int $value the semesterid (YYYYS as described at the top of the file).
      * @return string|null The human readable semester name
      */
     public static function get_name_for_semester(int $value) {
-        if ($value === 1) {
+        if ($value === self::get_termindependent_representation()) {
             return get_string('semesterindependent', 'customfield_semester');
         } else if ($value == null) {
             return null;
         } else {
             $year = intdiv($value, 10);
             $semester = $value % 10;
-            if ($semester === 0) {
+            if ($semester === self::get_summerterm_representation()) {
                 return get_string('summersemester', 'customfield_semester', $year);
-            } else {
+            } else if ($semester === self::get_winterterm_representation()) {
                 return get_string('wintersemester', 'customfield_semester',
                         $year . '/' . substr($year + 1, 2, 2));
+            } else {
+                return null;
             }
         }
     }
@@ -157,14 +181,154 @@ class data_controller extends \core_customfield\data_controller {
     public static function get_semester_for_datetime(DateTime $datetime): int {
         $year = (int) $datetime->format('Y');
         $month = (int) $datetime->format('m');
-        if ($month < 4) {
+        $summertermstartmonth = self::get_summerterm_startmonth();
+        $wintertermstartmonth = self::get_winterterm_startmonth();
+        if ($month < $summertermstartmonth) {
             $year--;
-            $semester = 1;
-        } else if ($month < 10) {
-            $semester = 0;
+            $semester = self::get_winterterm_representation();
+        } else if ($month < $wintertermstartmonth) {
+            $semester = self::get_summerterm_representation();
         } else {
-            $semester = 1;
+            $semester = self::get_winterterm_representation();
         }
         return $year * 10 + $semester;
     }
+
+    /**
+     * Returns the configured start month of the summer term from the plugin settings.
+     *
+     * @return int
+     */
+    public static function get_summerterm_startmonth(): int {
+        global $CFG;
+
+        // Require local library.
+        require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+        // Get config from DB.
+        $config = get_config('customfield_semester');
+
+        // Double-check that the value is within the acceptable range. If not, return the default value.
+        if (is_numeric($config->summertermstartmonth) == false ||
+                $config->summertermstartmonth < 1 || $config->summertermstartmonth > 12 ||
+                $config->summertermstartmonth > $config->wintertermstartmonth) {
+            return CUSTOMFIELD_SEMESTER_SUMMERTERMSTART;
+        }
+
+        return $config->summertermstartmonth;
+    }
+
+    /**
+     * Returns the configured start month of the winter term from the plugin settings.
+     *
+     * @return int
+     */
+    public static function get_winterterm_startmonth(): int {
+        global $CFG;
+
+        // Require local library.
+        require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+        // Get config from DB.
+        $config = get_config('customfield_semester');
+
+        // Double-check that the value is within the acceptable range. If not, return the default value.
+        if (is_numeric($config->wintertermstartmonth) == false ||
+                $config->wintertermstartmonth < 1 || $config->wintertermstartmonth > 12 ||
+                $config->wintertermstartmonth < $config->summertermstartmonth) {
+            return CUSTOMFIELD_SEMESTER_WINTERTERMSTART;
+        }
+
+        return $config->wintertermstartmonth;
+    }
+
+    /**
+     * Returns the configured internal representation for the summer term.
+     *
+     * @return int
+     */
+    public static function get_summerterm_representation(): int {
+        global $CFG;
+
+        // Static variable to remember the return value for subsequent calls of this function.
+        static $returnvalue = null;
+
+        // If not already done in a previous call, calculate the return value.
+        if ($returnvalue === null) {
+            // Require local library.
+            require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+            // Get config from DB.
+            $config = get_config('customfield_semester');
+
+            // If the setting was changed to something different from the default.
+            if ($config->internaltermrepresentation == CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2) {
+                $returnvalue = CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2_ST;
+
+                // Otherwise, return the default representation.
+            } else {
+                $returnvalue = CUSTOMFIELD_SEMESTER_INTERNAL_ST0WT1_ST;
+            }
+        }
+
+        // Return value.
+        return $returnvalue;
+    }
+
+    /**
+     * Returns the configured internal representation for the winter term.
+     *
+     * @return int
+     */
+    public static function get_winterterm_representation(): int {
+        global $CFG;
+
+        // Static variable to remember the return value for subsequent calls of this function.
+        static $returnvalue = null;
+
+        // If not already done in a previous call, calculate the return value.
+        if ($returnvalue === null) {
+            // Require local library.
+            require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+            // Get config from DB.
+            $config = get_config('customfield_semester');
+
+            // If the setting was changed to something different from the default.
+            if ($config->internaltermrepresentation == CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2) {
+                $returnvalue = CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2_WT;
+
+                // Otherwise, return the default representation.
+            } else {
+                $returnvalue = CUSTOMFIELD_SEMESTER_INTERNAL_ST0WT1_WT;
+            }
+        }
+
+        // Return value.
+        return $returnvalue;
+    }
+
+    /**
+     * Returns the configured internal representation for the term-independent term.
+     *
+     * @return int
+     */
+    public static function get_termindependent_representation(): int {
+        global $CFG;
+
+        // Static variable to remember the return value for subsequent calls of this function.
+        static $returnvalue = null;
+
+        // If not already done in a previous call, calculate the return value.
+        if ($returnvalue === null) {
+            // Require local library.
+            require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+            // Return the default representation.
+            $returnvalue = CUSTOMFIELD_SEMESTER_INTERNAL_TERMINDEPENDENT;
+        }
+
+        // Return value.
+        return $returnvalue;
+    }
 }

classes/field_controller.php

@@ -92,13 +92,32 @@ class field_controller extends \core_customfield\field_controller {
      * @return array
      */
     public function course_grouping_format_values($values): array {
+        global $CFG;
+
+        // Require local library.
+        require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+        // Get config from DB.
+        $config = get_config('customfield_semester');
+
+        // Prepare return array.
         $ret = [];
+
+        // The values arrive in CUSTOMFIELD_SEMESTER_PRESENTATION_ASC order here.
+        // If the admin wants to present them in CUSTOMFIELD_SEMESTER_PRESENTATION_DESC order, we need to reverse the array now.
+        if ($config->termpresentationorder == CUSTOMFIELD_SEMESTER_PRESENTATION_DESC) {
+            $values = array_reverse($values, true);
+        }
+
+        // Iterate over given values.
         foreach ($values as $value) {
             $name = data_controller::get_name_for_semester($value);
             if ($name) {
                 $ret[$value] = $name;
             }
         }
+
+        // Return values.
         return $ret;
     }
 }

lang/de/customfield_semester.php

@@ -32,3 +32,17 @@ $string['specificsettings'] = 'Einstellungen für das Semesterfeld';
 $string['showmonthsintofuture'] = 'Ein Semester ist auswählbar, wenn es in weniger als X Monaten beginnt.';
 $string['defaultmonthsintofuture'] = 'Standard ist das Semester in X Monaten.';
 $string['beginofsemesters'] = 'Das Jahr, in dem die Liste der Semester anfängt.';
+$string['internaltermrepresentation'] = 'Interne Semester Repräsentierung';
+$string['internaltermrepresentation_desc'] = 'Mit dieser Einstellung definitieren Sie wie das Kursfeld die Semester intern (in der Moodle Datenbank) repräsentiert. Dies ist relevant falls Sie Moodle mit externen Kursplanungssystemen integrieren und das Kursfeld direkt mit Werten eines externen Systems befüllen wollen.';
+$string['internaltermrepresentationwarning'] = '<strong>Warnung:</strong> Eine Änderung dieser Einstellung bewirkt <em>nicht</em> dass existierende Feldwerte in existierenden Kursen aktualisiert werden. Bitte ändern Sie diese Einstellung ausschließlich wenn Sie dies wirklich benötigen und Sie sich bewusst sind dass Sie danach die Feldwerte existierender Kurse neu befüllen müssen.';
+$string['internaltermrepresentationst0wt1'] = 'Repräsentiere das Sommersemester als Semester 0 und das Wintersemester als Semester 1';
+$string['internaltermrepresentationst1wt2'] = 'Repräsentiere das Sommersemester als Semester 1 und das Wintersemester als Semester 2';
+$string['summertermstartmonth'] = 'Der Monat in dem das Sommersemester startet';
+$string['summertermstartmonth_desc'] = 'Mit dieser Einstellung definieren Sie in welchem Monat das Sommersemester startet.';
+$string['termpresentationasc'] = 'Ältere Semester zuerst, semesterunabhängiger Eintrag am Beginn der Liste';
+$string['termpresentationdesc'] = 'Neuere Semester zuerst, semesterunabhängiger Eintrag am Ende der Liste';
+$string['termpresentationorder'] = 'Darstellungsreihenfolge der Semester';
+$string['termpresentationorder_desc'] = 'Mit dieser Einstellung definieren Sie wie die Liste der Semester innerhalb der Kurseinstellungen und (falls das Feld als Kursfilter verwendet wird) innerhalb des Kursübersichtsblocks auf dem Dashboard dargestellt wird.';
+$string['wintertermstartmonth'] = 'Der Monat in dem das Wintersemester startet';
+$string['wintertermstartmonth_desc'] = 'Mit dieser Einstellung definieren Sie in welchem Monat das Wintersemester startet.';
+$string['startmonthnote'] = 'Bitte beachten: Gültige Einstellungen sind Werte zwischen 1 und 12. Diese Einstellung geht davon aus, dass das Sommersemester im Jahresverlauf vor dem Wintersemester kommt. Falls Sie die Semester andersrum konfigurieren, wird das Kursfeld Ihre Einstellung stillschweigend ignorieren und die Standardwerte nutzen.';

lang/en/customfield_semester.php

@@ -32,3 +32,17 @@ $string['specificsettings'] = 'Semester field settings';
 $string['showmonthsintofuture'] = 'A semester will be selectable, if it begins in less than X months.';
 $string['defaultmonthsintofuture'] = 'The default option is the semester in X months.';
 $string['beginofsemesters'] = 'The year, the list of semesters begins in.';
+$string['internaltermrepresentation'] = 'Internal term representation';
+$string['internaltermrepresentation_desc'] = 'With this setting, you control how the custom field represents the terms internally (in the Moodle database). This is relevant if you want to integrate Moodle with external lecture management systems and want to fill the custom field directly with values from an external system.';
+$string['internaltermrepresentationwarning'] = '<strong>Warning:</strong> Changing this setting will <em>not</em> update existing field values in existing courses. Please change this setting only if you really need to and if you are aware that you will have to fill the fields of existing courses again.';
+$string['internaltermrepresentationst0wt1'] = 'Represent the summer term as term 0 and the winter term as term 1';
+$string['internaltermrepresentationst1wt2'] = 'Represent the summer term as term 1 and the winter term as term 2';
+$string['summertermstartmonth'] = 'The month when summer term starts';
+$string['summertermstartmonth_desc'] = 'With this setting, you define in which month the summer term starts.';
+$string['termpresentationasc'] = 'Older terms first, term-independent entry at the beginning of the list';
+$string['termpresentationdesc'] = 'Newer terms first, term-independent entry at the end of the list';
+$string['termpresentationorder'] = 'Term presentation order';
+$string['termpresentationorder_desc'] = 'With this setting, you control how the list of terms is presented within the course settings and (if the field is used as a course filter) within the Dashboard course overview block.';
+$string['wintertermstartmonth'] = 'The month when winter term starts';
+$string['wintertermstartmonth_desc'] = 'With this setting, you define in which month the winter term starts.';
+$string['startmonthnote'] = 'Please note: Acceptable values are numbers between 1 and 12. This setting assumes that the summer term comes before the winter term. If you configure the terms the other way round, the custom field will silently ignore your settings and use the defaults.';

locallib.php

+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Customfield Semester Type - Local library.
+ *
+ * @package   customfield_semester
+ * @copyright 2021 Alexander Bias
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+// Constants for term default start months.
+define('CUSTOMFIELD_SEMESTER_SUMMERTERMSTART', 4);
+define('CUSTOMFIELD_SEMESTER_WINTERTERMSTART', 10);
+
+// Constants for term presentation order.
+define('CUSTOMFIELD_SEMESTER_PRESENTATION_ASC', 'asc');
+define('CUSTOMFIELD_SEMESTER_PRESENTATION_DESC', 'desc');
+
+// Constants for internal term representation.
+define('CUSTOMFIELD_SEMESTER_INTERNAL_ST0WT1', 'st0wt1');
+define('CUSTOMFIELD_SEMESTER_INTERNAL_ST0WT1_ST', 0);
+define('CUSTOMFIELD_SEMESTER_INTERNAL_ST0WT1_WT', 1);
+define('CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2', 'st1wt2');
+define('CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2_ST', 1);
+define('CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2_WT', 2);
+define('CUSTOMFIELD_SEMESTER_INTERNAL_TERMINDEPENDENT', 1);

settings.php

+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Customfield Semester Type - Settings file.
+ *
+ * @package   customfield_semester
+ * @copyright 2021 Alexander Bias
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+if ($ADMIN->fulltree) {
+    // Require local library.
+    require_once($CFG->dirroot.'/customfield/field/semester/locallib.php');
+
+    // Prepare regex for month number. This will be used instead of the PARAM_* type within the admin settings.
+    $monthregex = '/^([1-9]|1[0-2])$/';
+
+    // Setting for the summer term start month.
+    $name = 'customfield_semester/summertermstartmonth';
+    $title = get_string('summertermstartmonth', 'customfield_semester', null, true);
+    $description = get_string('summertermstartmonth_desc', 'customfield_semester', null, true).'<br />'.
+            get_string('startmonthnote', 'customfield_semester', null, true);
+    $setting = new admin_setting_configtext($name, $title, $description, CUSTOMFIELD_SEMESTER_SUMMERTERMSTART, $monthregex, 2);
+    $settings->add($setting);
+
+    // Setting for the winter term start month.
+    $name = 'customfield_semester/wintertermstartmonth';
+    $title = get_string('wintertermstartmonth', 'customfield_semester', null, true);
+    $description = get_string('wintertermstartmonth_desc', 'customfield_semester', null, true).'<br />'.
+            get_string('startmonthnote', 'customfield_semester', null, true);
+    $setting = new admin_setting_configtext($name, $title, $description, CUSTOMFIELD_SEMESTER_WINTERTERMSTART, $monthregex, 2);
+    $settings->add($setting);
+
+    // Setting for the term presentation order.
+    $options = array (CUSTOMFIELD_SEMESTER_PRESENTATION_ASC => get_string('termpresentationasc', 'customfield_semester'),
+            CUSTOMFIELD_SEMESTER_PRESENTATION_DESC => get_string('termpresentationdesc', 'customfield_semester'));
+    $name = 'customfield_semester/termpresentationorder';
+    $title = get_string('termpresentationorder', 'customfield_semester', null, true);
+    $description = get_string('termpresentationorder_desc', 'customfield_semester', null, true);
+    $setting = new admin_setting_configselect($name, $title, $description, CUSTOMFIELD_SEMESTER_PRESENTATION_ASC, $options);
+    $settings->add($setting);
+
+    // Setting for the internal term representation.
+    $options = array (CUSTOMFIELD_SEMESTER_INTERNAL_ST0WT1 => get_string('internaltermrepresentationst0wt1', 'customfield_semester'),
+            CUSTOMFIELD_SEMESTER_INTERNAL_ST1WT2 => get_string('internaltermrepresentationst1wt2', 'customfield_semester'));
+    $name = 'customfield_semester/internaltermrepresentation';
+    $title = get_string('internaltermrepresentation', 'customfield_semester', null, true);
+    $description = get_string('internaltermrepresentation_desc', 'customfield_semester', null, true).'<br />'.
+            get_string('internaltermrepresentationwarning', 'customfield_semester', null, true);
+    $setting = new admin_setting_configselect($name, $title, $description, CUSTOMFIELD_SEMESTER_INTERNAL_ST0WT1, $options);
+    $settings->add($setting);
+}

version.php

@@ -25,5 +25,5 @@
 defined('MOODLE_INTERNAL') || die();
 
 $plugin->component = 'customfield_semester';
-$plugin->version   = 2020041301;
+$plugin->version   = 2020041304;
 $plugin->requires  = 2019111800;