PHPackages spanjaan/wn-site-search-plugin - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Search & Filtering](/categories/search) 4. / 5. spanjaan/wn-site-search-plugin ActiveWinter-plugin[Search & Filtering](/categories/search) spanjaan/wn-site-search-plugin ============================== This plugin adds global search capabiliies to WinterCMS. v1.0.3(5mo ago)012MITPHPPHP >=7.0 Since Sep 3Pushed 5mo ago1 watchersCompare [ Source](https://github.com/spanjaan/wn-site-search-plugin)[ Packagist](https://packagist.org/packages/spanjaan/wn-site-search-plugin)[ Docs](https://github.com/spanjaan/wn-site-search-plugin)[ RSS](/packages/spanjaan-wn-site-search-plugin/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (1)Versions (5)Used By (0) Site-Search Plugin for WinterCMS ================================ [](#site-search-plugin-for-wintercms) This plugin adds global search capabilities to WinterCMS. Forked from ----------- [](#forked-from) This plugin is a WinterCMS-compatible fork of the original [OFFLINE.SiteSearch plugin for OctoberCMS](https://github.com/OFFLINE-GmbH/oc-site-search-plugin). It has been adapted to work seamlessly with WinterCMS, preserving the original functionality and adding enhancements specific to the WinterCMS ecosystem. Installation ------------ [](#installation) ``` composer require spanjaan/wn-site-search-plugin ``` Available languages ------------------- [](#available-languages) - English - German - Czech - Russian - Persian (Farsi) - Portuguese You can translate all contents into your own language. Currently supported content types --------------------------------- [](#currently-supported-content-types) - [Winter.Pages](https://github.com/wintercms/wn-pages-plugin) - [Winter.Blog](https://github.com/wintercms/wn-blog-plugin) - Native CMS pages (experimental) Supported but deactivated ------------------------- [](#supported-but-deactivated) These plugins are supported but deactivated by default. You can manually activate them by removing the comments in following files: ``` {PLUGIN ROOT}/models/settings/fields.yaml {PLUGIN ROOT}/classes/SearchService.php ``` - [Indikator.News](https://github.com/gergo85/oc-news) - [Feegleweb.Octoshop](https://octobercms.com/plugin/feegleweb-octoshop) - [Jiri.JKShop](http://octobercms.com/plugin/jiri-jkshop) - [RadiantWeb.ProBlog](https://octobercms.com/plugin/radiantweb-problog) - [Arrizalamin.Portfolio](https://octobercms.com/plugin/arrizalamin-portfolio) - [Responsiv.Showcase](https://octobercms.com/plugin/responsiv-showcase) - [VojtaSvoboda.Brands](https://octobercms.com/plugin/vojtasvoboda-brands) - [Graker.PhotoAlbums](https://octobercms.com/plugin/graker-photoalbums) **Multilingual contents via Winter.Translate are supported.** Support for more plugins is added upon request. **You can easily extend this plugin to search your custom plugin's contents as well. See the documentation for further information.** ### Get native support for your plugin [](#get-native-support-for-your-plugin) If you are a plugin developer and wish to have native support for your contents in SiteSearch please submit a pull request for your search provider. We cannot add support for every plugin but will add any plugin that has a notable project count on the Winter Marketplace. Components ---------- [](#components) ### searchResults [](#searchresults) Place this component on your page to display search results. #### Usage example [](#usage-example) Create a search form that sends a query to your search page: ##### Search form [](#search-form) ``` Search ``` **Important**: Use the `q` parameter to send the user's query. Alternatively you can also use the `searchInput` component described below to generate this form for you. ##### Search results [](#search-results) Create a page to display your search results. Add the `searchResults` component to it. Use the `searchResults.query` parameter to display the user's search query. ``` title = "Search results" url = "/search" layout = "default" [searchResults] resultsPerPage = 10 showProviderBadge = 1 noResultsMessage = "Your search did not return any results." visitPageMessage = "Visit page" == Search results for {{ searchResults.query }} {% component 'searchResults' %} ``` ##### Example css to style the component [](#example-css-to-style-the-component) ``` .ss-result { margin-bottom: 2em; } .ss-result__aside { float: right; margin-left: .5em; } .ss-result__title { font-weight: bold; margin-bottom: .5em; } .ss-result__badge { font-size: .7em; padding: .2em .5em; border-radius: 4px; margin-left: .75em; background: #eee; display: inline-block; } .ss-result__text { margin-bottom: .5em; } .ss-result__url { } ``` #### Modify the query before searching [](#modify-the-query-before-searching) If you want to modify the user's search query before the search is executed you can call the `forceQuery` method on the `searchResults` component from your page's `onStart` method. ``` [searchResults] resultsPerPage = 10 showProviderBadge = 1 noResultsMessage = "Your search returned no results." visitPageMessage = "Visit page" == function onStart() { $query = Request::get('q'); $query = str_replace('ё', 'e', $query); $this->page->components['searchResults']->forceQuery($query); } == {% component 'searchResults' %} ``` #### Change the results collection before displaying [](#change-the-results-collection-before-displaying) You can listen for the `spanjaan.sitesearch.results` event and modify the query as you wish. This is useful to remove certain results or change the sort order. ``` [searchResults] resultsPerPage = 10 showProviderBadge = 1 noResultsMessage = "Your search returned no results." visitPageMessage = "Visit page" == function onInit() { \Event::listen('spanjaan.sitesearch.results', function ($results) { // return $results->filter(...); return $results->sortByDesc('model.custom_attribute'); }); } == {% component 'searchResults' %} ``` #### Properties [](#properties) The following properties are available to change the component's behaviour. ##### resultsPerPage [](#resultsperpage) How many results to display on one page. ##### showProviderBadge [](#showproviderbadge) The search works by querying multiple providers (Pages, Blog, or other). If this option is enabled each search result is marked with a badge to show which provider returned the result. This is useful if your site has many different entities (ex. teams, employees, pages, blog entries). ##### noResultsMessage [](#noresultsmessage) This message is shown if there are no results returned. ##### visitPageMessage [](#visitpagemessage) A link is placed below each search result. Use this property to change that link's text. ### searchInput [](#searchinput) Place this component anywhere you want to display a simple search input with "search as you type" capabilities. #### Usage example [](#usage-example-1) Add the `searchInput` component to any layout, partial or page. ``` title = "Home" url = "/" ... [searchInput] useAutoComplete = 1 autoCompleteResultCount = 5 showProviderBadge = 1 searchPage = "search.htm" == {% component 'searchInput' %} ``` ##### Example css to style the component [](#example-css-to-style-the-component-1) ``` .ss-search-form { position: relative; } .ss-search-form__results { display: none; position: absolute; left: 0; top: 35px; width: 100%; background: #fff; padding: 1em; box-shadow: 0 2px 4px rgba(0, 0, 0, .1); } .ss-search-form__results--visible { display: block; } ``` #### Properties [](#properties-1) The following properties are available to change the component's behaviour. ##### useAutoComplete [](#useautocomplete) If this property is enabled, a search query will be executed as soon as the user begins to type. ##### autoCompleteResultCount [](#autocompleteresultcount) This many results will be displayed to the user below the input field. There will be a "Show all results" link the user can click that takes her to a full search results page if one has been specified via the `searchPage` property. ##### showProviderBadge [](#showproviderbadge-1) The search works by querying multiple providers (Pages, Blog, or other). If this option is enabled each search result is marked with a badge to show which provider returned the result. This is useful if your site has many different entities (ex. teams, employees, pages, blog entries). ##### searchPage [](#searchpage) The filename of the page where you have placed a `searchResults` component. If a user clicks on the "Show all results" link it will take him to this page where a full search is run using the `searchResults` component. Add support for custom plugin contents -------------------------------------- [](#add-support-for-custom-plugin-contents) ### Simple method [](#simple-method) To return search results for you own custom plugin, register an event listener for the `spanjaan.sitesearch.query`event in your plugin's boot method. Return an array containing a `provider` string and `results` array. Each result must provide at least a `title` key. #### Example to search for custom `documents` [](#example-to-search-for-custom-documents) ``` public function boot() { \Event::listen('spanjaan.sitesearch.query', function ($query) { // The controller is used to generate page URLs. $controller = \Cms\Classes\Controller::getController() ?? new \Cms\Classes\Controller(); // Search your plugin's contents $items = YourCustomDocumentModel ::where('title', 'like', "%${query}%") ->orWhere('content', 'like', "%${query}%") ->get(); // Now build a results array $results = $items->map(function ($item) use ($query, $controller) { // If the query is found in the title, set a relevance of 2 $relevance = mb_stripos($item->title, $query) !== false ? 2 : 1; // Optional: Add an age penalty to older results. This makes sure that // newer results are listed first. // if ($relevance > 1 && $item->created_at) { // $ageInDays = $item->created_at->diffInDays(\Illuminate\Support\Carbon::now()); // $relevance -= \SpAnjaan\Sitesearch\Classes\Providers\ResultsProvider::agePenaltyForDays($ageInDays); // } return [ 'title' => $item->title, 'text' => $item->content, 'url' => $controller->pageUrl('cms-page-file-name', ['slug' => $item->slug]), 'thumb' => optional($item->images)->first(), // Instance of System\Models\File 'relevance' => $relevance, // higher relevance results in a higher // position in the results listing // 'meta' => 'data', // optional, any other information you want // to associate with this result // 'model' => $item, // optional, pass along the original model[] ]; }); return [ 'provider' => 'Document', // The badge to display for this result 'results' => $results, ]; }); } ``` That's it! ### Advanced method [](#advanced-method) If you need a bit more flexibility you can also create your own `ResultsProvider` class. Simply extend SiteSearch's `ResultProvider` and implement the needed methods. Have a look at the existing providers shipped by this plugin to get an idea of all the possibilities. When your own `ResultsProvider` class is ready, register an event listener for the `spanjaan.sitesearch.extend`event in your plugin's boot method. There you can return one `ResultsProvider` (or multiple in an array) which will be included every time a user runs a search on your website. #### Advanced example to search for custom `documents` [](#advanced-example-to-search-for-custom-documents) ``` public function boot() { Event::listen('spanjaan.sitesearch.extend', function () { return new DocumentsSearchProvider(); // or // return [new DocumentsSearchProvider(), new FilesSearchProvider()]; }); } ``` ```