Search Interface

We have created a search and analytics frontend that you can point to your Fuse instance to interact with it.

The frontend supports several standard features like autocomplete, faceted search as well as several views for displaying the results. It also supports a wide range of customization options.

Frontend in Docker image

The default Q-Sensei Fuse docker image comes with the search frontend pre-packaged and can be accessed at http://localhost:8000/ in the browser.

Note

For optimal experience we recommend a modern up to date browser. If you are using Fuse through Docker Toolbox on Windows 10 you might not be able to access the frontend using Microsoft Edge due to current limitations within the browser. Please switch to Microsoft Internet Explorer 11 in that case or any other modern browser like Mozilla Firefox or Google Chrome.

docker run -p 8000:8000 docker.qsensei.com/fuse-free

Go to http://localhost:8000/ in the browser. You will see a message similar to the following.

../../_images/nofuse.png

Click the link to Fuse Manager and make sure you setup Fuse with a content and index schema and then upload data into it.

Once done you can head back to http://localhost:8000/ for the search interface. You can go to http://localhost:8000/#!/config to configure the default frontend further.

../../_images/frontend_config.png

The Frontend Configuration UI provides additional help messages to guide you through how each setting will effect the frontend for end users. See Frontend Configuration for more information.

For any advanced use case where you want to have custom templates, themes or embedd the Frontend in a third-party environment like Drupal and WordPress you can use the additional information found below.

General Overview

To give you an idea about what our search interface can do this section will provide an overview of its parts and capabilities.

../../_images/si_overview.png

Search Bar with Autocomplete and Settings

../../_images/si_searchbar.png

At the top of your browser you find the search bar. Just start typing and you will instantly get search suggestions spanning all available facets and fulltext data. Hit return to start a fulltext search or select a specific suggestion from the autocomplete. The searchfield supports boolean operations like AND, NOT and OR for more specialized queries.

Note the small In Context on the right of the search field? Click to change to New Search. This determines if searching through the search bar will further narrow your already selected filters or start fresh.

../../_images/si_settings.png

Click the gear icon to open the settings pane. General settings for all users can be configured through the Frontend Configuration in the Management Interface. Use this to configure the available facets individually for you. If anything goes wrong the Reset button allows you to go back to the defaults set through the Management Interface.

Selected Filters and Search Terms

../../_images/si_filters.png

Below the search bar on the left selected filters and fulltext search terms of your current query are displayed. You can remove individual search terms or groups by clicking on the x button next to them or click directly on a filter to start a new search with just that term. Use the Clear button to completely clear your search.

Facets Pane

../../_images/si_facets.png

On the left part of the search interface the available search facets are shown. Which facets are available depends on the index schema, the configuration set through the Management Interface and the interface options you have set through the top settings menu. Also note that only facet are shown which actually have results.

Each facet is build in the same way. The top shows the label that facet has been given through the index schema. Next to that is a Sort icon. Click to open a small pane to select in which way this facet should be sorted, alphabetically or by the number of results the individual attributes have. Below that the available attributes are displayed with the number of search results each attribute would create. Note that this number is calculated in realtime and depends on your currently selected search filters. Finally the More button will open the search popup for more complex operations (see below).

All facets use the described default template but you are also able to specifiy a different template through Facet configuration in the Management Interface. Besides the default version a range search and a special date range search template are available. These will offer an additional Range button next to the more button that allows you to conduct from-to searches by providing input fields for general searches and date selection for facets containing dates.

Search Popup

../../_images/si_popup.png

The search popup can be opend by clicking on the More button at the botton of every facet. The popup will open with the facet pre-selected you choose.

Use the search field to directly search within a facet and use the checkboxes to select more than one attribute for an OR search. Clicking directly on a result will start a new search with that filter only. You can switch to a different facet by selecting it on the left of the popup anytime. Note that the results you will see when switching between facets depend on the checkboxes you already selected since these filters already amend your search query. When satisfied with your selection hit OK to see your search results, use Reset to revert the popup to the intial state or simply close the popup discarding any selections you made.

Search History

../../_images/si_history.png

Below the facets on the left your search history will be displayed. Click on any entry to search for that specific query again and use Up and Down arrows to page through your entries. The Clear button at the top will instantly remove all your recent search entries.

Search Results Pane

../../_images/si_results.png

