Coursesets

Anmeldesets und -regeln

Auf dieser Seite... (ausblenden)

  1.   1.  Konzept
  2.   2.  Aufbau einer Anmelderegel
    1.   2.1  Speichern und Laden der Daten
    2.   2.2  Regeldefinition
    3.   2.3  Zusammenfassung
  3.   3.  Verteilungsalgorithmus

§

1.  Konzept

Ein Anmeldeset stellt einen Rahmen für Veranstaltungen dar, die gemeinsame Regeln zur Anmeldung besitzen. Mit Stud.IP 3.0 werden initial schon einige verschiedene Regeln mitgeliefert, hier soll jedoch unter anderem beschrieben werden, wie man selbst eine solche Regel implementieren kann.

↑ Inhaltsverzeichnis

§

2.  Aufbau einer Anmelderegel

Alle Anmelderegeln liegen im Ordner lib/admissionrules. Pro Regeltyp gibt es dort einen Ordner, in dem typischerweise die Klassendefinition der Regel liegt (Regeltyp.class.php, SQL-Anweisungen, die bei (De-)Installation der Regel ausgeführt werden müssen und templates zur Konfiguration und zur Kurzanzeige der Regel.

Im Folgenden soll das Beispiel NightAdmission entwickelt werden, eine Regel, die eine Anmeldung nur zwischen 22 und 6 Uhr zulässt.

2.1  Speichern und Laden der Daten

Die Regel vom Typ NightAdmission sollen alle in einer eigenen Tabelle nightadmissions in der Datenbank gespeichert werden. Da dieser Regeltyp neben dem standardmäßig vorhandenen Infotext keine weiteren Attribute besitzt, sieht diese Tabelle so aus:

  1. CREATE TABLE `nightadmissions` (
  2.     `rule_id` VARCHAR(32) NOT NULL,
  3.     `message` TEXT NOT NULL,
  4.     `mkdate` INT NOT NULL,
  5.     `chdate` INT NOT NULL,
  6.     PRIMARY KEY (`rule_id`);

Wird dieser Regeltyp komplett aus dem System entfernt, so reicht folgende SQL-Anweisung zum Aufräumen:

  1. DROP TABLE `nightadmissions`;
  2. DELETE FROM `courseset_rule` WHERE `type`='NightAdmission';

2.2  Regeldefinition

Wir legen eine Datei NightAdmission.class.php an, die von der bereits vorhandenen Klasse AdmissionRule erbt. Da wir nur die aktuelle Uhrzeit berücksichtigen müssen, braucht diese Klasse keine eigenen, weiteren Attribute. Wir definieren nur, mit welchen anderen Anmelderegeltypen diese Regel kombinierbar ist (nämlich alle Standardregeln außer zeitgesteuerter und komplett gesperrter Anmeldung).

Einige Standardmethoden müssen wir ebenfalls implementieren, um das Laden und Speichern in eigene Tabellen zu realisieren.

  1. <?php
  2. class NightAdmission extends AdmissionRule {
  3.  
  4.     /**
  5.      * Standardkonstruktor
  6.      */
  7.     public function __construct($ruleId='', $courseSetId = '')
  8.     {
  9.         parent::__construct($ruleId, $courseSetId);
  10.         $this->default_message = _("Sie können sich nur nachts zwischen 22 und 6 Uhr anmelden.");
  11.         if ($ruleId) {
  12.             // Regel bereits vorhanden, lade Daten.
  13.             $this->load();
  14.         } else {
  15.             // Erzeuge neue ID.
  16.             $this->id = $this->generateId('nightadmissions');
  17.         }
  18.         return $this;
  19.     }
  20.  
  21.     /**
  22.      * Lösche aktuelle Regel aus der Datenbank.
  23.      */
  24.     public function delete() {
  25.         parent::delete();
  26.         $stmt = DBManager::get()->prepare("DELETE FROM `nightadmissions` WHERE `rule_id`=?");
  27.         $stmt->execute(array($this->id));
  28.     }
  29.  
  30.     /**
  31.      * Beschreibungstext für diesen Regeltyp, wird angezeigt, wenn eine neue
  32.      * Regel zu einem Anmeldeset hinzugefügt werden soll.
  33.      */
  34.     public static function getDescription() {
  35.         return _("Diese Regel erlaubt die Anmeldung nur nachts zwischen 22 und 6 Uhr.");
  36.     }
  37.  
  38.     /**
  39.      * Name für diesen Regeltyp, wird angezeigt, wenn eine neue Regel zu einem
  40.      * Anmeldeset hinzugefügt werden soll.
  41.      */
  42.     public static function getName() {
  43.         return _("Nächtliche Anmeldung");
  44.     }
  45.  
  46.     /**
  47.      * Holt das Template zur Anzeige der Konfiuration dieser Regel
  48.      * (configuration.php, hinterlegt im Unterordner templates). Für unser
  49.      * Beispiel brauchen wir nur das Standardtemplate, da es nichts eigenes*
  50.      * für diesen Regeltyp zu konfigurieren gibt.
  51.      */
  52.     public function getTemplate() {
  53.         $tpl = $GLOBALS['template_factory']->open('admission/rules/configure');
  54.         $tpl->set_attribute('rule', $this);
  55.         return $tpl->render();
  56.     }
  57.  
  58.     /**
  59.      * Lädt die Regel aus der Datenbank.
  60.      */
  61.     public function load() {
  62.         $rule = DBManager::get()->fetch("SELECT * FROM `nightadmissions` WHERE `rule_id`=? LIMIT 1", array($this->id));
  63.         $this->message = $rule['message'];
  64.         return $this;
  65.     }
  66.  
  67.     /**
  68.      * Diese Funktion überprüft, ob sich der gegebene Benutzer zur gegebenen
  69.      * Veranstaltung anmelden darf, ob die Regel also greift.
  70.      * Zurückgegeben wird eine Fehlermeldung, falls die Anmeldung nicht
  71.      * möglich ist.
  72.      */
  73.     public function ruleApplies($userId, $courseId) {
  74.         $failed = array();
  75.         $now = mktime();
  76.         // Zeit zwischen 6 und 22 Uhr => keine Anmeldung erlaubt.
  77.         if (date('H', $now) < 22 && date('H', $now) >= 6) {
  78.             $failed[] = $this->default_message;
  79.         }
  80.         return $failed;
  81.     }
  82.  
  83.     /**
  84.      * Speichert die aktuelle Regel in der Datenbank.
  85.      */
  86.     public function store() {
  87.         $stmt = DBManager::get()->prepare("INSERT INTO `nightadmissions`
  88.             (`rule_id`, `message`, `mkdate`, `chdate`)
  89.             VALUES
  90.             (:id, :message, UNIX_TIMESTAMP(), UNIX_TIMESTAMP())
  91.             ON DUPLICATE KEY
  92.             UPDATE `message`=VALUES(`message`), `chdate`=VALUES(`chdate`)");
  93.         $stmt->execute(array('id' => $this->id, 'message' => $this->message));
  94.         return $this;
  95.     }
  96.  
  97. }

Am wichtigsten sind die beiden Methoden ruleApplies und getTemplate.

Erstere Methode spezifiert das Verhalten der Regel, also wann und unter welchen Voraussetzungen überhaupt eine Anmeldung erfolgreich sein kann. Hier können im Prinzip beliebige Datenbankabfragen oder sonstige anderen Funktionen aufgerufen werden.

Das Template definiert die GUI zur Konfiguration der jeweiligen Regel. Standardmäßig wird nur ein Textfeld angeboten, das einen Text aufnehmen kann, der vor der Anmeldung auf der Veranstaltungsseite erscheint. Will man hier weitere Werte, Checkboxen oder anderes einstellbar machen, muss man selbst ein Flexi-Template dafür schreiben.

Daneben kann es noch ein Info-Template geben, das nur zur Anzeige der Regel in normalem Prosatext dient.

2.3  Zusammenfassung

Um diese Beispielregel in Stud.IP zu installieren, reicht es, in lib/admissionrules einen Ordner nightadmissions zu erstellen, dort die obige Klasse Nightadmission.class.php hineinzukopieren und die nötigen SQL-Anweisungen auszuführen. Da kein eigenes Template benötigt wird, ist hier auch kein Unterordner templates von Nöten. In der globalen Konfiguration unter Anmelderegeln kann die Regel dann aktiviert werden. An gleicher Stelle muss dann unter Regelkompatibilität eingestellt werden, mit welchen vorhandenen Regelndie neue Regel kombinierbar ist.

↑ Inhaltsverzeichnis

3.  Verteilungsalgorithmus

Der Algorithmus, der die Plätze der Veranstaltungen eines Anmeldesets verteilt, kann ebenfalls frei selbst implementiert werden. Standardmäßig wird bereits ein Algorithmus mitgeliefert.

Zum Anlegen eines neuen Algorithmus reicht es, das vorhandene Interface AdmissionAlgorithm zu implementieren, dabei handelt es sich im Prinzip nur um eine Methode run(), die den Algorithmus ausführt.

Letzte Änderung am June 28, 2019, at 01:39 PM von anoack. Regelkompatibilität ergänzt