lib.php 10.6 KB
Newer Older
Martyn Smith's avatar
Martyn Smith committed
1 2 3 4 5
<?php
/**
 *
 * @package    mahara
 * @subpackage search
6
 * @author     Catalyst IT Ltd
7 8
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL version 3 or later
 * @copyright  For copyright information on Mahara, please see the README file distributed with this software.
Martyn Smith's avatar
Martyn Smith committed
9 10 11 12 13 14
 *
 */

defined('INTERNAL') || die();

/**
15
 * Helper interface to hold IPluginSearch's abstract static methods
Martyn Smith's avatar
Martyn Smith committed
16
 */
17
interface IPluginSearch {
Martyn Smith's avatar
Martyn Smith committed
18 19 20
    /**
     * Given a query string and limits, return an array of matching users
     *
Martyn Smith's avatar
Martyn Smith committed
21
     * NOTE: user with ID zero or that are NOT active should never be returned
22
     *
Martyn Smith's avatar
Martyn Smith committed
23 24 25 26 27 28 29 30
     * @param string  The query string
     * @param integer How many results to return
     * @param integer What result to start at (0 == first result)
     * @return array  A data structure containing results looking like ...
     *         $results = array(
     *               count   => integer, // total number of results
     *               limit   => integer, // how many results are returned
     *               offset  => integer, // starting from which result
31
     *               data    => array(   // the result records
Martyn Smith's avatar
Martyn Smith committed
32
     *                   array(
33 34 35 36 37 38 39
     *                       id            => integer,
     *                       username      => string,
     *                       institution   => string,
     *                       firstname     => string,
     *                       lastname      => string,
     *                       preferredname => string,
     *                       email         => string,
Martyn Smith's avatar
Martyn Smith committed
40 41
     *                   ),
     *                   array(
42 43 44 45 46 47 48
     *                       id            => integer,
     *                       username      => string,
     *                       institution   => string,
     *                       firstname     => string,
     *                       lastname      => string,
     *                       preferredname => string,
     *                       email         => string,
Martyn Smith's avatar
Martyn Smith committed
49 50 51 52 53
     *                   ),
     *                   array(...),
     *               ),
     *           );
     */
54
    public static function search_user($query_string, $limit, $offset = 0);
55 56

    /**
57
     * Given a query string and limits, return an array of matching groups
58 59 60 61
     *
     * @param string  The query string
     * @param integer How many results to return
     * @param integer What result to start at (0 == first result)
62
     * @param string  Which groups to search (all, member, notmember)
63 64
     * @param string  Category the group belongs to
     * @param string  The institution the group belongs
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
     * @return array  A data structure containing results looking like ...
     *         $results = array(
     *               count   => integer, // total number of results
     *               limit   => integer, // how many results are returned
     *               offset  => integer, // starting from which result
     *               data    => array(   // the result records
     *                   array(
     *                       id            => integer,
     *                       name          => string,
     *                       description   => string,
     *                       jointype      => string,
     *                       owner         => string,
     *                       ctime         => string,
     *                       mtime         => string,
     *                   ),
     *                   array(
     *                       id            => integer,
     *                       name          => string,
     *                       description   => string,
     *                       jointype      => string,
     *                       owner         => string,
     *                       ctime         => string,
     *                       mtime         => string,
     *                   ),
     *                   array(...),
     *               ),
     *           );
     */
93
    public static function search_group($query_string, $limit, $offset=0, $type='member', $category='', $institution='all');
94 95 96 97 98 99 100

    /**
     * Returns search results for users in a particular group
     *
     * It's called by and tightly coupled with get_group_user_search_results() in searchlib.php. Look there for
     * the exact meaning of its parameters and expected return values.
     */
101
    public static function group_search_user($group, $query_string, $constraints, $offset, $limit, $membershiptype, $order, $friendof, $orderbyoptionidx=null);
102

Martyn Smith's avatar
Martyn Smith committed
103 104 105 106 107
    /**
     * Given a query string and limits, return an array of matching objects
     * owned by the current user.  Possible return types are ...
     *   - artefact
     *   - view
108
     *   - @todo potentially other types such as group could be searched by this too
Martyn Smith's avatar
Martyn Smith committed
109 110 111 112 113 114 115 116 117
     *
     * Implementations of this search should search across tags for artefacts
     * and views at a minimum. Ideally the search would also index
     * title/description and other metadata for these objects.
     *
     * @param string  The query string
     * @param integer How many results to return
     * @param integer What result to start at (0 == first result)
     * @param string  Type to search for (either 'all' or one of the types above).
118
     *
Martyn Smith's avatar
Martyn Smith committed
119
     */
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
    public static function self_search($query_string, $limit, $offset, $type = 'all');
}

/**
 * Base search class. Provides a common interface with which searches can be
 * carried out.
 */
