madmatt / silverstripe-funnelback
Provides an interface to search a Funnelback collection
Installs: 1 128
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 2
Open Issues: 1
Type:silverstripe-vendormodule
Requires
- php: ^8
- guzzlehttp/guzzle: ^7.4
- silverstripe/config: ^1
- silverstripe/framework: ^4.10
Requires (Dev)
- phpunit/phpunit: ^9
README
This module provides an interface to query a Funnelback collection.
Features
Current features
- Search a single Funnelback collection by one or more keywords
- Present paginated search results to users
- Has been tested and known to work with Funnelback version 15.
You can see this module in action on the Whaikaha - Ministry of Disabled People website.
Still to do
- Identify a search result in the database and provide the most up-to-date content for the results page
- Ability to filter or facet information (reliant on Funnelback supporting this)
What this module won't try to do
- Index content into a Funnelback collection. Instead, use the silverstripe-search-service module and add your own Funnelback search service, OR have Funnelback crawl your website directly.
Installation
Install this module via Composer:
$ composer require madmatt/silverstripe-funnelback
Requirements
You need to be using Silverstripe CMS 4.10 or newer, no other dependencies should matter.
Usage
Once you've installed the module, you'll need to do two things:
- Configure the necessary environment variables.
- Create & integrate your search form.
Step 1: Configuring the necessary environment variables
This module needs the following environment variables configured:
SS_FUNNELBACK_URL
: The base URL to the Funnelback API endpoint, without any trailing slashes or path. For example, https://example-uat-search.squiz.cloudSS_FUNNELBACK_USERNAME
: The username provided by Funnelback.SS_FUNNELBACK_PASSWORD
: The password provided by Funnelback.SS_FUNNELBACK_COLLECTION
: The name of the collection (e.g. example-collection).
Once configured, the module can be used to perform search requests.
Step 2: Create & integrate your search form
You may already have some search infrastructure in place. If so, adapt these instructions as needed. This assumes you have nothing setup yet.
Create a new controller for your search page - app/src/Controllers/SearchController.php
:
<?php namespace App\Controllers; use Madmatt\Funnelback\SearchService; class SearchController extends \PageController { private static $dependencies = [ 'searchService' => '%$' . SearchService::class ]; public SearchService $searchService; public function index(HTTPRequest $request) { $keyword = $request->getVar('q'); $start = $request->getVar('start') ?? 0; // If a keyword has been supplied, perform a search and return the results. // Otherwise, don't bother performing an empty search. if ($keyword) { return [ 'Query' => DBField::create_field('Varchar', $keyword) 'Results' => $this->searchService->search($keyword, $start), ]; } else { return []; } } }
Next, register your new controller via a Director
route, for example in app/_config/routes.yml
:
--- Name: app-routes After: - '#rootroutes' - '#coreroutes' --- SilverStripe\Control\Director: rules: 'search': 'App\Controllers\SearchController'
Create your search results template (for example themes/<theme>/templates/App/Search/Layout/Search.ss
):
<main> $SearchForm <% if $Results || $Query %> <section> <h2>Results for "$Query"</h2> </section> <section> <% if $Results %> <h3>Displaying $Results.FirstItem - $Results.LastItem results of $Results.TotalItems</h3> <ul> <% loop $Results %> <li> <h3><a href="$Link">$Title</a></h3> <p>$Summary.RAW</p> </li> <% end_loop %> </ul> <% if $Results.MoreThanOnePage %> <nav aria-label="pagination"> <ul> <% if $Results.NotFirstPage %> <li><a href="$Results.PrevLink">Previous</a></li> <% end_if %> <% loop $Results.PaginationSummary %> <% if $CurrentBool %> <li>$PageNum <span class="sr-only">(current)</span></li> <% else %> <% if $Link %> <li><a href="$Link">$PageNum</a></li> <% else %> <li>...</li> <% end_if %> <% end_if %> <% end_loop %> <% if $Results.NotLastPage %> <li><a href="$Results.NextLink">Next</a></li> <% end_if %> </ul> </nav> <% end_if %> <% else %> <h3>No search results found for "$Query"</h3> <% end_if %> </section> <% end_if %> </main>
Now, assuming that Funnelback has already crawled your website, you should be able to visit http://your-website/search?q=testing
and have the website query Funnelback and return results for you.
On your PageController
class, add the following SearchForm
method so that you can output a search form on every page of your website:
<?php use SilverStripe\CMS\Controllers\ContentController; use SilverStripe\Forms\FieldList; use SilverStripe\Forms\Form; use SilverStripe\Forms\FormAction; use SilverStripe\Forms\TextField; class PageController extends ContentController { public function SearchForm(): Form { $form = Form::create( $this, __FUNCTION__, FieldList::create([ TextField::create('q', 'Search query') ]), FieldList::create([ FormAction::create('search') ]) ); $form ->setFormAction('/search') // Override the standard form action URL to always be /search ->setFormMethod('GET', true) // Ensure the form sends the search query in the URL so it can be bookmarked and cached etc ->disableSecurityToken(); // Turn off CSRF protection for this form, it's not required unless you have sensitive or private search results return $form; } }
Finally, add this into your template:
<header> $SearchForm </header>
Provided everything is configured correctly, you should now have everything you need to get Funnelback search working on your website.
Optional configuration
Optional configuration options are listed below.
Code of Conduct
When having discussions about this module, please adhere to the Silverstripe Community Code of Conduct.