asconsulting/contao-zyppy-search

Live page search for Contao 5. A visitor types into the search box and the results appear underneath as they type, without a page reload — each one with the page's image and teaser from Zyppy Page alongside the usual highlighted excerpt. A page flagged as a news reader shows the matching news article's teaser and image instead.

Underneath it is Contao's own site search: the same tl_search index, the same query options and the same per-visitor access rules. What this bundle adds is the live transport and the richer result.

Requirements

Installation

composer require asconsulting/contao-zyppy-search:^5.0

Then run the database migration. Contao Manager does this on install and on update; on the command line it is vendor/bin/contao-console contao:migrate. It adds the module settings to tl_module and the News Reader flag to tl_page.

The module searches Contao's search index; it does not build it. Index the site as usual (crawl it, or let the front end indexer run) before expecting results.

Usage

Creating the module

Under Themes → Front end modules, create a module of type Zyppy Search (in the Applications group) and place it on a page like any other module. Its settings are the ones Contao's own search module has, plus three formatting options:

Setting Effect
Query type (queryType), fuzzy search (fuzzy), context range (contextLength), minimum keyword length (minKeywordLength), items per page (perPage) As in Contao's search module. The minimum keyword length also decides how many characters the visitor has to type before the live search fires (3 if unset).
Form layout (searchType) Advanced adds the "match all / match any" choice to the form; the live search honours it too.
Reference pages (pages) Restricts the search to these pages and their subtrees. Left empty, the module searches the whole site the request host resolves to.
Redirect page (jumpTo) The page the form submits to when JavaScript is off. Left empty, the form submits back to its own page.
Search template (searchTpl) The template for one result. search_zyppy by default.
Image size (imgSize) The image size used for the result image.
Format Page Teaser / Page Teaser Limit Strip tags from the page teaser and optionally cut it to this many characters (0 for unlimited).
Format Page Description / Page Description Limit The same for the page's meta description.
Format News Teaser / News Teaser Limit The same for the news teaser used by the News Reader override.
Clear on Popup (popupClear) Only present with contao-zyppy-popup installed: empties the results when a pop-up opens.

What the visitor gets

The News Reader override

On a news reader page, tick News Reader (zyppy_news) in the page's Meta legend; the box is offered on regular pages only. When a result points at a news article under that page, the article's teaser and image replace the page's own. Only published articles inside their publication window are used. Requires contao/news-bundle.

The live endpoint

The script calls GET /_zyppy/search/{moduleId} with keywords, an optional query_type (and or or) and an optional page, and receives JSON: the result window (count, from, to, page, totalPages) plus one html string that is dropped into the results area as is.

Templates

Template Role
zyppy_search (frontend_module/zyppy_search) The module shell: form and results area. The module's default template.
search_zyppy One result. Selectable per module through Search template, which is the one an editor has a reason to swap.
search_zyppy_results Everything inside the results area: header, keyword hint, the result rows, pager. Not selectable in the back end; override it by shipping a project template of the same name.
mod_search_zyppy The legacy shell, used only when it is picked as a module's Custom template. Kept so sites that chose it keep rendering.

The wrapper class mod_zyppy_search is load bearing: the script selects it, and contao-zyppy-popup relies on it for Clear on Popup. The script is published at bundles/search/js/search.js and is emitted by the module template itself, so nothing has to be added to the page layout.

Migration from legacy version

This package replaces the legacy package asconsulting/zyppy_search (namespace ZyppySearch\). The old name does not resolve any more.

The four legacy Zyppy packages — page, classes, popup and search — have to be upgraded together, in one composer update: old and new packages register the same DCA fields and module types, so a site that briefly has both installed double-registers. The walkthrough for the whole suite, including the order of operations and a verification checklist, is UPGRADING.md in the contao-zyppy-page repository. The part specific to this package:

Development

composer install
vendor/bin/phpunit --no-coverage

Two things to know before changing the code:

TODO.md carries the original audit, the modernization steps and what has been verified where.

Licence

Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE. Copyright Andrew Stevens.

Downloads

VersionReleasedFile
5.0.1contao-zyppy-search-5.0.1.zip 125 KB
5.0.0contao-zyppy-search-5.0.0.zip 125 KB