Merge branch 'main' into issue-3911issue-3911

1 files changed, 548 insertions, 0 deletions

diff --git a/lib/classes/MultiPersonSearch.php b/lib/classes/MultiPersonSearch.php
new file mode 100644
index 0000000..3ca617b
--- /dev/null
+++ b/lib/classes/MultiPersonSearch.php
@@ -0,0 +1,548 @@
+<?php
+/**
+ * MultiPersonSearch.php
+ *
+ * This class provides a GUI-element for searching, adding and removing
+ * multiple persons. If JavaScript is enabled the GUI-element is shown
+ * as a dialog on the current page. Otherwise the GUI-element is shown
+ * on a separate page.
+ *
+ * This program 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 2 of
+ * he License, or (at your option) any later version.
+ *
+ * @author      Sebastian Hobert <sebastian.hobert@uni-goettingen.de>
+ * @license     http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
+ * @category    Stud.IP
+ * @link        http://docs.studip.de/develop/Entwickler/MultiPersonSearch
+ */
+class MultiPersonSearch {
+
+    private $name;
+    private $linkIconPath = "";
+    private $linkText = "";
+    private $title = "";
+    private $description = "";
+    private $executeURL;
+    private $jsFunction = null;
+    private $pageURL = null;
+    private $quickfilterIds = [];
+    private $defaultSelectableUsersIDs = [];
+    private $defaultSelectedUsersIDs = [];
+    private $searchObject = null;
+    private $additionalHMTL = "";
+    private $navigationItem = "";
+    private $dataDialogStatus = false;
+
+    /**
+     * restores a MultiPersonSearch object.
+     *
+     * @param string name of the object
+     *
+     * @return MultiPersonSearch
+     */
+    public static function load($name)
+    {
+        $mp = new MultiPersonSearch($name);
+        $mp->restoreFromSession();
+        return $mp;
+    }
+
+    /**
+     * returns a MultiPersonSearch object.
+     *
+     * @param string name of the object
+     *
+     * @return MultiPersonSearch
+     */
+    public static function get($name)
+    {
+        $mp = new MultiPersonSearch($name);
+        return $mp;
+    }
+
+    /**
+     * contsructs a new MultiPersonSearch object.
+     *
+     * @param string name of the object and html ids
+     */
+    public function __construct($name)
+    {
+       $this->name = $name;
+       $_SESSION['multipersonsearch'][$this->name]['lastUse'] = time();
+       $this->collectGarbage();
+       $this->setDefaultValues();
+
+    }
+
+    /**
+     * returns the newly added persons. The array will contain all
+     * persons which are selected (on the right side of the dialog) but
+     * without the defaultSelectedUsers.
+     *
+     * @return array containing all new persons
+     */
+    public function getAddedUsers() {
+        return $_SESSION['multipersonsearch'][$this->name]['added'] ?? [];
+    }
+
+    /**
+     * saves the added persons to $_SESSION.
+     */
+    public function saveAddedUsersToSession() {
+        $addedUsers = [];
+        foreach (Request::optionArray($this->name . '_selectbox') as $selected) {
+            if (!in_array($selected, $_SESSION['multipersonsearch'][$this->name]['defaultSelectedUsersIDs'])) {
+                $addedUsers[] = $selected;
+            }
+        }
+        $_SESSION['multipersonsearch'][$this->name]['added'] = $addedUsers;
+        $_SESSION['multipersonsearch'][$this->name]['additional'] = Request::optionArray('additional');
+    }
+
+    /**
+     * returns the removed persons. The array will contain all
+     * persons which were selected by default (on the right side of the
+     * dialog) and then removed by the user.
+     *
+     * @return array containing all removed persons
+     */
+    public function getRemovedUsers() {
+        return $_SESSION['multipersonsearch'][$this->name]['removed'];
+    }
+
+    /**
+     * saves the removed persons to $_SESSION.
+     */
+    public function saveRemovedUsersToSession() {
+        $removedUsers = [];
+        foreach ($this->defaultSelectedUsersIDs as $default) {
+            if (!in_array($default, Request::optionArray($this->name . '_selectbox'))) {
+                $removedUsers[] = $default;
+            }
+        }
+        $_SESSION['multipersonsearch'][$this->name]['removed'] =  $removedUsers;
+    }
+
+    /**
+     * renders a link to open the multipersonsearch dialog.
+     *
+     * @param string $with_link_text include link text in output
+     */
+    public function render($with_link_text = true) {
+        $template = $GLOBALS['template_factory']->open('multipersonsearch/link.php');
+
+        $template->set_attribute('linkIconPath', $this->linkIconPath);
+        $template->set_attribute('linkText', $with_link_text ? $this->linkText : '');
+        $template->set_attribute('title', $this->title);
+        $template->set_attribute('name', $this->name);
+        $template->set_attribute('description', $this->description);
+        $template->set_attribute('executeURL', $this->executeURL);
+        $template->set_attribute('jsFunction', $this->jsFunction);
+        $this->storeToSession();
+        return $template->render();
+    }
+
+    /**
+     * sets the icon of the link to open the dialog. To hide the icon an
+     * empty string can be set.
+     *
+     * @param string path ot the icon
+     *
+     * @return MultiPersonSearch
+     */
+    public function setLinkIconPath($path) {
+        $this->linkIconPath = $path;
+
+        return $this;
+    }
+
+    /**
+     * returns the icon of the link to open the dialog.
+     *
+     * @return string path ot the icon.
+     */
+    public function getLinkIconPath() {
+        return $this->linkIconPath;
+    }
+
+    /**
+     * sets the link text of the link to open the dialog. To hide the
+     * text an empty string can be set.
+     *
+     * @param string text of the link
+     *
+     * @return MultiPersonSearch
+     *
+     */
+    public function setLinkText($text = "") {
+        $this->linkText = $text;
+
+        return $this;
+    }
+
+    /**
+     * returns the link text of the link.
+     *
+     * @return string text of the link.
+     */
+    public function getLinkText() {
+        return $this->linkText;
+    }
+
+    /**
+     * sets the action which will handle the added and removed persons after saving the dialog.
+     *
+     * @param string action
+     *
+     * @return MultiPersonSearch
+     */
+    public function setExecuteURL($action) {
+        $this->executeURL = $action;
+
+        return $this;
+    }
+
+    /**
+     * returns the action which will handle the added and removed persons after saving the dialog.
+     *
+     * @return string action which will handle the form data.
+     */
+    public function getExecuteURL() {
+        return $this->executeURL;
+    }
+
+    /**
+     * sets a JavaScript-function to be fired when the user has pressed the submit-button.
+     * Arguments are:
+     * function fireme(id_of_item, text_of_item)
+     * example setting: MPS->setJSFunctionOnSubmit('fireme');
+     *
+     * @param string $function_name the name of the javascript function
+     *
+     * @return MultiPersonSearch
+     */
+    public function setJSFunctionOnSubmit($function_name)
+    {
+        $this->jsFunction = $function_name;
+        return $this;
+    }
+
+    /**
+     * returns a JavaScript-function which should be fired when the user has pressed the submit button.
+     *
+     * @return string function name
+     */
+    public function getJSFunctionOnSubmit()
+    {
+        return $this->jsFunction;
+    }
+
+    /**
+     * sets the search object.
+     *
+     * @param SearchType object of type SearchType (e.g. SQLSearch.php)
+     *
+     * @return MultiPersonSearch
+     */
+    public function setSearchObject($searchType) {
+        $this->searchObject = $searchType;
+
+        return $this;
+    }
+
+    /**
+     * returns the search object.
+     *
+     * @return SearchType
+     */
+    public function getSearchObject() {
+        return $this->searchObject;
+    }
+
+    /**
+     * sets html code which will be shown inside the form element.
+     *
+     * @param string html code
+     *
+     * @return MultiPersonSearch
+     */
+    public function setAdditionalHTML($html) {
+        $this->additionalHMTL = $html;
+
+        return $this;
+    }
+
+
+    /**
+     * enables or disabled data-dialog
+     * @param boolean $status
+     * @return $this
+     */
+    public function setDataDialogStatus($status) {
+        $this->dataDialogStatus = $status;
+
+        return $this;
+    }
+
+    /**
+     * returns if data-dialog is enabled or disabled
+     * @return bool
+     */
+    public function getDataDialogStatus() {
+        return $this->dataDialogStatus;
+    }
+    /**
+     * returns html code which will be shown inside the form element.
+     *
+     * @return string html code
+     */
+    public function getAdditionHTML() {
+        return $this->additionalHMTL;
+    }
+
+    /**
+     * returns an additional option array.
+     *
+     * @return string html code
+     */
+    public function getAdditionalOptionArray() {
+        return $_SESSION['multipersonsearch'][$this->name]['additional'];
+    }
+
+    /**
+     * sets the persons which will be shown as selectable by default on
+     * the left side of the dialoag.
+     *
+     * @param array array containing user-ids
+     */
+    public function setDefaultSelectableUser($userArray) {
+        $userArray = array_unique($userArray);
+        $this->defaultSelectableUsersIDs = [];
+        if (is_array($userArray)) {
+            foreach ($userArray as $userId) {
+                $this->defaultSelectableUsersIDs[] = $userId;
+            }
+        }
+        return $this;
+    }
+    /**
+     * returns the ids of defaultselectable users.
+     *
+     * @return array
+     */
+    public function getDefaultSelectableUsersIDs() {
+        return $this->defaultSelectableUsersIDs;
+    }
+
+    /**
+     * sets the persons which will be shown as selected by default on
+     * the right side of the dialoag.
+     *
+     * @param array array containing user-ids
+     */
+    public function setDefaultSelectedUser($userArray) {
+        $userArray = array_unique($userArray);
+        $this->defaultSelectedUsersIDs = [];
+        if (is_array($userArray)) {
+            foreach ($userArray as $userId) {
+                $this->defaultSelectedUsersIDs[]  = $userId;
+            }
+        }
+        return $this;
+    }
+
+    /**
+     * returns the ids of defaultselected users.
+     *
+     * @return array
+     */
+    public function getDefaultSelectedUsersIDs() {
+        return $this->defaultSelectedUsersIDs;
+    }
+
+
+    /**
+     * sets the title of the dialog.
+     *
+     * @param string  $title title of the dialog
+     *
+     * @return MultiPersonSearch
+     */
+    public function setTitle($title) {
+        $this->title = $title;
+        return $this;
+    }
+
+    /**
+     * returns the title.
+     *
+     * @return string
+     */
+    public function getTitle() {
+        return $this->title;
+    }
+
+
+    /**
+     * sets the description of the dialog.
+     *
+     * @param string  $desc description of the dialog
+     *
+     * @return MultiPersonSearch
+     */
+    public function setDescription($desc) {
+        $this->description = $desc;
+        return $this;
+    }
+
+    /**
+     * returns the description.
+     *
+     * @return string
+     */
+    public function getDescription() {
+        return $this->description;
+    }
+
+    /**
+     * returns the url of the page where the GUI element is added.
+     *
+     * @return string
+     */
+    public function getPageUrl() {
+        return $this->pageURL;
+    }
+
+    /**
+     * adds a new quickfilter.
+     *
+     * @param string $title title of the new quickfilter
+     * @param array $userArray containing all user-ids belonging to the quickfilter
+     *
+     * @return MultiPersonSearch
+     */
+    public function addQuickfilter($title, $userArray) {
+        $users = [];
+        $usersIds = [];
+        if (is_array($userArray)) {
+            foreach ($userArray as $userId) {
+                $usersIds[]  = $userId;
+            }
+        }
+        $this->quickfilterIds[(string) $title] = $usersIds;
+
+        return $this;
+    }
+
+    /**
+     * returns the ids of quickfilters.
+     *
+     * @return array
+     */
+    public function getQuickfilterIds()
+    {
+        return $this->quickfilterIds ?: [];
+    }
+
+    /**
+     * clears all quickfilters.
+     *
+     * @return MultiPersonSearch
+     */
+    public function clearQuickfilters() {
+        $this->quickfilterIds = [];
+
+        return $this;
+    }
+
+    /**
+     * sets the navigation item.
+     *
+     * @param string  $navigationItem navigation item
+     *
+     * @return MultiPersonSearch
+     */
+    public function setNavigationItem($navigationItem) {
+        $this->navigationItem = $navigationItem;
+
+        return $this;
+    }
+
+    /**
+     * returns the navigation item.
+     *
+     * @return string
+     */
+    public function getNavigationItem() {
+        return $this->navigationItem;
+    }
+
+    /**
+     * stores the internal data to a session.
+     */
+    public function storeToSession() {
+        $_SESSION['multipersonsearch'][$this->name]['title'] = $this->title;
+        $_SESSION['multipersonsearch'][$this->name]['description'] = $this->description;
+        $_SESSION['multipersonsearch'][$this->name]['additionalHMTL'] = $this->additionalHMTL;
+        $_SESSION['multipersonsearch'][$this->name]['executeURL'] = $this->executeURL;
+        $_SESSION['multipersonsearch'][$this->name]['jsFunction'] = $this->jsFunction;
+        $_SESSION['multipersonsearch'][$this->name]['pageURL'] = Request::url();
+        $_SESSION['multipersonsearch'][$this->name]['defaultSelectableUsersIDs'] = $this->defaultSelectableUsersIDs;
+        $_SESSION['multipersonsearch'][$this->name]['defaultSelectedUsersIDs'] = $this->defaultSelectedUsersIDs;
+        $_SESSION['multipersonsearch'][$this->name]['quickfilterIds'] = $this->quickfilterIds;
+        $_SESSION['multipersonsearch'][$this->name]['searchObject'] = serialize($this->searchObject);
+        $_SESSION['multipersonsearch'][$this->name]['navigationItem'] = $this->navigationItem;
+        $_SESSION['multipersonsearch'][$this->name]['dataDialogStatus'] = $this->dataDialogStatus;
+    }
+
+    /**
+     * restores the internal data from a session.
+     */
+    public function restoreFromSession() {
+        if (isset($_SESSION['multipersonsearch'][$this->name])) {
+            $this->title = $_SESSION['multipersonsearch'][$this->name]['title'] ?? '';
+            $this->description = $_SESSION['multipersonsearch'][$this->name]['description'] ?? '';
+            $this->quickfilterIds = $_SESSION['multipersonsearch'][$this->name]['quickfilterIds'] ?? [];
+            $this->additionalHMTL = $_SESSION['multipersonsearch'][$this->name]['additionalHMTL'] ?? '';
+            $this->executeURL = html_entity_decode($_SESSION['multipersonsearch'][$this->name]['executeURL'] ?? '');
+            $this->jsFunction = $_SESSION['multipersonsearch'][$this->name]['jsFunction'] ?? '';
+            $this->pageURL = $_SESSION['multipersonsearch'][$this->name]['pageURL'] ?? '';
+            $this->defaultSelectableUsersIDs = $_SESSION['multipersonsearch'][$this->name]['defaultSelectableUsersIDs'] ?? [];
+            $this->defaultSelectedUsersIDs = $_SESSION['multipersonsearch'][$this->name]['defaultSelectedUsersIDs'] ?? [];
+            $this->searchObject = unserialize($_SESSION['multipersonsearch'][$this->name]['searchObject'] ?? null);
+            $this->navigationItem = $_SESSION['multipersonsearch'][$this->name]['navigationItem'] ?? null;
+            $this->dataDialogStatus = $_SESSION['multipersonsearch'][$this->name]['dataDialogStatus'] ?? '';
+        }
+    }
+
+    /**
+     * clears the session data.
+     */
+    public function clearSession() {
+        unset($_SESSION['multipersonsearch'][$this->name]);
+    }
+
+    /**
+     * sets default values of the internal variables.
+     */
+    private function setDefaultValues() {
+        $this->title = '';
+        $this->description = _('Bitte wählen Sie aus, wen Sie hinzufügen möchten.');
+        $this->linkIconPath = Icon::create('add');
+    }
+
+    /**
+     * clear unused sessions.
+     */
+    private function collectGarbage() {
+        $maxLifeTime = 30; // minutes
+        foreach ($_SESSION['multipersonsearch'] as $key=>$value) {
+            if (time() - $value['lastUse'] > $maxLifeTime * 60) {
+                unset($_SESSION['multipersonsearch'][$key]);
+            }
+        }
+    }
+
+}