This documentation is complemented by the https://gitlab.datafari.com/datafari-community/DatafariUI/-/blob/dev/README.md that gives you more indepth details for low level modifications of DatafariUI, in particular those that require rebuilding the framework.

The documentation below is valid from November 5th 2021 or from commit dbb8d17e6a35b5a313e4086e0b04fffaaa94a24c of the DatafariUI repository.

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:

images/logo.png

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:

/opt/datafari/www/images/logo.png

A square is preferred. Be aware that the file will be resized to 50px in height when displayed in the interface.

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

images/logo_big.png

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:

/opt/datafari/www/images/logo_big.png

A rectangle is preferred. Be aware that the file will be resized to approximately 210px width when displayed in the interface.

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:

/opt/datafari/www/ui-config.json

The default file looks like the following:

{
  "left": [
    {
      "type": "FieldFacet",
      "title": "Extension",
      "field": "extension",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5
    },
    {
      "type": "FieldFacet",
      "title": "Language",
      "field": "language",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5
    },
    {
      "type": "FieldFacet",
      "title": "Source",
      "field": "repo_source",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5,
      "show": false
    },
    {
      "type": "QueryFacet",
      "title": "Creation Date",
      "queries": [
        "creation_date:[NOW/DAY TO NOW]",
        "creation_date:[NOW/DAY-7DAY TO NOW/DAY]",
        "creation_date:[NOW/DAY-30DAY TO NOW/DAY-8DAY]",
        "creation_date:([1970-09-01T00:01:00Z TO NOW/DAY-31DAY] || [* TO 1970-08-31T23:59:59Z])",
        "creation_date:[1970-09-01T00:00:00Z TO 1970-09-01T00:00:00Z]"
      ],
      "labels": [
        "Today",
        "From Yesterday Up To 7 days",
        "From 8 Days Up To 30 days",
        "Older than 31 days",
        "No date"
      ],
      "id": "date_facet",
      "minShow": 5,
      "children": [
        {
          "type": "DateFacetCustom"
        }
      ]
    },
    {
      "type": "HierarchicalFacet",
      "field": "urlHierarchy",
      "title": "hierarchical facet",
      "separator": "/"
    },
    {
      "type": "AggregatorFacet",
      "title": "Aggregator facet"
    }
  ],
  "center": {
    "main": [
      {
        "type": "SearchInformation",
        "data": ["filters", "facets"]
      },
      {
        "type": "ResultsList",
        "data": ["title", "url", "logo", "previewButton", "extract"],
        "folderLinkSources": ["enron"],
        "folderTarget": "_blank",
        "previewTarget": "_self"
      }
    ],
    "tabs": [
      { "type": "FieldFacet", "field": "repo_source", "max": 3 }
    ]
  },
  "right": [],
  "searchBar": {
    "suggesters": [
      {
        "type": "BASIC",
        "props": {
          "maxSuggestion": 5,
          "title": "SUGGESTED QUERIES",
          "subtitle": "Queries extending your current query terms"
        },
        "aggregator": false
      },

      {
        "type": "ENTITY",
        "props": {
          "field": "authorTokens",
          "suggester": "suggestAuthors",
          "dictionary": "suggesterEntityAuthors",
          "asFacet": false,
          "maxSuggestion": 5,
          "title": "Entities suggested",
          "subtitle": "Queries extending your current query terms"
        }
      }
    ]
  },
  "queryParams": {
    "fields": [
      "title",
      "url",
      "id",
      "extension",
      "preview_content",
      "last_modified",
      "crawl_date",
      "author",
      "original_file_size",
      "emptied",
      "repo_source"
    ]
  },
  "hotkeys": {
    "activeSearchBar": {
      "cmd": "shift",
      "key": "S",
      "enable": false
    }, 
    "deactiveSearchBar": {
      "cmd": "escape", 
      "enable": false
    }
  },
  "devMode": {
    "enable": false,
    "banner": {
      "location": "BOTTOM",
      "content": "Dev mode banner content",
      "props": {
        "backgroundColor": "orange"
      }
    }
  }
}

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:

It is usually used on the left column.

The definition of a field facet looks like the following:

{
      "type": "FieldFacet",
      "title": "Extension",
      "field": "extension",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5,
      "show": true,
      "sendToSolr": true
    },

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 Checkbox display (default) autocomplete search with 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:

