README

This module allows configuration of freetext search indexes, and provides tools to create indexes and reindex them. By default only a sitetree index is configured, but one can add indexes for subclasses of SiteTree (e.g. a BlogPost) or a DataObject only index, e.g. flickr photos. The template for rendering the search results can also be overridden.

Note that one also has to install an implementation, currently only one for Manticore Search (formerly Sphinx) exists, package name is suilven/silverstripe-manticore-search

Configuration

Indexes

By default the core fields of SiteTree are indexed. You can override as follows to allow for third party modules or your own. Each index should map to a model class, and the field names match those in the database.

An example follows, code can be found at https://github.com/gordonbanderson/flickr-editor/tree/upgradess4

---
Name: flickrfreetextsearch
After: freetextindexes
---

Suilven\FreeTextSearch\Indexes:
  indexes:

The above is compulsory. Additional indexes start here.

    - index:

The name of the index

        name: flickrphotos

The class of DataObject being indexed

        class: Suilven\Flickr\Model\Flickr\FlickrPhoto

These fields are indexed as free text.

        fields:
          - Title
          - Description

It is not always desirable to show highlights from all of the fields, this is a filter list of fields to render highlights from in search results.

        highlighted_fields:
          - Title
          - Description

These fields are stored but not searchable. Their function is to provide fields to render in the search results, and avoid hydrating objects from the database. Note that Link is a hybrid field, the existence of a Link() method is checked for at indexing time and the field added if the method exists.

        stored_fields:
          - ThumbnailURL
          - Link

The following indexes correctly with Manticoresearch, but note that the ManticoreSearch PHP client does not currently allow for facetted searching. It is in pipeline though. Raw queries show facetted groups returned, but it makes sense to wait for this to be implemented in the PHP client instead.

Fields that can be used for facetted searching.

        tokens:
          - Aperture
          - ShutterSpeed
          - ISO
          - TakenAt

Have one fields are effectively another facet.

        has_one:
          - Suilven\Flickr\Model\Flickr\FlickrAuthor

This example shows how to index a has many field, tags, for facetting. Each entry has 3 fields:

name: the name of the relationship
relationship: The SilverStripe name of the relationship
field: The FlickrTags relationship is a data list of FlickrTag, the value stored is that of the RawValue field.

        has_many:
          -
            name: tags
            relationship: FlickrTags
            field: RawValue

Extensions

Any class referenced in indexes configuration needs the following extension, Suilven\FreeTextSearch\Extension\IndexingExtension, added. This performs one of two jobs:

Index a DataObject immediately after it's been saved
/or mark a DataObject as dirty and add a job to the queue to process the indexes affected.

---
Name: freetextindexes-flickr
After: freetextindexes-extensions
---

Suilven\Flickr\Model\Flickr\FlickrPhoto:
  extensions:
    - Suilven\FreeTextSearch\Extension\IndexingExtension

Indexing Mode

In the site configuration there is an additional tab called Free Text Search. It contains two fields:

FreeTextSearchIndexingModeInBulk - tick this to index in bulk via queue, untick to index immediately after writing to the database
BulkSize - the number of DataObjects to index at once

Install

Via Composer

$ composer require suilven/freetextsearch

Usage

Indexing

Note that these commands require an implementation of freetextsearch.

Creating an Index

Change the name of the index as appropriate. Note that when this command is run, the contents of the index will be dropped, and a reindex will be required.

vendor bin/sake dev/tasks/create-index index=sitetree

Reindexing an Index

Change the name of the index as appropriate. This will reindex in bulk.

vendor bin/sake dev/tasks/reindex index=sitetree

Adding a Search Page for an Index

In the CMS add a page of type Search Page. The following fields are editable:

IndexToSearch - the index to search, e.g. sitetree or flickrphotos
PageSize - the number of search results to return per page

The following are related to facets and not yet implemented:

ShowAllIfEmptyQuery - if this is ticked, search results will be shown for an empty query
ShowTagCloudFor - show tag cloud for a faceted field when there are no search results to be shown

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ vendor/bin/phpunit tests '' flush=1

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email gordon.b.anderson@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

suilven / freetextsearch

Maintainers

Details