aus "Stud.IP-Entwicklerdokumentation"

Entwickler: QuickSearch

QuickSearch-Klasse

In lib/classes/QuickSearch.class.php wird eine GUI-Klasse bereit gestellt, mit der man ein einzeiliges Suchfeld inklusive AJAX-Dropdown Menü schnell und einfach an jede Stelle einbauen kann. Vorteile:

Im HTML gibt es dann das Input-Feld, das man erwartet und ein weiteres unsichtbares Input-Feld für die ID. Meistens sucht man nach etwas wie Personen, die einen klar lesbaren Namen haben. Aber der Programmierer will an der Stelle eigentlich nicht den Namen, sondern lieber eine user_id haben. Die user_id wird dann versteckt im Hintergrund gespeichert. Der Programmierer kann QuickSearch einbinden, wie ein Input-Feld, in das der Nutzer wie magisch nur die user_id eingegeben hätte - der Nutzer gibt aber den Klarnamen ein. QuickSearch bietet diese Architektur ganz automatisch.

Einbau eines QuickSearch Feldes

Üblicherweise besteht die Suche aus zwei Elementen, die zusammen arbeiten: erstens, das Suchelement, das quasi ein Model ist, das konkret nach etwas sucht, und zweitens die QuickSearch-Klasse, die diese Suche ausführt und sich um die Ausgabe kümmert.

  1. $suche = new SQLSearch("SELECT username, Nachname " .
  2.     "FROM auth_user_md5 " .
  3.     "WHERE Nachname LIKE :input " .
  4.     "LIMIT 5", _("Nachname"), "username");
  5. print QuickSearch::get("username", $suche)
  6.     ->setInputStyle("width: 240px")
  7.     ->render();

Die Variable $suche ist also das Objekt, das die Suche durchführt. Dieses Objekt ist nicht notwendigerweise ein Objekt der Klasse SQLSearch, sondern ein Objekt der Klasse SearchType (wovon SQLSearch eine Unterklasse ist). SQLSearch ist nun eine spezielle Klasse, die beliebige SQL-Queries auf die Datenbank anwenden kann. In diesem Query bezeichnet :input stets den Suchstring, den ein Nutzer später eingibt.

Die Klasse QuickSearch kümmert sich danach dann um die Ausgabe. Der erste Wert des Konstruktors ist immer der Name des Suchfeldes im HTML, also zum Beispiel <input name="username"> . Der zweite Parameter ist dann das Suchobjekt, das wir vorher definiert haben. Danach folgen einige Methoden, um die Ausgabe weiter zu konfigurieren wie setInputStyle("width: 240px") und die Methode render() veranlasst dann die Ausgabe des Ganzen.

Und so wird es dann aussehen:

Shortcut

Für ganz einfache Suchen wie der Suche nach einem username oder einer user_id kann man als Suchobjektes auch einfach die Klasse "StandardSearch mit Parameter "username", "user_id", "Seminar_id", "Institut_id" oder "Arbeitsgruppe_id" schreiben. Also:

  1. print QuickSearch::get("seminar", new StandardSearch("Seminar_id"))
  2.     ->setInputStyle("width: 240px")
  3.     ->render();

Weitere Methoden der QuickSearch-Klasse

Weitere Suchobjekte

Man ist nicht auf SQLSearch beschränkt. Jeder Programmierer kann eigene Suchobjekte definieren und so zum Beispiel auch eine Lucene-Index-Suche implementieren, wenn ihm gerade danach ist. Die Suchklassen müssen alle von der Klasse SearchType abgeleitet werden und mindestens die Methoden includePath() und (sinnvollerweise) getResults(...) überschreiben. Falls die Suchklasse im Kern von Stud.IP benutzt wird, sollte sie auch im Verzeichnis lib/classes/seachtypes/ hinterlegt werden. Aber Pluginbauer können ihre Suchklassen natürlich auch im Plugin hinterlegen.

Eine kleine Beispielsuchklasse könnte zum Beispiel so aussehen:

class SeminarTypSuchen extends SearchType {

    public function getTitle() {
        return _("Seminartyp suchen");
    }

    public function getResults($input, $contextual_data = array()) {
        $typen = $GLOBALS['SEM_TYPE'];
        foreach($typen as $key => $typ) {
            if (strpos($typ['name'], $input) === false) {
                unset($typen[$key]);
            } else {
                $typen[$key] = array($key, $typ['name']);
            }
        }
        return $typen;
    }

    public function includePath() {
        return __file__;
    }
}

Diese Klasse ist für den Fall gedacht, dass es in Stud.IP unübersichtlich viele Semeinartypen gibt. Diese Typen sind in der config.inc.php definiert und finden sich also nicht in der Datenbank. Für diesen Zweck ist also die Klasse SQLSearch unpraktikabel.

Die Methode getTitle gibt nur den Schriftzug, der später im leeren Formularfeld stehen soll, wider. Die Methode getResults erledigt gewissermaßen die ganze Arbeit, durchsucht das Array aller Seminartypen nach dem eingegeben String und gibt ein Ergebnisarray der Form array(array(ID_des_Seminar_Typs, Name_des_Typs), ...) zurück. Die Methode includePath ist notwendig, damit diese Klasse gefunden wird (es gibt einen internen kleinen Autoloader), hat aber stets den gleichen Inhalt, kann also für alle Erweiterungsklassen von SearchType so übernommen werden.

Und das sollte es auch gewesen sein. Man kann noch einen Avatar für seine Suchergebnisse angeben, was sich aber für Seminartypen nicht gerade anbietet. Dennoch würde man da tun, indem man die Methoden getAvatar und getAvatarImageTag überschreibt. Siehe dazu Dokumentation im Quellcode.

URL: https://docs.studip.de/develop/Entwickler/QuickSearch
Zuletzt geändert am 10.11.2016 11:49 Uhr