Anmeldesets und -regeln

Anmeldesets und -regeln

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.

Aufbau einer Anmelderegel

Anmelderegeln liegen in zwei Ordnern:

• der PHP-Teil liegt in lib/admissionrules.
• die zugehörige Vue-Komponente liegt in resources/vue/components/admission. In lib/admissionrules/<unterordner> liegen typischerweise die Klassendefinition der Regel (Regeltyp.php, SQL-Anweisungen, die bei (De-)Installation der Regel ausgeführt werden müssen und ein Template zur Kurzanzeige der Regel.

Im Folgenden soll das Beispiel AdditionalDataAdmission entwickelt werden, eine Regel, die die Eingabe zusätzlicher Daten (Telefonnummer und Semesteradresse) vor der Anmeldung erfordert.

Speichern und Laden der Daten

Die Regel vom Typ AdditionalDataAdmission sollen alle in einer eigenen Tabelle additionaldataadmissions in der Datenbank gespeichert werden. Diese kann so aussehen:

CREATE TABLE `additionaldataadmissions` (
    `rule_id` CHAR(32) NOT NULL COLLATE latin1_bin,
    `message` TEXT NOT NULL,
    `phone` VARCHAR(255) NOT NULL,
    `address` VARCHAR(1024) NOT NULL,
    `mkdate` INT NOT NULL,
    `chdate` INT NOT NULL,
    PRIMARY KEY (`rule_id`);

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

DROP TABLE `additionaldataadmissions`;
DELETE FROM `courseset_rule` WHERE `type`='AdditionalDataAdmission';

Regeldefinition (PHP)

Die PHP-Klasse für die Regel wird von AdmissionRule abgeleitet. Damit das Zusammenspiel mit der zugehörigen Vue-Komponente funktionieren kann, müssen mindestens diese beiden Methoden implementiert sein:

• getPayload() liefert ein Array mit den Attributen (und deren Werten), die für diesen Regeltyp spezifisch sind. In unserem Fall wären das also phone und address für die Telefonnummer und Semesteradresse.

• setAllData($data) empfängt ein Array mit den Werten, die für diese Regel spezifisch sind. Hier also wieder phone und address.

• Weiter ist die Methode ruleApplies($user_id, $course_id) wichtig, die ermittelt, ob die angegebene Person in die angegebene Veranstaltung eingetragen werden darf.

Regeldefinition (Vue)

Die Vue-Komponente AdditionalDataAdmission implementiert sowohl die Oberfläche zur Regelkonfiguration als auch die Logik, die Daten an das PHP-Backend zu übergeben. Die Komponente sollte das Mixin AdmissionRuleMixin verwenden und bekommt damit bereits die gesamte Kommunikations- und Wertetransferlogik eingebaut. Darüber hinaus braucht die Komponente neben ihrem Template nur folgende Attribute und Methoden:

• data() legt fest, welche eigenen Attribute es in dieser Komponente gibt. Das wären hier phone und address für Telefonnummer und Semesteradresse

•   payload() {
        return {
            type: 'AdditionalDataAdmission',
            payload: {
                phone: this.phone,
                address: this.address,
            }
        }
    }

  Diese Methode ist computed und liefert die regelspezifischen Attribute zur Übertragung an die JSON-API-Route zur Speicherung
• Weiter werden noch zwei Methoden benötigt, um die eingebenen Daten von außen setzen und beim Speichern validieren zu können:

        setRuleData(data) {
            this.phone = data.attributes.payload.phone;
            this.address = data.attributes.payload.address;
        },
        validate() {
            this.invalidData = [];
            if (this.phone === '') {
                this.invalidData.push(this.$gettext('Es ist keine Telefonnummer angegeben.'));
            }
  
            if (this.address === '') {
                this.invalidData.push(this.$gettext('Es ist keine Semesteradresse angegeben.'));
            }
  
            return this.invalidData.length === 0;
        }

Verknüpfung Vue-Komponente mit Regeltyp

Damit Stud.IP weiß, welche Vue-Komponente zu diesem Regeltyp gehört, muss diese Verknüpfung in STUDIP.Admission.availableRules hergestellt werden:

STUDIP.Admission.availableRules.AdditionalDataAdmission = 'AdditionalDataAdmission.vue'

Hier muss der Pfad der Komponente relativ zu resources/vue/components/admission angegeben werden.

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.