abstract class PluginSearch extends Plugin implements IPluginSearch {

    public static function get_plugintype_name() {
        return 'search';
    }

    /**
     * This function gets called when the sitewide search plugin is switched to
     * this one. It's the chance for the plugin to do any post-configuration
     * initialization it might need. (The same stuff you'd probably do after
     * changing the plugin's configuration via its extension config page.)
     */
    public static function initialize_sitewide() {
        return true;
    }

    /**
     * This function gets called when the sitewide search plugin is switched AWAY
     * from this one. It's the chance for the plugin to disable anything that would
     * cause problems now that the search is no longer in use.
     */
    public static function cleanup_sitewide() {
        return true;
    }

152 153 154 155 156 157 158 159 160
    /**
     * This function gets called everytime the site options are saved. It is used to
     * detect whether the search plugin can connect to any servers it requires.
     * Defaults to true.
     */
    public static function can_connect() {
        return true;
    }

161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
    /**
     * This function determines whether the plugin is currently available to be chosen
     * as the sitewide search plugin (i.e. get_config('searchplugin'))
     */
    public static function is_available_for_site_setting() {
        return true;
    }

    /**
     * This function determines whether the plugin allows a search box to display for
     * non-logged in users - only useful if results returned by search are allowed to
     * be seen by the public
     */
    public static function publicform_allowed() {
        return false;
    }

    /**
     * This function indicates whether the plugin should take the raw $query string
     * when its group_search_user function is called, or whether it should get the
     * parsed query string.
     *
     * @return boolean
     */
    public static function can_process_raw_group_search_user_queries() {
        return false;
    }
Martyn Smith's avatar
Martyn Smith committed
188

189
    protected static function self_search_make_links(&$data) {
Martyn Smith's avatar
Martyn Smith committed
190
        $wwwroot = get_config('wwwroot');
Martyn Smith's avatar
Martyn Smith committed
191 192 193 194
        if ($data['count']) {
            foreach ($data['data'] as &$result) {
                switch ($result['type']) {
                    case 'artefact':
Martyn Smith's avatar
Martyn Smith committed
195
                        safe_require('artefact', get_field('artefact_installed_type', 'plugin', 'name', $result['artefacttype']));
196 197 198
                        $artefact = artefact_instance_from_id($result['id']);
                        if ($artefact->in_view_list() && $views = $artefact->get_views_instances()) {
                            foreach ($views as $view) {
199
                                $result['views'][$view->get('title')] = get_config('wwwroot') . 'artefact/artefact.php?artefact='
200 201 202 203 204 205
                                    . $result['id'] . '&view=' . $view->get('id');
                            }
                        }
                        if ($links = $artefact->get_links($result['id'])) {
                            $result['links'] = $links;
                        }
Martyn Smith's avatar
Martyn Smith committed
206 207 208
                        break;
                    case 'view':
                        $result['links'] = array(
209 210
                            '_default'                        => $wwwroot . 'view/view.php?id=' . $result['id'],
                            // TODO: these are certainly broken!
Martyn Smith's avatar
Martyn Smith committed
211 212 213 214
                            get_string('editviewinformation') => $wwwroot . 'view/editmetadata.php?viewid=' . $result['id'],
                            get_string('editview')            => $wwwroot . 'view/edit.php?viewid=' . $result['id'],
                            get_string('editaccess')          => $wwwroot . 'view/editaccess.php?viewid=' . $result['id'],
                        );
Martyn Smith's avatar
Martyn Smith committed
215 216 217 218 219 220 221
                        break;
                    default:
                        break;
                }
            }
        }
    }
222 223 224 225 226 227 228 229 230 231 232 233 234 235


    /**
     * Generates the search form used in the page headers
     * @return string
     */
    public static function header_search_form() {
        return pieform(array(
                'name'                => 'usf',
                'action'              => get_config('wwwroot') . 'user/find.php',
                'renderer'            => 'oneline',
                'autofocus'           => false,
                'validate'            => false,
                'presubmitcallback'   => '',
Pat Kira's avatar
Pat Kira committed
236
                'class'               => 'header-search-form',
237 238 239
                'elements'            => array(
                        'query' => array(
                                'type'           => 'text',
240
                                'defaultvalue'   => '',
241
                                'title'          => get_string('searchusers'),
242
                                'placeholder'    => get_string('searchusers'),
243
                                'hiddenlabel'    => true,
244 245
                        ),
                        'submit' => array(
246 247 248 249
                            'type' => 'button',
                            'class' => 'btn-primary input-group-btn',
                            'usebuttontag' => true,
                            'value' => '<span class="icon icon-search icon-lg" role="presentation" aria-hidden="true"></span><span class="sr-only">'. get_string('go') . '</span>',
250 251 252 253
                        )
                )
        ));
    }
Martyn Smith's avatar
Martyn Smith committed
254
}