Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 401 and 403]

Document representation.

Copyright: 2015 David Monllao {@link http://www.davidmonllao.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 688 lines (23 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class


Class: document  - X-Ref

Represents a document to index.

Note that, if you are writting a search engine and you want to change \core_search\document
behaviour, you can overwrite this class, will be automatically loaded from \search_YOURENGINE\document.

__construct($itemid, $componentname, $areaname)   X-Ref
We ensure that the document has a unique id across search areas.

param: int $itemid An id unique to the search area
param: string $componentname The search area component Frankenstyle name
param: string $areaname The area name (the search area class name)
return: void

add_stored_file($file)   X-Ref
Add a stored file to the document.

param: \stored_file|int $file The file to add, or file id.
return: void

get_files()   X-Ref
Returns the array of attached files.

return: \stored_file[]

set($fieldname, $value)   X-Ref
Setter.

Basic checkings to prevent common issues.

If the field is a string tags will be stripped, if it is an integer or a date it
will be casted to a PHP integer. tdate fields values are expected to be timestamps.

param: string $fieldname The field name
param: string|int $value The value to store
return: string|int The stored value

set_extra($fieldname, $value)   X-Ref
Sets data to this->extradata

This data can be retrieved using \core_search\document->get($fieldname).

param: string $fieldname
param: string $value
return: void

get($field)   X-Ref
Getter.

Use self::is_set if you are not sure if this field is set or not
as otherwise it will trigger a \coding_exception

param: string $field
return: string|int

is_set($field)   X-Ref
Checks if a field is set.

param: string $field
return: bool

set_is_new($new)   X-Ref
Set if this is a new document. False if unknown.

param: bool $new

get_is_new()   X-Ref
Returns if the document is new. False if unknown.

return: bool

get_default_fields_definition()   X-Ref
Returns all default fields definitions.

return: array

format_time_for_engine($timestamp)   X-Ref
Formats the timestamp preparing the time fields to be inserted into the search engine.

By default it just returns a timestamp so any search engine could just store integers
and use integers comparison to get documents between x and y timestamps, but search
engines might be interested in using their own field formats. They can do it extending
this class in \search_xxx\document.

param: int $timestamp
return: string

format_string_for_engine($string)   X-Ref
Formats a string value for the search engine.

Search engines may overwrite this method to apply restrictions, like limiting the size.
The default behaviour is just returning the string.

param: string $string
return: string

format_text_for_engine($text)   X-Ref
Formats a text value for the search engine.

Search engines may overwrite this method to apply restrictions, like limiting the size.
The default behaviour is just returning the string.

param: string $text
return: string

import_time_from_engine($time)   X-Ref
Returns a timestamp from the value stored in the search engine.

By default it just returns a timestamp so any search engine could just store integers
and use integers comparison to get documents between x and y timestamps, but search
engines might be interested in using their own field formats. They should do it extending
this class in \search_xxx\document.

param: string $time
return: int

get_text_format()   X-Ref
Returns how text is returned from the search engine.

return: int

set_data_from_engine($docdata)   X-Ref
Fills the document with data coming from the search engine.

param: array $docdata
return: void

set_doc_url(\moodle_url $url)   X-Ref
Sets the document url.

param: \moodle_url $url
return: void

get_doc_url()   X-Ref
Gets the url to the doc.

return: \moodle_url

set_doc_icon(document_icon $docicon)   X-Ref
Sets document icon instance.

param: \core_search\document_icon $docicon

get_doc_icon()   X-Ref
Gets document icon instance.

return: \core_search\document_icon

set_context_url(\moodle_url $url)   X-Ref
No description

get_context_url()   X-Ref
Gets the url to the context.

return: \moodle_url

export_for_engine()   X-Ref
Returns the document ready to submit to the search engine.

return: array

apply_defaults()   X-Ref
Apply any defaults to unset fields before export. Called after document building, but before export.

Sub-classes of this should make sure to call parent::apply_defaults().

export_for_template(\renderer_base $output)   X-Ref
Export the document data to be used as a template context.

Adding more info than the required one as people might be interested in extending the template.

Although content is a required field when setting up the document, it accepts '' (empty) values
as they may be the result of striping out HTML.

SECURITY NOTE: It is the responsibility of the document to properly escape any text to be displayed.
The renderer will output the content without any further cleaning.

param: renderer_base $output The renderer.
return: array

format_text($text)   X-Ref
Formats a text string coming from the search engine.

By default just return the text as it is:
- Search areas are responsible of sending just plain data, the search engine may
append HTML or markdown to it (highlighing for example).
- The view is responsible of shortening the text if it is too big

param: string $text Text to format
return: string HTML text to be renderer