...

{ "x_datakey": "x_value", "y_datakey": "y_value" }

const chartData = [   
  { name: '01/02/2022', doc: 300 },   
  { name: '02/02/20222', doc: 145 }
]

const chartData = [   
  { index: 1, price: 1000 },   
  { index: 2, price: 350 }
]

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"
  }
}

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

ENTITY suggester

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

The definition looks like this:

...

...

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 :

 ...
  "searchBar": {
    "suggesters": [
      {
        "type": "ENTITYBASIC",
        "props": {
    "field": "authorTokens",      "maxSuggestion": 5,
          "suggestertitle": "suggestAuthorsSUGGESTED QUERIES",
          "dictionarysubtitle": "suggesterEntityAuthorsQueries extending your current query terms",
    "asFacet": false,    },
     "maxSuggestion": 5,},
      {
        "titletype": "Entities suggestedENTITY",
        "subtitleprops": {
 "Queries extending your current query terms"   } }

Parameters:

"field

...

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

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 Advanced search - Fixed values list for fields

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:

/opt/datafari/www/theme.json

The default file looks like so:

{
  "palette": "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": {
    "typemaxSuggestion": "light"5,
    "primarytitle": {
 "SUGGESTED QUERIES",
    "mainsubtitle": "#ffffff",Queries extending your current query   terms"dark":
"#fafafa",  }
}

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

ENTITY suggester

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

The definition looks like this:

{
   "contrastTexttype": "#000000ENTITY",
    },
    "secondary""props": {
 
    "lightfield": "#99cc33authorTokens",
      "mainsuggester": "#679439suggestAuthors",
      "darkdictionary": "#648542"
    }suggesterEntityAuthors",
    "backgroundasFacet": {false,
      "defaultmaxSuggestion": "#ffffff"5,
      "papertitle": "#fafafa"
    }Entities suggested",
  },   "typographysubtitle": {"Queries extending your current  "fontFamily": "Montserrat, Helvetica, Arial, sans-serifquery terms"
  }
}

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.

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.

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 user custom search

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 :

...

...

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

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 and titles parameters level, but it could also be at the subtitle level.

...
  "searchBar": {
    "suggesters": [
      {
        "type": "BASIC",
        "props": {
          "maxSuggestion": 5,
          "title": "SUGGESTED QUERIES",
           "typesubtitle": "BASIC",Queries extending your current query terms",
   "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"
        }
      },
      {
   ]   }   ...

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

The searchBar has the following parameters :

...

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.

For each one, you can configure the following props :

• Put here the Solr field required by your suggestion request (optional, depends on your suggester)

• maxSuggestion defines the number of results displayed in suggestions

• title Key name for translation of the title suggester section

• subtitle Key name for translation of the subtitle suggester section

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

...

backdrop

...

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

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

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 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": "suggestAuthors",
          "dictionary": "suggesterEntityAuthors",
          "asFacet": false,
          "maxSuggestion": 5,
          "title": "Entities suggested by social security number",
          "subtitle": "Queries extending your current query terms"
        }
      }
    ]
  }
  ...

Adding a new type of suggester

When adding a new type of suggester, we need to implement it in React and rebuild DatafariUI. You need to follow these steps :

1. Implement a new hook with the same structure as other hooks that already exist, such as useBasicAutocomplete.js. This hook needs to have at least, a querySuggestions function, a suggestions array for results, a onSelect function to return the real value to be displayed in the search bar, title and subtitle as string to provide a title and a subtitle the autocomplete section.

2. In useSuggesters.js, add a new suggester type and export it. Then add the new suggester hook in the array definedSuggesters :

...
export const NEW_TYPE = "myNewTypeSuggester";
...
const [definedSuggesters] = useState([
  {
    type: BASIC_ID,
    suggester: useBasicAutocomplete,
  },

  {
    type: ENTITY_ID,
    suggester: useEntityAutocomplete,
  },

  {
    type: CUSTOM_ID,
    suggester: useCustomSuggesterAutocomplete,
  },
  {
    type: NEW_TYPE,
    suggester: useNewTypeSuggesterAutocomplete,
  },
]);

3. Finally, add this new type in the ui-config.json file :

...
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: "NEW_TYPE",
        props: {
          field: "newField",
          suggester: "newSuggester",
          dictionary: "newDictionary",
          asFacet: false,
          maxSuggestion: 5,
          title: "New suggestions",
          subtitle: "Queries extending your current query terms",
        },
      }
    ],
  },
  ...

Adapt props to your new type. All fields will be pass as props to the new type suggester.

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

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"type": "ENTITY",
        "props": {
          "field": "authorSocialSecurityNumber",
          "suggester": "suggestAuthors",
          "dictionary": "suggesterEntityAuthors",
          "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.

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

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 Advanced search - Fixed values list for fields

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:

/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": {
      "locationdefault": "BOTTOM#ffffff",
      "contentpaper": "Dev#fafafa"
 mode banner content", }
  },
  "propstypography": {
    "fontFamily": "Montserrat, Helvetica, Arial,   "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

...

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 (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.