IFullTextSearchProvider
Interface IFullTextSearchProvider
This interface must be use when creating a Content Provider for FullTextSearch.
A Content Provider is an extension to the FullTextSearch that will extract and provide content to the FullTextSearch.
There is no limit to the number of Content Provider that can be integrated to FullTextSearch. Each Content Provider corresponding to a type of content available in Nextcloud (files, bookmarks, notes, deck cards, mails, ...)
Content is split in document identified by an ID and the ID of the Content Provider. The content is indexed by a Search Platform that will returns a documentId as a result on a search request.
To oversimplify the mechanism:
- When indexing, FullTextSearch will ask for documents to every Content Provider.
- On search, results from the Search Platform, identified by documentId, will be improved by each relative Content Provider.
The Content Provider is a PHP class that implement this interface and is defined in appinfo/info.xml of the app that contains that class:
<fulltextsearch> <provider>OCA\YourApp\YourContentProvider</provider> </fulltextsearch>
Multiple Content Provider can be defined in a single app.
Tags
Table of Contents
- fillIndexDocument() : mixed
- Must fill IIndexDocument with all information relative to the document, before its indexing by the Search Platform.
- generateChunks() : string[]
- Allow the provider to generate a list of chunk to split a huge list of indexable documents
- generateIndexableDocuments() : \OCP\FullTextSearch\Model\IIndexDocument[]
- Returns all indexable document for a user as an array of IIndexDocument.
- getConfiguration() : array
- Should returns the current configuration of the Content Provider.
- getId() : string
- Must returns a unique Id used to identify the Content Provider.
- getName() : string
- Must returns a descriptive name of the Content Provider.
- getSearchTemplate() : ISearchTemplate
- Must returns a ISearchTemplate that contains displayable items and available options to users when searching.
- improveSearchRequest() : mixed
- Method is called when a search request is initiated by a user, prior to be sent to the Search Platform.
- improveSearchResult() : mixed
- Method is called after results of a search are returned by the Search Platform.
- isDocumentUpToDate() : bool
- Called to verify that the document is not already indexed and that the old index is not up-to-date, using the IIndex from IIndexDocument->getIndex()
- loadProvider() : mixed
- Called when FullTextSearch is loading your Content Provider.
- onInitializingIndex() : mixed
- Called when an index is initiated by the administrator.
- onResettingIndex() : mixed
- Called when administrator is resetting the index.
- setIndexOptions() : mixed
- This method is called when the administrator specify options when running the ./occ fulltextsearch:index or ./occ fulltextsearch:live
- setRunner() : mixed
- Set the wrapper of the currently executed process.
- unloadProvider() : mixed
- not used yet.
- updateDocument() : IIndexDocument
- The Search Provider must create and return an IIndexDocument based on the IIndex and its status. The IIndexDocument must contains all information as it will be send for indexing.
Methods
fillIndexDocument()
Must fill IIndexDocument with all information relative to the document, before its indexing by the Search Platform.
public
fillIndexDocument(IIndexDocument $document) : mixed
Method is called for each element returned previously by generateIndexableDocuments().
Parameters
- $document : IIndexDocument
Tags
Return values
mixed —generateChunks()
Allow the provider to generate a list of chunk to split a huge list of indexable documents
public
generateChunks(string $userId) : string[]
During the indexing the generateIndexableDocuments method will be called for each entry of the returned array. If the returned array is empty, the generateIndexableDocuments() will be called only once (per user).
Parameters
- $userId : string
Tags
Return values
string[] —generateIndexableDocuments()
Returns all indexable document for a user as an array of IIndexDocument.
public
generateIndexableDocuments(string $userId, string $chunk) : \OCP\FullTextSearch\Model\IIndexDocument[]
There is no need to fill each IIndexDocument with content; at this point, only fill the object with the minimum information to not waste memory while still being able to identify the document it is referring to.
FullTextSearch will call 2 other methods of this interface for each IIndexDocument of the array, prior to their indexing:
- first, to compare the date of the last index,
- then, to fill each IIndexDocument with complete data
Parameters
- $userId : string
- $chunk : string
Tags
Return values
\OCP\FullTextSearch\Model\IIndexDocument[] —getConfiguration()
Should returns the current configuration of the Content Provider.
public
getConfiguration() : array
This is used to display the configuration when using the ./occ fulltextsearch:check command line.
Tags
Return values
array —getId()
Must returns a unique Id used to identify the Content Provider.
public
getId() : string
Id must contains only alphanumeric chars, with no space.
Tags
Return values
string —getName()
Must returns a descriptive name of the Content Provider.
public
getName() : string
This is used in multiple places, so better use a clear display name.
Tags
Return values
string —getSearchTemplate()
Must returns a ISearchTemplate that contains displayable items and available options to users when searching.
public
getSearchTemplate() : ISearchTemplate
Tags
Return values
ISearchTemplate —improveSearchRequest()
Method is called when a search request is initiated by a user, prior to be sent to the Search Platform.
public
improveSearchRequest(ISearchRequest $searchRequest) : mixed
Your Content Provider can interact with the ISearchRequest to apply the search options and make the search more precise.
Parameters
- $searchRequest : ISearchRequest
Tags
Return values
mixed —improveSearchResult()
Method is called after results of a search are returned by the Search Platform.
public
improveSearchResult(ISearchResult $searchResult) : mixed
Your Content Provider can detail each entry with local data to improve the display of the search result.
Parameters
- $searchResult : ISearchResult
Tags
Return values
mixed —isDocumentUpToDate()
Called to verify that the document is not already indexed and that the old index is not up-to-date, using the IIndex from IIndexDocument->getIndex()
public
isDocumentUpToDate(IIndexDocument $document) : bool
Returning true will not queue the current IIndexDocument to any further operation and will continue on the next element from the list returned by generateIndexableDocuments().
Parameters
- $document : IIndexDocument
Tags
Return values
bool —loadProvider()
Called when FullTextSearch is loading your Content Provider.
public
loadProvider() : mixed
Tags
Return values
mixed —onInitializingIndex()
Called when an index is initiated by the administrator.
public
onInitializingIndex(IFullTextSearchPlatform $platform) : mixed
This is should only be used in case of a specific mapping is needed. (ie. almost never)
Parameters
- $platform : IFullTextSearchPlatform
Tags
Return values
mixed —onResettingIndex()
Called when administrator is resetting the index.
public
onResettingIndex(IFullTextSearchPlatform $platform) : mixed
This is should only be used in case of a specific mapping has been created.
Parameters
- $platform : IFullTextSearchPlatform
Tags
Return values
mixed —setIndexOptions()
This method is called when the administrator specify options when running the ./occ fulltextsearch:index or ./occ fulltextsearch:live
public
setIndexOptions(IIndexOptions $options) : mixed
Parameters
- $options : IIndexOptions
Tags
Return values
mixed —setRunner()
Set the wrapper of the currently executed process.
public
setRunner(IRunner $runner) : mixed
Because the index process can be long and heavy, and because errors can be encountered during the process, the IRunner is a wrapper that allow the Content Provider to communicate with the process initiated by FullTextSearch.
The IRunner is coming with some methods so the Content Provider can returns important information and errors to be displayed to the admin.
Parameters
- $runner : IRunner
Tags
Return values
mixed —unloadProvider()
not used yet.
public
unloadProvider() : mixed
Tags
Return values
mixed —updateDocument()
The Search Provider must create and return an IIndexDocument based on the IIndex and its status. The IIndexDocument must contains all information as it will be send for indexing.
public
updateDocument(IIndex $index) : IIndexDocument
Method is called during a cron or a ./occ fulltextsearch:live after a new document is created, or an old document is set as modified.
Parameters
- $index : IIndex