Next to the facets in the main part of the search interface the actual search results are displayed. Fuse provides a default List View template for this purpose that is suitable for most use cases.

The List View uses a search results header showing the number of current results and the page of results you are on. Below that the individual result snippets are listed each consisting of several slots that display information from the content item they represent. These snippets can be configured through the List View section in the Management Interface. They support highlighting of search terms and will only display a certain amount of characters for each field that can be changed through the Management Interface.

Hovering over a result will display a Show Details button. Clicking on that (or anywhere on the search result) will expand it to show all attributes for that item. Clicking again will reduce it back to just the result snippet.

If there are more search results than are configured to be displayed on a single page (in the Management Interface) the page navigation concludes the default results template. Switch between pages via Next and Back or directly click on a page number.

Advanced Setup

This section describes how you can setup the frontend manually. These instructions are required when you are trying to make a non-trivial deployments of the frontend like have custom color-schemes or embed the frontend in a third party application.

Download the frontend library

Download qc.frontend package from the public stash repository:

git clone ssh://git@stash.qsensei.com/fron/qc.frontend-distribution.git

The git repository supports usage of npm as well as bower for dependency management.

This package contains the necessary JavaScript files (including third-party files), stylesheets as well as the source SCSS files and other required static resources like images and fonts.

  1. css/qc.frontend.css

    The main css file. If you want to customize the styles and use themes, consider using the sass source files

  2. js/qc.frontend.js

    The main frontend library file.

  3. js/qc.frontend.vendor.js

    This file contains third-party libraries that the frontend depends upon

  4. sass/qc.frontend.scss and sass/*

    This are the source files for style sheets. You can use these to create custom color schemes or override default styles.

  5. images/* and fonts/*

    Other static files.

JS Configuration File

Create your frontend js file:

touch my.fuse.frontend.js

In this file, define your frontend module and its dependencies. Immediately after the application module is defined, the default configuration is overridden to specify the fuse server to which this frontend will be searching. There are many more configuration options that is listed below in the configuration section.

index.html

Create the index.html file and include the necessary CSS and JS files.

Notice the ‘qc-frontend’ element. This is where the frontend will be rendered. This can be treated like any other HTML element, so you can put your contents above or below it for header and footer.

Full Configuration Options

In this section you can find information about all the configuration options available.

Typical Configuration File

Here is a typical configuration file taken from the example application in this repository.

General Configuration

As seen in the example configuration above, the configuration file is defined in a javascript object literal. The detailed description of this structure and all options is below.

SearchConfig
fuseEndpoint string required The Fuse API endpoint to use.
|
|
|
|
|
facetSetting Object that describes a facet's configuration.
| |
| |
| |
| |
|
|
| |
columnDef Object that describes column's configuration.
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
|
|
|
|
|

Styles Customization

We provide the SCSS files with this package to allow customization of styles.

In a typical setup you would create your application’s entry SCSS file and import the ‘qc.frontend.scss’ in it. Next you can override the variables denoting colors and fonts to change the styles.

// my-fuse-frontend.scss
.my-fuse-frontend {
    $color-scheme: 'default';
    @include "path/to/scss/qc.frontend";
}

Notice that the style is scoped with the my-fuse-frontend class. This is to reduce side effects that you could have if you are planning to embed the frontend in any third party application.

Built-in Color Schemes

You can set the $color-scheme variable to use one of the builtin color schemes. Try the following in your scss file:

$color-scheme: 'default-dark';

The available color schemes are default and default-dark.

Custom Color Schemes

To create a custom color scheme, you can set the public color variables.

/* 'default' color scheme */
$color-1-bg: #bfbfbf; /* Primary background color */
$color-1-fg: #252521; /* Primary foreground color */
$color-2-bg: #336aa2; /* Secondary background color */
$color-2-fg: #ffffff; /* Secondary foreground color */
$color-3-bg: #78b044; /* Success color */
$color-4-bg: #d10043; /* Warning color */

The meaning of each colors is listed below:

color-1-bg
The primary background color.
color-1-fg
Color used for text that is using color-1-bg for background
color-2-bg
The secondary background color.
color-2-fg
Color used for text that is using color-2-bg for background
color-3-bg
Success background color.
color-3-fg
Success foreground color
color-4-bg
Warning background color.
color-4-fg
Warning foreground color