Download the PHP package teppokoivula/search-engine without Composer

SearchEngine ProcessWire module

SearchEngine is a module that creates an index of page contents, and makes it easy to search.

Usage

1) Install the SearchEngine module.

The module will automatically create an index field during installation, so you should define a custom field (via site config) before installing if you don't want it to be called "search_index". You can change the field name later as well, but you'll have to update the "index_field" option in site config or module settings (in Admin) after renaming the field.

2) Add the index field to templates you want to make searchable.

You can add the index field to templates via template settings, field settings (the "Actions" tab), or via the "indexed templates" setting found from the config screen of the SearchEngine module. After the field has been added to a template, every time a page using that template is saved, content from indexable fields will be automatically stored into the (typically hidden) index field.

3) Use selectors to query values in site search index or add appropriate render calls to your template file(s).

There are three ways to use SearchEngine, so you'll want to choose the one that fits your workflow best:

• You can query the search_index field (or whatever you decided to name it earlier) just like any other textarea field in ProcessWire. This allows you to build completely customized search feature on your site, while SearchEngine takes care of indexing content.
• You can use SearchEngine to find results by calling $modules->get('SearchEngine')->find($input->get->q). Obviously you can pass any search string to the find method, we're using the "q" GET param here just as an example.
• You can let SearchEngine handle the whole search feature by adding a render call to your search page's template file: $modules->get('SearchEngine')->render(). The render() method is a shortcut for calling multiple methods behind the scenes, but you can also omit that and instead call renderStyles(), renderScripts(), renderResults(), and renderForm() separately.

If you prefer letting SearchEngine handle all the markup for you, the simple approach only involves one method call:

You can pass an array to render(), rendering only specific features. Here's an example of rendering just the form and results list while omitting styles and/or scripts:

Finally, here's how you could render all parts separately – this approach involves some additional steps, but provides more control over the rendered output than other methods:

Multilanguage use (language support)

SearchEngine supports indexing multilingual content. Once ProcessWire's native multilanguage features are enabled, support for multilanguage indexing can be enabled by converting the index field to FieldtypeTextareaLanguage.

Advanced use

If you render the results list with one of the methods mentioned earlier, SearchEngine will automatically look for the query param defined in its settings – and if this param is found (GET), it will perform a search query for you. If you don't want the module to handle this part for you, you can also perform the query yourself (or just don't render the results list).

You can access the search index field just like any other ProcessWire field with selectors:

Note: while you can use any operator for your selectors, you will likely find the `=and%=operators most useful while querying the index. You can read more about selector operators from [ProcessWire's documentation on selectors](https://processwire.com/docs/selectors/). By default this module will use the=` operator for built-in features.

Alternatively you can delegate the find operation to the SearchEngine module:

JSON output

The Renderer class provides support for returning search results as a JSON string, which can be particularly useful for implementing AJAX search features. JSON output is returned by the Renderer::renderResultsJSON() method, and you can customise returned keys and values via results_json_fields configuration option.

The results_json_fields is an array of keys and field names. There are two "special" field name prefixes – template. and parent. – which provide access to template and parent page properties.

Here's an example of how you might use the renderResultsJSON() method in your own code:

... which, for an example, might result in following output:

Note that a returned field value (for a specific search result) may be an empty string, but it may also be null. Null return values occur, for an example, if you've specified a field that doesn't exist for that particular page.

Rebuilding the search index

If you want to rebuild (recreate) the search index for all pages or pages matching a specific selector, you can do that via the Admin GUI (module configuration screen), or you can perform following request via the API:

Options

By default the module will create a search index field called 'search_index' and store values from Page fields title, headline, summary, and body to said index field when a page is saved. You can modify the default behaviour via the Module config screen in the PocessWire Admin, or by defining $config->SearchEngine array in your site config file or other applicable location.

Below you'll find a summary of available options. Note that this is not a comprehensive list – please check the $defaultOptions array near the beginning of the SearchEngine.module.php file for a list with all available options. Some options can be modified via the admin (module config screen), while all options can be defined via code – and if you define an option via site config, it can't be overridden via admin.

You can also pass custom options to certain method calls. Most render-prefixed methods, for an example, accept an array of custom render arguments (see "render_args" in the list below) so that you can optionally override module and site defaults on a case-by-case basis.

Automatically generating search result descriptions (summaries)

As of version 0.24.0, SearchEngine has the capability to automatically generate descriptions for search results. You can trigger this behaviour by specifying _auto_desc as the name of the desc key. Note, though, that this comes with some notable caveats:

• Before enabling this feature, you need to be absolutely certain that everything you're indexing can also be publicly displayed. When SearchEngine generates the description automatically, it doesn't know which parts of the index are intended to be displayed publicly, and which parts might've been added to the index just to make them searchable.
• Automatically generated descriptions may, at least for the time being, contain data from multiple fields. This means that such snippets may not be entirely logical (and they very likely won't be complete sentences etc.)

Themes

SearchEngine supports the concept of themes. Themes are located in the themes directory, under their own subdirectories (e.g. /themes/theme-name/), and each of them needs to include (at the very least) a config file (/themes/theme-name/config.php). Here's an example of a theme config file:

A theme may include style and script file(s), in which case there should also be a type-specific directory to store them in (i.e. /themes/theme-name/scripts/ or /themes/theme-name/styles/). For each file there should be both the "source" file named in the theme_styles or theme_scripts array (e.g style.css) and a minified version with ".min" in its name (e.g. style.min.css).

Note: modifying files within the module directory is not recommended, since they may get overwritten in an update. You can configure the path for your custom themes via the "Advanced" section of the SearchEngine module config screen.

Requirements

• ProcessWire >= 3.0.112
• PHP >= 7.1.0

Installing

This module can be installed – just like any other ProcessWire module – by downloading or cloning the SearchEngine directory into your /site/modules/ directory. Alternatively you can install SearchEngine with Composer by running composer require teppokoivula/search-engine.

Development

SearchEngine core JS files are bundled with parcel.js and theme styles are minified with clean-css. Both of these require minimal configuration, which is why all that is needed is the "build" script defined in package.json. To build production assets for SearchEngine:

• Install Parcel globally: npm install -g parcel-bundler
• Install clean-css and clean-css-cli globally: npm install -g clean-css && npm install -g clean-css-cli
• Run build script in the SearchEngine module directory: npm run build

License

This project is licensed under the Mozilla Public License Version 2.0.