{
      "type": "QueryFacet",
      "title": "Creation Date",
      "queries": [
        "creation_date:[NOW/DAY TO NOW]",
        "creation_date:[NOW/DAY-7DAY TO NOW/DAY]",
        "creation_date:[NOW/DAY-30DAY TO NOW/DAY-8DAY]",
        "creation_date:([1970-09-01T00:01:00Z TO NOW/DAY-31DAY] || [* TO 1970-08-31T23:59:59Z])",
        "creation_date:[1970-09-01T00:00:00Z TO 1970-09-01T00:00:00Z]"
      ],
      "labels": [
        "Today",
        "From Yesterday Up To 7 days",
        "From 8 Days Up To 30 days",
        "Older than 31 days",
        "No date"
      ],
      "id": "date_facet",
      "minShow": 5,
      "children": [
        {
          "type": "DateFacetCustom"
        }
      ]
    }

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:

{
  "type": "DateFacetCustom"
}

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:

{
      "type": "HierarchicalFacet",
      "field": "urlHierarchy",
      "title": "hierarchical facet",
      "separator": "/"
    }

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

{
      "type": "AggregatorFacet",
      "title": "Aggregator facet",
      "show": false
    }

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:

{
  "type": "DirectLinksWidget",
  "title": "Direct Links",
  "show": true
  visible: 1
},

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:

{
  "type": "YellowPagesWidget",
  "title": "Yellow Pages",
  "show": true
  visible: 1
}

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:

{
      "type": "SearchInformation",
      "data": ["filters", "facets"]
}

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 :

"center": {
    "main": [
      {
        "type": "SearchInformation",
        "data": ["filters", "facets"]
      },
      {
        "type": "ResultsList",
        "data": ["title", "url", "logo", "previewButton", "extract"]
      }
    ],
    "tabs": [
      { "type": "FieldFacet", "field": "extension", "max": 3 },
      { "type": "FieldFacet", "field": "repo_source", "max": 3 },
      { "type": "Raw", "label": "google", "url": "https://www.google.fr" },
      { "type": "Raw", "label": "LinkedIn", "url": "https://www.linkedin.com" }
    ]
  }

A field tab is based on a facet, one of those defined in the left or right fields. For instance, if you define a tab based on the repo_source facet, you MUST define the repo_source facet. Otherwise, your tab will not be displayed. If you do NOT want to have both the left facet and its corresponding tabs on tab, and you only want the tabs to be displayed, please set the SHOW parameter of the repo_source facet to false (see example above). If you do not do that, when on the ALL CONTENT tab, you will see both widgets, and the facet will disappear when clicking on one of the tabs corresponding to this same facet.

Here is an example :

{
  "left": [
    {
      "type": "FieldFacet",
      "title": "Extension",
      "field": "extension",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5,
      "show": false
    },
    {
      "type": "FieldFacet",
      "title": "Language",
      "field": "language",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5
    },
    {
      "type": "FieldFacet",
      "title": "Source",
      "field": "repo_source",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5
    }
  ],
  "center": {
    "main": [
      {
        "type": "SearchInformation",
        "data": ["filters", "facets"]
      },
      {
        "type": "ResultsList",
        "data": ["title", "url", "logo", "previewButton", "extract"],
        "folderLinkSources": [],
        "folderTarget": "_blank",
        "previewTarget": "_self"
      }
    ],
    "tabs": [
      { "type": "FieldFacet", "field": "extension", "max": 3 },
      { "type": "FieldFacet", "field": "repo_source", "max": 3 }
    ]
  },
  "right": [],
  "searchBar": {
    "suggesters": []
  }
}

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.

Select a tab will hide the associated facet (here, extension facet is hidden)

ResultsList

Shows the list of results.

Looks like this:

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

{
  "type": "ResultsList",
  "data": ["title", "url", "logo", "previewButton", "extract"],
  "folderLinkSources": [],
  "folderTarget": "_blank",
  "previewTarget": "_self"
}

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

This facet is still in development as of March 15th, 2022

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.

Range facet

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

Name	Description

Name	Description
type	Facet type set to `RangeFacet`
title	i18n facet title
field	Solr field to bind
start	Solr range start
end	Solr range end
gap	Solr range gap
yDataKey	Key used to format data and used to display the Y bar legend. Key is i18n.
ranges (Optional)	Array of predefined integer ranges to get as much as radio button selection to give to the brush tool a predefined range. Default is an empty array and the ranges controls are hidden.
rangeLabel (Optional)	i18n label next to range value
showBrushBounds (Optional)	`true` to display the brush bounds under the brush tool. Default is `false`
barFillColor (Optional)	Bar fill color. Default is `#679439AA` (smooth green)
brushStrokeColor (Optional)	brush stroke color (range selection tool under the graph). Default is `#679439` (smooth green)

Configuration example include in left facet :

