Table of content

Customizing top left logo and background image

The top left logo is a public file which path from the root installation of DatafariUI is:

You can change it to put any png file containing your logo. Note that you MUST keep the naming (and hence you must use the png format).

If you are using DatafariUI bundled with Datafari and the default installation path, the file is located at:

The logo used in the front page is a public file which path from the root installation of DatafariUI is:

You can change it to put any png file containing your logo. Note that you MUST keep the naming (and hence you must use the png format).

If you are using DatafariUI bundled with Datafari and the default installation path, the file is located at:

The top header background image is a public file located in the root installation of DatafariUI :

images/background_datafari_banner_big.png

If you are using DatafariUI bundled with Datafari and the default installation path, the file is located at:

/opt/datafari/www/images/background_datafari_banner_big.png

This image should be minimum 1920px width and max 65px height. Note that you MUST keep the naming (and hence you must use the png format).

Customizing Displayed Facets and Elements

It is possible to customize the facets displayed as well as some of the elements displayed in DatafariUI by modifying a configuration file. This configuration file is ui-config.json and is present in the public folder of the DatafariUI project.

When installed bundled with Datafari, the location of this file is:

The default file looks like the following:

The “left” key corresponds to what is displayed in the left column of the interface.

The “center” key corresponds to what is displayed in the center (main) part of the interface. It contains two objects, a “main” object which may contain any component, and a “tabs” containing the declaration of tabs that are explained here: Customizing DatafariUI | Search Tabs.

The “right” key corresponds to what is displayed in the right column of the interface.

Each of these keys refer to an array of objects representing UI components.

Each object has a “type” property declaring the component to be instantiated as well as parameters for this component.

Supported components are:

• FieldFacet

• QueryFacet

• DateFacetCustom

• HierarchicalFacet

• SearchInformation

• ResultsList

• RangeFacet

• AggregatorFacet

Then, there is the “searchBar” key, that contains an object giving properties for the search bar and the suggesters to use in the “suggesters” array.

Two types of suggesters are supported:

• BASIC

• ENTITY

Finaly, some customization of the hotkeys is possible through “hotkeys” object.

Below are the details of each component and their parameters.

Field Facet

A field facet displays a facet tied to a given field, with the possibility to filter results based on the field values.

It looks like this:

Open

It is usually used on the left column.

The definition of a field facet looks like the following:

Parameters

Name	Optional	Default value	Description

Name	Optional	Default value	Description
title			The title showed at the top of the facet
field			The solr field associated to the facet
op			Operator, either “OR” or “AND”. Tells how documents are shown when selecting multiple entries in the facet. If “OR” documents need to have at least one selected element in the concerned field to be selected. If “AND” they need to have all selected elements as part of the concerned field
minShow			The maximum number of elements that are shown if the facet is not expanded
maxShow			The maximum number of elements that are shown if the facet is expanded (after clicking show more)
variant	yes	checkbox	Specify the type of FieldFacet to use. It can take these values : checkbox : use classic FieldFacet with a checkbox list Open Checkbox display (default) autocomplete
show	yes	true	True to display the FieldFacet in the left panel. This option is only an UI effect. The facet is still registered as a field facet in the query.
sendToSolr	yes	false	Set to true to force the query to Solr even if show is false (keep in mind that if show is true, the facet is queried whatever the value of the sendToSolr parameter). Required to be true for the use of field facet tabs (Customizing DatafariUI | Search Tabs ), which is its only purpose for now.

QueryFacet:

A query facet displays a facet tied to provided queries with the possibility to filter results based on those queries. It can include children components, providing the ability for the user to provide a custom query. In the example below, we present a way to provide a custom date range.

It looks like this:

It is usually used on the left column.

The definition of a query facet looks like the following:

Parameters:

• title: the title showed at the top of the facet

• queries: the solr queries to execute for the facet

• labels: The labels to be shown to the users alongside each query result

• id: an internal unique identifier that you must specify

• minShow: The maximum number of elements that are shown if the facet is not expanded

• maxShow: The maximum number of elements that are shown if the facet is expanded (after clicking show more)

