Search API - Revision history

Mudrd8mz: Text replacement - "`" to ""`


2021-07-15T08:09:50Z
Text replacement - "<code (.*)>" to "<syntaxhighlight lang="$1">"

				
				
				
				
				
				← Older revision
				Revision as of 08:09, 15 July 2021
				
Line 46:
Line 46:
Assuming the table containing the data you are indexing is called xxxxx, the basic principle is to do a query similar to: Assuming the table containing the data you are indexing is called xxxxx, the basic principle is to do a query similar to:



<code sql> <syntaxhighlight lang="sql">
SELECT x.* SELECT x.*
   FROM {xxxxx} x    FROM {xxxxx} x

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T20:24:50Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 20:24, 14 July 2021
Line 51:		Line 51:
	WHERE x.timemodified >= ?		WHERE x.timemodified >= ?
	ORDER BY x.timemodified ASC		ORDER BY x.timemodified ASC
	</~~code~~>		</syntaxhighlight>

	However you will also need to incorporate code to restrict the results based on the context within Moodle.		However you will also need to incorporate code to restrict the results based on the context within Moodle.
Line 72:		Line 72:
	return $DB->get_recordset_sql($sql, array_merge($contextparams, [$modifiedfrom]));		return $DB->get_recordset_sql($sql, array_merge($contextparams, [$modifiedfrom]));
	}		}
	</~~code~~>		</syntaxhighlight>

	Note the helper function '''get_context_restriction_sql''' is available for content within modules (there is a slightly different one for blocks). If you have an unusual case where the data being indexed is not within a module or block, you may need to write the context restriction SQL yourself.		Note the helper function '''get_context_restriction_sql''' is available for content within modules (there is a slightly different one for blocks). If you have an unusual case where the data being indexed is not within a module or block, you may need to write the context restriction SQL yourself.
Line 84:		Line 84:
	return $this->get_document_recordset($modifiedfrom);		return $this->get_document_recordset($modifiedfrom);
	}		}
	</~~code~~>		</syntaxhighlight>

	Note: Existing code that only has a get_recordset_by_timestamp function will still work in Moodle 3.4+ just as it did in earlier versions, but certain features added in Moodle 3.4+ (most importantly, indexing content from restored courses or activities) will not work properly.		Note: Existing code that only has a get_recordset_by_timestamp function will still work in Moodle 3.4+ just as it did in earlier versions, but certain features added in Moodle 3.4+ (most importantly, indexing content from restored courses or activities) will not work properly.
Line 148:		Line 148:
	return $doc;		return $doc;
	}		}
	</~~code~~>		</syntaxhighlight>

	As noted above, the '''modified''' field here must be consistent with the ordering and >= condition in the get_document_recordset function.		As noted above, the '''modified''' field here must be consistent with the ordering and >= condition in the get_document_recordset function.
Line 160:		Line 160:
	return true;		return true;
	}		}
	</~~code~~>		</syntaxhighlight>

	Define attach_files function, which receives a \core_search\document object and fills it with stored_file objects.		Define attach_files function, which receives a \core_search\document object and fills it with stored_file objects.
Line 176:		Line 176:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	==== Indexing performance ====		==== Indexing performance ====
Line 194:		Line 194:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	protected static $levels = [CONTEXT_COURSE]		protected static $levels = [CONTEXT_COURSE]
	</~~code~~>		</syntaxhighlight>

	==== Final access checking ====		==== Final access checking ====
Line 218:		Line 218:
	return \core_search\manager::ACCESS_GRANTED;		return \core_search\manager::ACCESS_GRANTED;
	}		}
	</~~code~~>		</syntaxhighlight>

	The automatic context-based filtering should get rid of most of the results where a user do not have access. If '''check_access''''s ratio of visible results vs non-visible results is high you might need to rethink about the context where your search area belongs or we might need to expand the APIs.		The automatic context-based filtering should get rid of most of the results where a user do not have access. If '''check_access''''s ratio of visible results vs non-visible results is high you might need to rethink about the context where your search area belongs or we might need to expand the APIs.
Line 231:		Line 231:
	return new \moodle_url('link/to/your/component.php', array('id' => $doc->get('id')));		return new \moodle_url('link/to/your/component.php', array('id' => $doc->get('id')));
	}		}
	</~~code~~>		</syntaxhighlight>

	The link to the result context, in some cases it might be the same than the doc url. Should return a \moodle_url object.		The link to the result context, in some cases it might be the same than the doc url. Should return a \moodle_url object.
Line 240:		Line 240:
	return new \moodle_url('link/to/your/component/context.php', array('id' => $doc->get('id')));		return new \moodle_url('link/to/your/component/context.php', array('id' => $doc->get('id')));
	}		}
	</~~code~~>		</syntaxhighlight>

	== Carry out a search ==		== Carry out a search ==
Line 261:		Line 261:
	$data = (object)['q' => 'frogs'];		$data = (object)['q' => 'frogs'];
	$results = $search->search($data);		$results = $search->search($data);
	</~~code~~>		</syntaxhighlight>

	Note: You don't need to call require_login immediately before searching, but it must be called somewhere before searching. The search system requires that there is a logged-in user in order to work. It uses this user to decide which search results they are allowed to see.		Note: You don't need to call require_login immediately before searching, but it must be called somewhere before searching. The search system requires that there is a logged-in user in order to work. It uses this user to decide which search results they are allowed to see.

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:28:58Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:28, 14 July 2021
				
Line 57:
Line 57:
Here is a full example from the Glossary module (you can find this code in mod/glossary/classes/search/entry.php): Here is a full example from the Glossary module (you can find this code in mod/glossary/classes/search/entry.php):



<code php> <syntaxhighlight lang="php">
public function get_document_recordset($modifiedfrom = 0, \context $context = null) { public function get_document_recordset($modifiedfrom = 0, \context $context = null) {
     global $DB;      global $DB;
Line 80:
Line 80:
Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well as Moodle 3.4+, add the following additional function: Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well as Moodle 3.4+, add the following additional function:



<code php> <syntaxhighlight lang="php">
public function get_recordset_by_timestamp($modifiedfrom = 0) { public function get_recordset_by_timestamp($modifiedfrom = 0) {
     return $this->get_document_recordset($modifiedfrom);      return $this->get_document_recordset($modifiedfrom);
Line 96:
Line 96:
* '''lastindexedtime''': Also related with files, see example below * '''lastindexedtime''': Also related with files, see example below



<code php> <syntaxhighlight lang="php">
public function get_document($record, $options = array) { public function get_document($record, $options = array) {



Line 156:
Line 156:
First declare that the search area is interested in indexing the files attached to its documents. First declare that the search area is interested in indexing the files attached to its documents.



<code php> <syntaxhighlight lang="php">
public function uses_file_indexing() { public function uses_file_indexing() {
     return true;      return true;
Line 165:
Line 165:



This is a simplified example of one of the cases we can find in core. This is a simplified example of one of the cases we can find in core.
<code php> <syntaxhighlight lang="php">
public function attach_files($document) { public function attach_files($document) {
     $fs = get_file_storage();      $fs = get_file_storage();
Line 192:
Line 192:
You need to specify to what context (or contexts) your search area contents belong to. Overwrite '''$levels''' static attribute in your class. You need to specify to what context (or contexts) your search area contents belong to. Overwrite '''$levels''' static attribute in your class.



<code php> <syntaxhighlight lang="php">
protected static $levels = [CONTEXT_COURSE] protected static $levels = [CONTEXT_COURSE]
</code> </code>
Line 200:
Line 200:
Your search area is the responsible to filter out the results that   Your search area is the responsible to filter out the results that  



<code php> <syntaxhighlight lang="php">
public function check_access($id) { public function check_access($id) {
     try {      try {
Line 226:
Line 226:
The link to the result. Should return a \moodle_url object. The link to the result. Should return a \moodle_url object.



<code php> <syntaxhighlight lang="php">
public function get_doc_url(\core_search\document $doc) { public function get_doc_url(\core_search\document $doc) {
     // This is just an example, can vary a lot depending on what are you indexing.      // This is just an example, can vary a lot depending on what are you indexing.
Line 235:
Line 235:
The link to the result context, in some cases it might be the same than the doc url. Should return a \moodle_url object. The link to the result context, in some cases it might be the same than the doc url. Should return a \moodle_url object.



<code php> <syntaxhighlight lang="php">
public function get_context_url(\core_search\document $doc) { public function get_context_url(\core_search\document $doc) {
     // This is just an example, can vary a lot depending on what are you indexing.      // This is just an example, can vary a lot depending on what are you indexing.
Line 256:
Line 256:
This example code will search the system for 'frogs' and store the results in an array called $results. This example code will search the system for 'frogs' and store the results in an array called $results.



<code php> <syntaxhighlight lang="php">
require_login(); require_login();
$search = \core_search\manager::instance(); $search = \core_search\manager::instance();



Quen: /* Carry out a search */ Documentation for using the search API to make and display a search
2018-08-13T17:00:20Z
Carry out a search:  Documentation for using the search API to make and display a search

				
				
				
				
				
				← Older revision
				Revision as of 17:00, 13 August 2018
				
Line 246:
Line 246:
Usually you do not need to carry out a search within custom code, because users can search using the standard Moodle global search user interface. However, if you want to build a custom search interface, you might need to call search manually. Usually you do not need to carry out a search within custom code, because users can search using the standard Moodle global search user interface. However, if you want to build a custom search interface, you might need to call search manually.



Carrying out a search involves three steps:



* Get the search manager object.
* Set up an object containing options about the query.
* Do the search.

=== Simple example ===

This example code will search the system for 'frogs' and store the results in an array called $results.

<code php>
require_login();
$search = \core_search\manager::instance();
$data = (object)['q' => 'frogs'];
$results = $search->search($data);
</code>

Note: You don't need to call require_login immediately before searching, but it must be called somewhere before searching. The search system requires that there is a logged-in user in order to work. It uses this user to decide which search results they are allowed to see.

=== Query options ===

The query object has the following useful options. Except for q, all of the others are optional.

; q : The actual query text
; title : If specified, will only show results where the title matches this value
; areaids : Array of search area id strings (e.g. sdafaasf). If specified, only results from these areas will be returned.
; courseids : Array of course ids. If specified, results will be restricted to these courses.
; contextids : Array of context ids. If specified, results will be restricted to these exact contexts. (Note: The system does not automatically include child contexts. For example, if you only include a course context id here, it will not return results from activities within that course.)
; groupids : Array of group ids. If specified, only results with these group ids will be returned. (Results with no group will not be returned.) Not all search engines support groups - check by calling $search->get_engine()->supports_group_filtering().
; userids : Array of user ids. If specified, only results with these user ids will be returned. Not all search engines support user search - check by calling $search->get_engine()->supports_users().

=== Display ===

See /search/index.php for an example of how to display the results. Specifically:

* Normally you want to display pages of results; in that case you should use the paged_search function instead of the search function shown in the above example.
* You might be able to reuse the search renderer to display your results. 



[[Category:Search]] [[Category:Search]]



Quen: Creating a new section about carrying out a search
2018-08-13T16:39:10Z
Creating a new section about carrying out a search

				
				
				
				
				
				← Older revision
				Revision as of 16:39, 13 August 2018
				
Line 241:
Line 241:
} }
</code> </code>

== Carry out a search ==

Usually you do not need to carry out a search within custom code, because users can search using the standard Moodle global search user interface. However, if you want to build a custom search interface, you might need to call search manually.





[[Category:Search]] [[Category:Search]]





Quen: Just tweaked to make it extra clear that the context parameter must be implemented.
2017-12-18T17:26:53Z
Just tweaked to make it extra clear that the context parameter must be implemented.

				
				
				
				
				
				← Older revision
				Revision as of 17:26, 18 December 2017
				
Line 38:
Line 38:
==== get_document_recordset ==== ==== get_document_recordset ====



This function should return a recordset with all the stuff in your component that has been modified on or after '''$modifiedfrom''' timestamp (integer), which is also within the specified context '''$context'''. (If the context is null or the system context, it means to include all content system-wide.) This function should return a recordset with all the stuff in your component that has been modified on or after '''$modifiedfrom''' timestamp (integer), which is also within the specified context '''$context'''. (If the context is null or the system context, it means to include all content system-wide. The function must support these, as well as all other possible contexts.)



You can optionally return null if you know there are no changes without having to do a database query. For example, if you are implementing a function for the glossary module, and the supplied context relates to an HTML block, then you already know it cannot contain any of your content. You can optionally return null if you know there are no changes without having to do a database query. For example, if you are implementing a function for the glossary module, and the supplied context relates to an HTML block, then you already know it cannot contain any of your content.



Quen: Slight edit to explain get_recordset_by_timestamp better
2017-12-12T16:43:46Z
Slight edit to explain get_recordset_by_timestamp better

				
				
				
				
				
				← Older revision
				Revision as of 16:43, 12 December 2017
				
Line 78:
Line 78:
==== get_recordset_by_timestamp (Moodle 3.3 and below) ==== ==== get_recordset_by_timestamp (Moodle 3.3 and below) ====



Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well, add the following: Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well as Moodle 3.4+, add the following additional function:



<code php> <code php>
Line 85:
Line 85:
} }
</code> </code>

Note: Existing code that only has a get_recordset_by_timestamp function will still work in Moodle 3.4+ just as it did in earlier versions, but certain features added in Moodle 3.4+ (most importantly, indexing content from restored courses or activities) will not work properly.



==== get_document ==== ==== get_document ====



Quen: Update documentation to cover MDL-55356 change to search indexing API
2017-12-12T16:39:12Z
Update documentation to cover MDL-55356 change to search indexing API

				
				
				
				
				
				← Older revision
				Revision as of 16:39, 12 December 2017
				
Line 36:
Line 36:
=== Index data === === Index data ===



This function should return a recordset with all the stuff in your component that has been modified since '''$modifiedfrom''' timestamp (integer). ==== get_document_recordset ====
 
This function should return a recordset with all the stuff in your component that has been modified on or after '''$modifiedfrom''' timestamp (integer), which is also within the specified context '''$context'''. (If the context is null or the system context, it means to include all content system-wide.)
 
You can optionally return null if you know there are no changes without having to do a database query. For example, if you are implementing a function for the glossary module, and the supplied context relates to an HTML block, then you already know it cannot contain any of your content.
 
The recordset must return the modified content in order by modified time (oldest first), and this must be the same time set in the document's '''modified''' field (see below). If these values are not consistent or the data is not in order then indexing will not always work correctly (for example it may never finish or it may miss updates).
 
Assuming the table containing the data you are indexing is called xxxxx, the basic principle is to do a query similar to:
 
<code sql>
SELECT x.*
  FROM {xxxxx} x
 WHERE x.timemodified >= ?
ORDER BY x.timemodified ASC
</code>
 
However you will also need to incorporate code to restrict the results based on the context within Moodle. 
 
Here is a full example from the Glossary module (you can find this code in mod/glossary/classes/search/entry.php):



<code php> <code php>
public function get_recordset_by_timestamp($modifiedfrom = 0) { public function get_document_recordset($modifiedfrom = 0, \context $context = null) {
     global $DB;      global $DB;



     // The idea is to include here most (if not all) of the data you will need to index (see get_document below)      list ($contextjoin, $contextparams) = $this->get_context_restriction_sql($context, 'glossary', 'g');
     $sql = "SELECT x.* FROM {xxxxx} WHERE x.timemodified >= ? ORDER BY x.timemodified ASC";     if ($contextjoin === null) {
        return null;
    }
 
     $sql = "SELECT ge.*, g.course FROM {glossary_entries} ge
              JOIN {glossary} g ON g.id = ge.glossaryid
      $contextjoin
             WHERE ge.timemodified >= ? ORDER BY ge.timemodified ASC";
    return $DB->get_recordset_sql($sql, array_merge($contextparams, [$modifiedfrom]));
}
</code>
 
Note the helper function '''get_context_restriction_sql''' is available for content within modules (there is a slightly different one for blocks). If you have an unusual case where the data being indexed is not within a module or block, you may need to write the context restriction SQL yourself.
 
==== get_recordset_by_timestamp (Moodle 3.3 and below) ====
 
Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well, add the following:



    // Note that this is an example, you might have more params. <code php>
     return $DB->get_recordset_sql($sql, array($modifiedfrom); public function get_recordset_by_timestamp($modifiedfrom = 0) {
     return $this->get_document_recordset($modifiedfrom);
} }
</code> </code>

==== get_document ====



This function receives one of the previous query results ($record) and an array of options. It should return a '''\core_search\document''' object with all the data to be indexed. This function receives one of the previous query results ($record) and an array of options. It should return a '''\core_search\document''' object with all the data to be indexed.
Line 109:
Line 147:
} }
</code> </code>

As noted above, the '''modified''' field here must be consistent with the ordering and >= condition in the get_document_recordset function.



==== Indexing files ==== ==== Indexing files ====



Quen: Slight tweak to block search limitations
2017-11-14T17:56:01Z
Slight tweak to block search limitations

				
				
				
				
				
				← Older revision
				Revision as of 17:56, 14 November 2017
				
Line 22:
Line 22:
* '''\core_search\base_mod (\core_search\area\base_mod in Moodle 3.1)''': Base class for activities search areas ([[Activity_modules]]) * '''\core_search\base_mod (\core_search\area\base_mod in Moodle 3.1)''': Base class for activities search areas ([[Activity_modules]])
* '''\core_search\base_activity (\core_search\area\base_activity in Moodle 3.1)''': Base class also for activities, but more specific than '''base_mod''' as it is intended to be used to index Moodle activities basic data like the activity name and description. For other specific activity data to be indexed use '''base_mod'''. If you have doubts and you don't know which one you should use think of forum activities and forum posts, forum activities should use '''base_activity''', but forum posts should use '''base_mod'''. * '''\core_search\base_activity (\core_search\area\base_activity in Moodle 3.1)''': Base class also for activities, but more specific than '''base_mod''' as it is intended to be used to index Moodle activities basic data like the activity name and description. For other specific activity data to be indexed use '''base_mod'''. If you have doubts and you don't know which one you should use think of forum activities and forum posts, forum activities should use '''base_activity''', but forum posts should use '''base_mod'''.
* '''\core_search\base_block (Available in Moodle 3.4+)''': Base class for block search areas ([[Blocks]]). Only blocks displayed on some areas of the site are supported for indexing. This is based on the 'pagetypepattern' of the block_instance. Supported page types are as follows: * '''\core_search\base_block (Available in Moodle 3.4+)''': Base class for block search areas ([[Blocks]]). Only blocks located on course pages and the site home page are supported for indexing. This is based on the 'pagetypepattern' of the block_instance. Supported page types are as follows:
** Blocks on the site home page (pagetypepattern = 'site-index') ** Blocks on the site home page (pagetypepattern = 'site-index')
** Blocks on a course home page (pagetypepattern = 'course-view-*') ** Blocks on a course home page (pagetypepattern = 'course-view-*')
** Blocks on any course page (pagetypepattern = 'course-*') ** Blocks on any course page (pagetypepattern = 'course-*')
** Blocks on any page (pagetypepattern = '*') ** Blocks on any page (pagetypepattern = '*'), where they are located at a course context
: Note: Indexing is not supported for blocks configured for course-module-level display. : Note: Indexing is not supported for blocks configured for course-module-level display.






Jaked: /* Base class */
2017-11-14T06:54:49Z
Base class

				
				
				
				
				
				← Older revision
				Revision as of 06:54, 14 November 2017
				
Line 29:
Line 29:
: Note: Indexing is not supported for blocks configured for course-module-level display. : Note: Indexing is not supported for blocks configured for course-module-level display.



: '''\core_search\base_block''' includes a default implementation for '''get_document_recordset''' which is suitable for blocks storing their data in the '''block_instances''' table. Blocks of this nature only need implement the '''get_document''' function to return the document. Blocks storing their data in other tables will need to override the '''get_document_recordset''' function. : '''\core_search\base_block''' includes a default implementation for '''get_document_recordset''' which is suitable for blocks storing their data in the '''block_instances''' table. Blocks of this nature only need implement the '''get_document''' function to return the document. Blocks storing their data in other tables will need to override the '''get_document_recordset''' function. See '''blocks/html/classes/search/content.php''' for an example of a 'standard' block indexing implementation.



=== Name === === Name ===

← Older revision		Revision as of 08:09, 15 July 2021
Line 46:		Line 46:
	Assuming the table containing the data you are indexing is called xxxxx, the basic principle is to do a query similar to:		Assuming the table containing the data you are indexing is called xxxxx, the basic principle is to do a query similar to:

	<~~code~~ sql>		<syntaxhighlight lang="sql">
	SELECT x.*		SELECT x.*
	FROM {xxxxx} x		FROM {xxxxx} x

← Older revision		Revision as of 13:28, 14 July 2021
Line 57:		Line 57:
	Here is a full example from the Glossary module (you can find this code in mod/glossary/classes/search/entry.php):		Here is a full example from the Glossary module (you can find this code in mod/glossary/classes/search/entry.php):

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function get_document_recordset($modifiedfrom = 0, \context $context = null) {		public function get_document_recordset($modifiedfrom = 0, \context $context = null) {
	global $DB;		global $DB;
Line 80:		Line 80:
	Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well as Moodle 3.4+, add the following additional function:		Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well as Moodle 3.4+, add the following additional function:

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function get_recordset_by_timestamp($modifiedfrom = 0) {		public function get_recordset_by_timestamp($modifiedfrom = 0) {
	return $this->get_document_recordset($modifiedfrom);		return $this->get_document_recordset($modifiedfrom);
Line 96:		Line 96:
	* '''lastindexedtime''': Also related with files, see example below		* '''lastindexedtime''': Also related with files, see example below

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function get_document($record, $options = array) {		public function get_document($record, $options = array) {

Line 156:		Line 156:
	First declare that the search area is interested in indexing the files attached to its documents.		First declare that the search area is interested in indexing the files attached to its documents.

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function uses_file_indexing() {		public function uses_file_indexing() {
	return true;		return true;
Line 165:		Line 165:

	This is a simplified example of one of the cases we can find in core.		This is a simplified example of one of the cases we can find in core.
	<~~code~~ php>		<syntaxhighlight lang="php">
	public function attach_files($document) {		public function attach_files($document) {
	$fs = get_file_storage();		$fs = get_file_storage();
Line 192:		Line 192:
	You need to specify to what context (or contexts) your search area contents belong to. Overwrite '''$levels''' static attribute in your class.		You need to specify to what context (or contexts) your search area contents belong to. Overwrite '''$levels''' static attribute in your class.

	<~~code~~ php>		<syntaxhighlight lang="php">
	protected static $levels = [CONTEXT_COURSE]		protected static $levels = [CONTEXT_COURSE]
	</code>		</code>
Line 200:		Line 200:
	Your search area is the responsible to filter out the results that		Your search area is the responsible to filter out the results that

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function check_access($id) {		public function check_access($id) {
	try {		try {
Line 226:		Line 226:
	The link to the result. Should return a \moodle_url object.		The link to the result. Should return a \moodle_url object.

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function get_doc_url(\core_search\document $doc) {		public function get_doc_url(\core_search\document $doc) {
	// This is just an example, can vary a lot depending on what are you indexing.		// This is just an example, can vary a lot depending on what are you indexing.
Line 235:		Line 235:
	The link to the result context, in some cases it might be the same than the doc url. Should return a \moodle_url object.		The link to the result context, in some cases it might be the same than the doc url. Should return a \moodle_url object.

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function get_context_url(\core_search\document $doc) {		public function get_context_url(\core_search\document $doc) {
	// This is just an example, can vary a lot depending on what are you indexing.		// This is just an example, can vary a lot depending on what are you indexing.
Line 256:		Line 256:
	This example code will search the system for 'frogs' and store the results in an array called $results.		This example code will search the system for 'frogs' and store the results in an array called $results.

	<~~code~~ php>		<syntaxhighlight lang="php">
	require_login();		require_login();
	$search = \core_search\manager::instance();		$search = \core_search\manager::instance();

← Older revision		Revision as of 17:00, 13 August 2018
Line 246:		Line 246:
	Usually you do not need to carry out a search within custom code, because users can search using the standard Moodle global search user interface. However, if you want to build a custom search interface, you might need to call search manually.		Usually you do not need to carry out a search within custom code, because users can search using the standard Moodle global search user interface. However, if you want to build a custom search interface, you might need to call search manually.

			Carrying out a search involves three steps:

			* Get the search manager object.
			* Set up an object containing options about the query.
			* Do the search.

			=== Simple example ===

			This example code will search the system for 'frogs' and store the results in an array called $results.

			<code php>
			require_login();
			$search = \core_search\manager::instance();
			$data = (object)['q' => 'frogs'];
			$results = $search->search($data);
			</code>

			Note: You don't need to call require_login immediately before searching, but it must be called somewhere before searching. The search system requires that there is a logged-in user in order to work. It uses this user to decide which search results they are allowed to see.

			=== Query options ===

			The query object has the following useful options. Except for q, all of the others are optional.

			; q : The actual query text
			; title : If specified, will only show results where the title matches this value
			; areaids : Array of search area id strings (e.g. sdafaasf). If specified, only results from these areas will be returned.
			; courseids : Array of course ids. If specified, results will be restricted to these courses.
			; contextids : Array of context ids. If specified, results will be restricted to these exact contexts. (Note: The system does not automatically include child contexts. For example, if you only include a course context id here, it will not return results from activities within that course.)
			; groupids : Array of group ids. If specified, only results with these group ids will be returned. (Results with no group will not be returned.) Not all search engines support groups - check by calling $search->get_engine()->supports_group_filtering().
			; userids : Array of user ids. If specified, only results with these user ids will be returned. Not all search engines support user search - check by calling $search->get_engine()->supports_users().

			=== Display ===

			See /search/index.php for an example of how to display the results. Specifically:

			* Normally you want to display pages of results; in that case you should use the paged_search function instead of the search function shown in the above example.
			* You might be able to reuse the search renderer to display your results.

	[[Category:Search]]		[[Category:Search]]

← Older revision		Revision as of 16:39, 13 August 2018
Line 241:		Line 241:
	}		}
	</code>		</code>

			== Carry out a search ==

			Usually you do not need to carry out a search within custom code, because users can search using the standard Moodle global search user interface. However, if you want to build a custom search interface, you might need to call search manually.



	[[Category:Search]]		[[Category:Search]]

← Older revision		Revision as of 17:26, 18 December 2017
Line 38:		Line 38:
	==== get_document_recordset ====		==== get_document_recordset ====

	This function should return a recordset with all the stuff in your component that has been modified on or after '''$modifiedfrom''' timestamp (integer), which is also within the specified context '''$context'''. (If the context is null or the system context, it means to include all content system-wide.)		This function should return a recordset with all the stuff in your component that has been modified on or after '''$modifiedfrom''' timestamp (integer), which is also within the specified context '''$context'''. (If the context is null or the system context, it means to include all content system-wide. The function must support these, as well as all other possible contexts.)

	You can optionally return null if you know there are no changes without having to do a database query. For example, if you are implementing a function for the glossary module, and the supplied context relates to an HTML block, then you already know it cannot contain any of your content.		You can optionally return null if you know there are no changes without having to do a database query. For example, if you are implementing a function for the glossary module, and the supplied context relates to an HTML block, then you already know it cannot contain any of your content.

← Older revision		Revision as of 16:43, 12 December 2017
Line 78:		Line 78:
	==== get_recordset_by_timestamp (Moodle 3.3 and below) ====		==== get_recordset_by_timestamp (Moodle 3.3 and below) ====

	Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well, add the following:		Moodle 3.3 and below use a different function to do the same job. The function does the same job, but doesn't support the context parameter. If you want your code to support Moodle 3.3 as well as Moodle 3.4+, add the following additional function:

	<code php>		<code php>
Line 85:		Line 85:
	}		}
	</code>		</code>

			Note: Existing code that only has a get_recordset_by_timestamp function will still work in Moodle 3.4+ just as it did in earlier versions, but certain features added in Moodle 3.4+ (most importantly, indexing content from restored courses or activities) will not work properly.

	==== get_document ====		==== get_document ====

← Older revision		Revision as of 17:56, 14 November 2017
Line 22:		Line 22:
	* '''\core_search\base_mod (\core_search\area\base_mod in Moodle 3.1)''': Base class for activities search areas ([[Activity_modules]])		* '''\core_search\base_mod (\core_search\area\base_mod in Moodle 3.1)''': Base class for activities search areas ([[Activity_modules]])
	* '''\core_search\base_activity (\core_search\area\base_activity in Moodle 3.1)''': Base class also for activities, but more specific than '''base_mod''' as it is intended to be used to index Moodle activities basic data like the activity name and description. For other specific activity data to be indexed use '''base_mod'''. If you have doubts and you don't know which one you should use think of forum activities and forum posts, forum activities should use '''base_activity''', but forum posts should use '''base_mod'''.		* '''\core_search\base_activity (\core_search\area\base_activity in Moodle 3.1)''': Base class also for activities, but more specific than '''base_mod''' as it is intended to be used to index Moodle activities basic data like the activity name and description. For other specific activity data to be indexed use '''base_mod'''. If you have doubts and you don't know which one you should use think of forum activities and forum posts, forum activities should use '''base_activity''', but forum posts should use '''base_mod'''.
	* '''\core_search\base_block (Available in Moodle 3.4+)''': Base class for block search areas ([[Blocks]]). Only blocks ~~displayed~~ on ~~some areas of~~ the site are supported for indexing. This is based on the 'pagetypepattern' of the block_instance. Supported page types are as follows:		* '''\core_search\base_block (Available in Moodle 3.4+)''': Base class for block search areas ([[Blocks]]). Only blocks located on course pages and the site home page are supported for indexing. This is based on the 'pagetypepattern' of the block_instance. Supported page types are as follows:
	** Blocks on the site home page (pagetypepattern = 'site-index')		** Blocks on the site home page (pagetypepattern = 'site-index')
	** Blocks on a course home page (pagetypepattern = 'course-view-*')		** Blocks on a course home page (pagetypepattern = 'course-view-*')
	** Blocks on any course page (pagetypepattern = 'course-*')		** Blocks on any course page (pagetypepattern = 'course-*')
	** Blocks on any page (pagetypepattern = '*')		** Blocks on any page (pagetypepattern = '*'), where they are located at a course context
	: Note: Indexing is not supported for blocks configured for course-module-level display.		: Note: Indexing is not supported for blocks configured for course-module-level display.

← Older revision		Revision as of 06:54, 14 November 2017
Line 29:		Line 29:
	: Note: Indexing is not supported for blocks configured for course-module-level display.		: Note: Indexing is not supported for blocks configured for course-module-level display.

	: '''\core_search\base_block''' includes a default implementation for '''get_document_recordset''' which is suitable for blocks storing their data in the '''block_instances''' table. Blocks of this nature only need implement the '''get_document''' function to return the document. Blocks storing their data in other tables will need to override the '''get_document_recordset''' function.		: '''\core_search\base_block''' includes a default implementation for '''get_document_recordset''' which is suitable for blocks storing their data in the '''block_instances''' table. Blocks of this nature only need implement the '''get_document''' function to return the document. Blocks storing their data in other tables will need to override the '''get_document_recordset''' function. See '''blocks/html/classes/search/content.php''' for an example of a 'standard' block indexing implementation.

	=== Name ===		=== Name ===

Search API - Revision history

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Quen: /* Carry out a search */ Documentation for using the search API to make and display a search

Quen: Creating a new section about carrying out a search

Quen: Just tweaked to make it extra clear that the context parameter must be implemented.

Quen: Slight edit to explain get_recordset_by_timestamp better

Quen: Update documentation to cover MDL-55356 change to search indexing API

Quen: Slight tweak to block search limitations

Jaked: /* Base class */

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""

Mudrd8mz: Text replacement - "`" to ""`