"left": [
    {
      "type": "FieldFacet",
      "title": "Extension",
      "field": "extension",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5
    },
    {
      "type": "FieldFacet",
      "title": "Language",
      "field": "language",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5
    },
    {
      "type": "FieldFacet",
      "title": "Source",
      "field": "repo_source",
      "op": "OR",
      "minShow": 2,
      "maxShow": 5,
      "show": false
    },
    {
      "type": "QueryFacet",
      "title": "Creation Date",
      "queries": [
        "creation_date:[NOW/DAY TO NOW]",
        "creation_date:[NOW/DAY-7DAY TO NOW/DAY]",
        "creation_date:[NOW/DAY-30DAY TO NOW/DAY-8DAY]",
        "creation_date:([1970-09-01T00:01:00Z TO NOW/DAY-31DAY] || [* TO 1970-08-31T23:59:59Z])",
        "creation_date:[1970-09-01T00:00:00Z TO 1970-09-01T00:00:00Z]"
      ],
      "labels": [
        "Today",
        "From Yesterday Up To 7 days",
        "From 8 Days Up To 30 days",
        "Older than 31 days",
        "No date"
      ],
      "id": "date_facet",
      "minShow": 5,
      "children": [
        {
          "type": "DateFacetCustom"
        }
      ]
    },
    {
      "type": "RangeFacet",
      "field": "creation_date",
      "start": "NOW-300MONTH",
      "end": "NOW/MONTH",
      "gap": "+1MONTH",
      "title": "Date Range",
      "yDataKey": "doc",
      "ranges": [1, 3, 6, 12, 36],
      "rangeLabel": "Month",
      "showBrushBounds": true
    },
    {
      "type": "RangeFacet",
      "field": "page_count",
      "start": "0",
      "end": "99",
      "gap": "+1",
      "title": "Page count",
      "yDataKey": "page",
      "ranges": [1, 3, 6, 12, 36],
      "rangeLabel": "Page",
      "showBrushBounds": true
    },
    {
      "type": "HierarchicalFacet",
      "field": "urlHierarchy",
      "title": "hierarchical facet",
      "separator": "/"
    },
    {
      "type": "AggregatorFacet",
      "title": "Aggregator facet"
    }
  ]

Example of override default parameters :

{       
 "type": "RangeFacet",
  "field": "page_count",
  "start": "0",
  "end": "99",
  "gap": "+1",
  "title": "Page count",
  "yDataKey": "page",
  "rangeLabel": "Page",
  "barFillColor": "orange",       
  "brushStrokeColor": "black"      
}

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 :

Prop name	Type	Description

Prop name	Type	Description
data	Array	an array of objects that represents the data to be displayed in the graph. The minimal object structure must be as follows : `{ "x_datakey": "x_value", "y_datakey": "y_value" }` Example : `const chartData = [ { name: '01/02/2022', doc: 300 }, { name: '02/02/20222', doc: 145 } ]` X labels will be based on `x_datakey` value. The legend for Y axis will be based on `x_datakey` name (not the value!). Each axis is auto scale. With the previous example, the dates are used for X labels. `doc` appears in the legend on top. But you can use any type of values as well : `const chartData = [ { index: 1, price: 1000 }, { index: 2, price: 350 } ]`
xDataKey	string	Name of the field in the data array object for X axis
yDataKey	string	Name of the field in the data array object for Y axis
maxHeight	number\|string	Max height of the graph. Default is `100%`
width	number\|string	Width of the graph. Default is `100%`
startIndex	number	Start index of the brush tool
endIndex	number	End index of the brush tool
brushStrokeColor	string	CSS color of the brush tool stroke. Default is `#679439`
barFillColor	string	CSS color of the chart bar. Default is `#679439AA`
xTickFormater	function<value>:string	A function that takes the X axis label value and returns a formatted value. Default is undefined.
brushLabelFormatter	function<value>:string	A function that formats the brush label as you will. Default returns the current value
onSelectChanged	function<startIndex, endIndex>:void	A function called when the user has changed the brush selection.

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 :

Name	Description

Name

Description

suggesters

Array of suggesters.

Several suggesters can be added, even if they are of the same type : you can add 2 entity suggesters but with different field/suggester.

Each suggester result will be displayed in a dedicated section below the search bar.

Available suggester types and their parameters are presented below

backdrop

Enable / Disabled the backdrop behind the search bar when it is focused. Default is false (no backdrop).

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 :

 ...
  "searchBar": {
    "suggesters": [
      {
        "type": "BASIC",
        "props": {
          "maxSuggestion": 5,
          "title": "SUGGESTED QUERIES",
          "subtitle": "Queries extending your current query terms",
        },
        "aggregator": false
      },

      {
        "type": "ENTITY",
        "props": {
          "field": "authorTokens",
          "suggester": "suggestAuthors",
          "dictionary": "suggesterEntityAuthors",
          "asFacet": false,
          "maxSuggestion": 5,
          "title": "Entities suggested",
          "subtitle": "Queries extending your current query terms"
        }
      }
    ]
  }
  ...

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:

{
  "type": "BASIC",
  "props": {
    "maxSuggestion": 5,
    "title": "SUGGESTED QUERIES",
    "subtitle": "Queries extending your current query terms"
  },
        "aggregator": false
      }

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:

{
  "type": "ENTITY",
  "props": {
    "field": "authorTokens",
    "suggester": "suggestAuthors",
    "dictionary": "suggesterEntityAuthors",
    "asFacet": false,
    "maxSuggestion": 5,
    "title": "Entities suggested",
    "subtitle": "Queries extending your current query terms"
  }
}

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.

...
  "searchBar": {
    "suggesters": [
      {
        "type": "BASIC",
        "props": {
          "maxSuggestion": 5,
          "title": "SUGGESTED QUERIES",
          "subtitle": "Queries extending your current query terms",
        },
      },
      {
        "type": "ENTITY",
        "props": {
          "field": "authorTokens",
          "suggester": "suggestAuthors",
          "dictionary": "suggesterEntityAuthors",
          "asFacet": false,
          "maxSuggestion": 5,
          "title": "Entities suggested",
          "subtitle": "Queries extending your current query terms"
        }
      },
      {
        "type": "ENTITY",
        "props": {
          "field": "authorSocialSecurityNumber",
          "suggester": "suggestSocialSecurityNumber",
          "dictionary": "suggesterEntitySocialSecurityNumbers",
          "asFacet": false,
          "maxSuggestion": 5,
          "title": "Entities suggested by social security number",
          "subtitle": "Queries extending your current query terms"
        }
      }
    ]
  }
  ...

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.

{
...
"sources": ["source name 1", "source name 2"]
}

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.

This feature is not active yet (as of April 2022). You can define you preferences, but no boosting will occur.

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:

"mappingValues": {
  "pdf": "Fichier PDF",
  "doc": "Fichier Doc",
  "html": "Fichier Web"
}

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 :

Key name	description	Default value

Key name	description	Default value
fields	An array of string that define fields sent to solr for each query.	`"fields": [ "title", "url", "id", "extension", "preview_content", "last_modified", "crawl_date", "author", "original_file_size", "emptied", "repo_source" ]`

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 :

import { CTRL } from "src/Hooks/useHotkey.js"

const { hotkey: ctrlHotkey } = useHotkey({
  cmd: CTRL,
  key: "D",
  enable: true,  
  callback: handleHotkey,
});

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 ;

"hotkeys": {
    "activeSearchBar": {
      "cmd": "shift",
      "key": "S",
      "enable": false
    },
    "deactiveSearchBar": {
      "cmd": "escape",
      "enable": false
    }
  }

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": {
    "excel": {
      "minResults": 1,
      "maxResults": 5000,
      "defaultResults": 100
    }
  }

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 :

"devMode": {
    "enable": true,
    "banner": {
      "location": "BOTTOM",
      "content": "Dev mode banner content",
      "props": {
        "backgroundColor": "orange"
      }
    }
  }

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

This functionality is available from commit a99c24fc77cfb7b76ef3c52e53a4ef701a0f4545

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:

/opt/datafari/www/theme.json

The default file looks like so:

{
  "palette": {
    "type": "light",
    "primary": {
      "main": "#ffffff",
      "dark": "#fafafa",
      "contrastText": "#000000"
    },
    "secondary": {
      "light": "#99cc33",
      "main": "#679439",
      "dark": "#648542"
    },
    "background": {
      "default": "#ffffff",
      "paper": "#fafafa"
    }
  },
  "typography": {
    "fontFamily": "Montserrat, Helvetica, Arial, sans-serif"
  }
}

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 (Default theme viewer - Material UI ). 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 Material UI Theme Creator to help you in your theme creation.

Customizing DatafariUI

Table of content

Customizing top left logo and background image

Customizing Displayed Facets and Elements

Field Facet

QueryFacet:

DateFacetCustom

HierarchicalFacet

Aggregator Facet

Quick Links widget

Yellow Page widget

SearchInformation

Search Tabs

ResultsList

Range Facet

Customize Search Bar component

Available suggesters

Configure suggester into ui-config.json

BASIC suggester

ENTITY suggester

Adding a new suggester - Configuration

Adding a new type of suggester

Define the list of prefered sources

MappingValues (optional)

QueryParams

useHotkey hook

Hotkeys configuration

Export search results

DEV mode banner

Advanced search

Customizing colors and theme

More theme customization

Related content