• children: an array of children components displayed directly below this facet. Made available to specify components allowing users to specify custom queries, like the one to specify a custom date range shown in the example

• show (optional) : True to display the facet. False to hide the facet

• variant (optional, default is `both') : differ the display according to the given variant value. It could be :

  • queries_only : Only display solr queries as multiple checkboxes list

  • children_only : only display the children component contained in the children props of the QueryFacet

  • both (default) : Display both queries list and children components

DateFacetCustom

Allows users to specify a custom date range applied to the creation_date field. Specifically built to be displayed together with the creation date query facet.

Looks like this:

defined like this:

Has no parameters.

HierarchicalFacet

Displays a documents hierarchy as a facet, based on the information stored in a dedicated solr field.

It looks like the following:

The definition looks like:

Parameters:

• title: the title showed at the top of the facet

• field: the solr field in which hierarchy information are stored. The default is urlHierarchy in Datafari.

• separator: the separator used in the solr filed to separate levels of hierarchy. The default is “/” in Datafari

Aggregator Facet

Displays a facet to chose the sources to aggregate from when the aggregator is active. Source names are retrieved from the backend.

The definition looks like

Parameters:

• title: the title showed at the top of the facet

• show: show or hide this facet

Quick Links widget

Widget to display links to quickly navigate to useful content.

It is usually used in the right column. The widget definition looks like this:

Parameters:

type - The type of component to place in the service
title - The title showed at the top of the facet
show - Custom parameter, default value is true. true - for will enable the display of the "Direct Links" widget in the right pane. false - to hide its display in the service. This option is just a user interface effect. The widget is still registered with the service.
visible - Custom parameter, default value is 10. Specifies the maximum number of records that will be immediately visible when the widget is displayed

Yellow Page widget

Widget to display useful contact information

It is usually used in the right column. The widget definition looks like this:

Options:

type - The type of component to place in the service
title - The title showed at the top of the facet
show - Custom parameter, default value is true. true - for will enable the display of the "Yellow Pages" widget in the right pane. false - to hide its display in the service. This option is just a user interface effect. The widget is still registered with the service.
visible - Custom parameter, default value is 1. Specifies the maximum number of records that will be immediately visible when the widget is displayed

SearchInformation

Displays some information about the current search, such as:

• currently searched terms

• spell checking information if available as well as automatic spell checking query firing if 0 results were found

• filters applied

• facet filters applied

It looks like this:

The definition looks like:

Parameters:

• data: An array of data to be displayed. Possible values:

  • “filters”: displays the “other filters” section if present

  • “facets”: displays the facets in the filters section if present

The current search and spellcheck info are always displayed if this component is used.

Search Tabs

The UI configuration allows to add graphical tabs below the search bar, between the All content tab and the Search Tools tab.

As of the writing of this documentation (March 2022), we propose two types of tabs :

• FieldFacet : it will generate as many tabs as a field contains out of a result query. For example, with the "extension" field in our demo, it will create one tab per type of extension returned by the search query (for instance one tab for the pdf type, one for the doc type etc).
  This type of tab has two parameters :
  field : the field name used to generate the tabs
  max: the max number of tabs that can be generated

• Raw : This type of tab is called raw because it is just a link to a given URL. It has 2 parameters :
  label : the label of the tab (it is i18n)
  url: an HTTP URL.
  target: (optional) define where to open the url. If absent, default is _self. Values accepted: _self OR _blank

These tabs can be declared as illustrated below in the ui-config.json, in the center property :

Here is an example :

Note the repo_source field defined in the FieldFacet tab is also declared as the field parameters of a FieldFacet facet in the left section.

ResultsList

Shows the list of results.

Looks like this:

The definition looks like this, in ui-config.json

Parameters:

• data: An array of data to be displayed. Possible values:

  • title: Displays the document title for each result if present

  • url : Displays the url for each result if present

  • logo: Displays the file type logo for each result if present

  • previewButton: Displays the preview button for each result if present

  • extract: Displays the text snippet with highlighting for each result if present

• folderLinkSource (default is an empty array[] in which case nothing will be displayed) : array of sources to open as a folder. Needs to match with sources declared (case sensitive). For instance, if you have a source named “Enron”, the array should be ["Enron"]

• folderTarget (optional, default is _blank): target to open folder. Values are the same as the HTML attribute target. The values you can declare mandatorily come from the repo_source solr field, displayed via the source facet field to users.

• previewTarget (optional, default _self): target to open preview page. Values are the same as the HTML attribute target.

Any data not present is not displayed. If the data parameter is absent or is not an array, the default (showing everything) is used. Values other than the one given above are ignored. An empty array results in the following (Yes this is useless but possible):

Range Facet

Range Facet is a facet that displays a bar chart with a range selection tool. It is a generic react component that could be used to display any kind of dual axis data.

From ui-config.json file, you can customize the following parameters of the chart :

Configuration example include in left facet :

Example of override default parameters :

You get the following result :

You can create/extend the actual RangeFacet component. It is based on the RangeBarChart component, a customizable react bar chart component, based itself on the https://recharts.org/en-US library.

The RangeBarChart component can be embed into any other component like the RangeFacet that displays the graph as a facet with a maximal height. This component uses the following props :

Customize Search Bar component

This component comes with autocomplete feature which suggesters can be customized from the ui-config.json file.

Depending on what suggesters are configured into it, the search bar will be displaying suggestions according to the suggesters. User can navigate through it with the keyboard arrows, each selection will update the search bar value. User can press Enter to perform a search.

The searchBar has the following parameters :

Available suggesters

There are 3 types of suggesters :

• BASIC : basic suggester based on words

• ENTITY : suggester based on entities like authors names

• CUSTOM : suggester based on custom solr suggester (Work In Progress - Not ready to use yet)

Theses suggesters can be used to configure which suggesters are to be used in the search bar with the autocomplete.

Configure suggester into ui-config.json

In this file, there is a searchBar field as shown below :

This configuration is the default one, used in DatafariUI with 2 suggesters : basic and entity.

Below the parameters for each type of suggester are presented:

BASIC suggester

The basic suggester calls the default suggester bundled with datafari.

The definition looks like this:

parameters:

• maxSuggestion: The maximum number of suggestion that will be showed in the autocomplete for this suggester

• title: the title of the autocomplete section for this suggester

• subtitle: the subtitle / helper text of the autocomplete section for this suggester

• aggregator : indicates if aggregator is activated or not. If yes use the Datafari REST API rest/v2.0/noaggregator/suggest instead of rest/v2.0/suggest

ENTITY suggester

A suggester designed for entity suggestions. Adds to the query a statement like: field:(“suggestion”).

The definition looks like this:

Parameters:

• field: The field containing the entities

• suggester: the solr request handler for that suggester

• dictionary: the name of the dictionary used in the suggest handler

• asFacet: weather the filter is added to the query body (q= parameter) or as an fq.

• maxSuggestion: the maximum number of suggestions showed for this section of the autocomplete

• title: the title of the autocomplete section for this suggester

• subtitle: the subtitle / helper text of the autocomplete section for this suggester

Adding a new suggester - Configuration

Without the need to recompile Datafari or DatafariUI, you can add new suggesters in the autocomplete just by declaring them in the config file, as long as you do not want to declare a new type of suggester used in the backend (see the next chapter for adding a new type of suggester). You can get the list of currently implemented suggesters types by looking at this file: https://gitlab.datafari.com/datafari-community/DatafariUI/-/blob/dev/src/Components/SearchBar/Autocompletes/Suggester/useSuggesters.js

You also need to add the suggester into the file $DATAFARI_HOME/tomcat/conf/entity-autocomplete.properties see Adding entity autocomplete: from indexation to autocomplete | Configuring Datafari to Serve the New Suggest Request Handler

In the configuration below, we have 3 suggesters : 1 of type basic and 2 of type entity. The difference between the 2 entities suggesters here, is at the field, the name of the request handler used and titles parameters level, but it could also be at the subtitle level.

Adding a new type of suggester

This requires developing new components in DatafariUI. Refer to the DatafariUI read me for more information on how to do that.

Define the list of prefered sources

You can define a list of prefered sources by adding a “sources” key to the ui-config object that holds an array of source names, ordered in decreasing order of their importance.

If absent or empty, this has no effect. When present, results coming from the preffered sources are boosted and appear higher in the search results.

MappingValues (optional)

From ui-config.json file, you can customize labels from results list for each FieldFacet or Field tab. This field is a map key/value to rename a specific name.

Example:

Key value is case sensitive, the label from label have to match exactly to rename the label (i.e. html is different of HTML)

The mappingValues block is global, it does not belong to a facet block, so it must be declared at the same level than the queryParams block or the hotkeys block

QueryParams

From ui-config.json file, you can customize the fields you send to Solr. queryParams is an object which can have the following keys :

useHotkey hook

This hook allows to define a hotkey with one command key plus an optional second letter key.
Command keys are defined as below (case sensitive) :

• shift

• alt

• ctrl

• escape

These command keys are defined in src/Hooks/useHotkey.js. Use exported cmd keys ID in other components.

These command keys can be associated with another key like any alphanumeric key, to provide hotkey under the form : [CMD+key] such as [ctrl+k], [shift+S] etc.

useHotkey hook can be used anywhere in the react application. Exemple of use :

The hook uses the following parameters :

• cmd : Command key, one of defined command keys in the useHotkey js file

• key (optional, default value to "") : Second key of the hotkey.

• enable (optional, default is false) : True to enable the hotkey. False otherwise. In this last case, empty string will be returned

• callback : Called if command key matched and either the second key matched or it equals to empty string

The hook returns a component that represents the hotkey. You can mount it wherever you want in your component. By default, this component displays the hotkey between [] like [⇧S].

Hotkeys configuration

Hotkeys can be configured into ui-config.json file, like below ;

Be care, cmd and key are case sensitive. If you use shift as command, the key MUST be in CAPITAL.

Hotkeys IDs are defined into the useHotkey.js (activeSearchBar, deactiveSearchBar, ...). Defined here other IDs to increase the list of hotkeys available

Export search results

In ui-config.json, you can add some export format that the backend offer. So far (31.01.2023), Datafari API offers excel format to export results list.

exportResults have to have at least one key under (here is Excel. Each keys here will be a format in the export modal:

Under each key, the following fields are mandatory:

• minResults : minimum number of results to be exported

• maxResults : maximum number of results to be exported

• defaultResults : default number of results to be exported

The key format is the type format defined in the backend (excelfor example)

DEV mode banner

In ui-config.json, you can set the dev mode on. It can be useful for instance to warn your datafari users that you have not finished configuring your Datafari, but that they can start playing with it. In DatafariUI, a warn banner will be showed in the bottom of the screen. Here is a sample configuration :

• enable : True to enable devMode.

• banner : Define props for the banner

  • location (default is BOTTOM) : Define the location of the banner, between TOP or BOTTOM

  • content : Translation key of the banner content to display

  • props : Define CSS props for banner component

    • backgroundColor : background color of the banner

Advanced search

You can decide which fields to display in the advanced search dropdown lists, and which labels to use. For that, please refer to https://datafari.atlassian.net/wiki/spaces/DATAFARI/pages/331415555

Customizing colors and theme

It is possible to customize the facets displayed as well as some of the elements displayed in DatafariUI by modifying a configuration file. This configuration file is theme.json and is present in the public folder of the DatafariUI project.

When installed bundled with Datafari, the location of this file is:

The default file looks like so:

The colored screenshot below will help me explain which part of the UI are affected by each configuration :

• primary: parts in blue in the screenshot

• secondary: part (and text) in green in the screenshot

• background:

  • default: parts in dark pink

  • paper: parts in light pink

For primary and secondary:

• light, main and dark: three variations of the color. Can be used to provide variations in some situation. Only the main color is used in the current DatafariUI interface (as of November 25th 2021)

• contrastText: The color used for the text displayed on elements using this color scheme (primary or secondary)

More theme customization

DatafariUI uses MaterialUI and its theme capabilities (https://mui.com/customization/default-theme/#main-content ). The theme configuration file can redefine the theme entirely as you wish so you can change any little detail as long as you read the doc and understand how to access it.

You can also use https://bareynol.github.io/mui-theme-creator/ to help you in your theme creation.