react-hierarchy-selector

Description

Hierarchy selector component is a component that can be useful for selecting items of hierarchies. It can take data from any sources through a function that should return a promise object. The promise object, in its turn, should return a data structure hierarchyItemListShape of type

Installation

npm install @opuscapita/react-hierarchy-selector

Demo

View the DEMO

Change log

View the Change log

Migrate guide

View the Migrate guide between major versions

Builds

UMD

The default build with compiled styles in the .js file. Also minified version available in the lib/umd directory.

CommonJS/ES Module

You need to configure your module loader to use cjs or es fields of the package.json to use these module types. Also you need to configure sass loader, since all the styles are in sass format.

• With webpack use resolve.mainFields to configure the module type.
• Add SASS loader to support importing of SASS styles.

Dependencies

Regular

• @opuscapita/oc-cm-common-styles
• @opuscapita/react-checkbox
• @opuscapita/react-perfect-scrollbar
• @opuscapita/react-searchbar
• @opuscapita/react-spinner
• classnames
• react-icons
• react-list

Peer dependencies

• prop-types
• react
• react-dom
• react-bootstrap

Data structure

Content

Hierarchy selector component expects data, for example, from a back-end to show with the following structure (type hierarchyItemListShape):

[
  {
    "id": 1,
    "name": "Company 1",
    "children": [
      {
        "id": 12,
        "name": "Europe",
        "children": [
          {
            "id": 113,
            "name": "FI12 1234 1234 1234 1234 14",
            "children": [],
          },
          {
            "id": 114,
            "name": "FI12 1234 1234 1234 1234 15",
            "children": [],
          }
        ]
      }
    ]
  },
]

where id, name and children are required properties. The last level of hierarchy can include also additional properties. Additional property information can be shown by implementing listItemRenderFunction callback function (see API of HierarchySelectorView). The number of level is not limited by the component.

Checked items

Here is a data structure that components HierarchySelectorView and HierarchySelectorComboBox return within callback functions onCheckListChanged and onSelect and contains checked items:

[
   {
     "id": 1,
     "name": "Company 1",
     "level": 1,
     "parentId": null,
     "parentIds": [],
     "isCheckedAll": true,
     "isChildren": true
   },
   {
     "id": 212,
     "name": "FI12 1234 1234 1234 1234 22",
     "level": 3,
     "parentId": 25,
     "parentIds": [2,25],
     "isCheckedAll": false,
     "isChildren": false
   },
]

See more information in descriptions of the callback functions.

Pre-checked items

A structure of pre-checked items:

[  
    {
      id: oneOfType([number, string]).isRequired,
      parentId: oneOfType([number, string]),
      isCheckedAll: bool,
    },
]

id, parentId and isCheckedAll attributes are enough to define pre-checked items for the components. If isCheckedAll attribute is missed the components interpret this as false value. If parentId is null, it means that the item has no parent.

In practice, you can pass, for example, the same structure as callback function onSelect returns. The compoments will pay attention to id, parentId and isCheckedAll attributes only.

The components (combo-box and view) pay attention to id and parentId while searching for pre-checked items. It means that Back-End should return unique parentId - id combinations for all items of hierarchies while id of a particular item could be not unique.

API

HierarchySelectorView

Properties

Property name | Type | Required | Default value | Description ---|---|:---:|---|--- allLabel | string or element | | 'All' | A text of 'All' checkbox of combo-box lists btnCancelLabel | string or element | | 'Cancel' | A text of Cancel button of the component btnSelectLabel | string or element | | 'Select' | A text of Select button of the component dataSourceProvider | dataSourceProviderType | yes | | Data provider for the component groupName | string | | <empty string> | Input field value of a group name groupNameLabel | string or element | | 'Group name' | A label text of the group name input field groupNamePlaceHolder | string | | 'Please, fill a group name' | A placeholder text of the group name input field listItemRenderFunction | function | | null | A custom rendering function to render the last items in hierarchy differently than by default preCheckedItems | preCheckedItemsListShape | | null | Defines pre-checked items for the view selectedItemListLabel | string or element | | 'Selected items' | A label text of a selected items list selectedItemRenderFunction | function | | null | A custom rendering function to render selected list items differently than by default. The function has only one parameter that represents the current selected item for rendering. Otherwise it works the same way as listItemRenderFunction function showInModal | boolean | | true | Whether to show the component as a popup modal window or not (it uses a bootstrap modal component). When 'standalone' property = true, then the view will be rendered as a part of a page standalone | boolean | | false | Set to true, if the component used as a standalone component without HierarchySelectorComboBox. In this case, some elements such GroupName component will be hidden. title | string or element | | <empty string> | A title of the component onCancel | function | | <empty function> | A callback function that is called when Cancel button of the component is clicked (Cancel button is visible only in a modal mode) onCheckListChanged | function | | <empty function> | A callback function that is called every time user checked or unchecked an item(s) onHelp | function | | <empty function> | A callback function that is called when Help button of the component is clicked (Help button is visible only in a modal mode) helpDisabled | boolean | | true | Whether to show Help button in top bar of modal mode. Affects only to the visibility of Help button

Callback functions

Here is a list of HierarchySelectorView callback functions.

• onCancel() — Function is called when a user press Cancel button (the button is visible only when HierarchySelectorView is not in standalone mode)
• onCheckListChanged(resultList) — Function is called every time user check/uncheck items.
  • Parameters: resultList (array) — contains information about items, that are checked through the list(s) of hierarchies items, including data source provider ID.
  • resultList example:

    [
      {
        "id": 1,
        "name": "Company 1",
        "level": 1,
        "parentId": null,
        "parentIds": [],
        "isCheckedAll": true,
        "isChildren": true
      },
      {
        "id": 212,
        "name": "FI12 1234 1234 1234 1234 22",
        "level": 3,
        "parentId": 25,
        "parentIds": [2,25],
        "isCheckedAll": false,
        "isChildren": false
      },
    ]

A Level attribute's value starts from 1 (not zero-based). Property parentIds contains all parents of a checked node. parentId contains only the closest parent id. If there is no parent the property contains null value.

Styling

HierarchySelectorView component doesn't have borders, so a developer need a DIV wrapper container to embed this component suitable way.

Here an example of style that brings to HierarchySelectorView borders and 100% height:

.bank-account-view-component-wrapper {
  display: flex;
  flex-direction: column;
  height: 100%;
  padding: 0;
  background-color: #fff;
  border: 1px solid #ccc
}

HierarchySelectorDataSourceProvider

This is a class, that provides data handling for HierarchySelectorView and HierarchySelectorComboBox components

Methods

Method name | Parameter ---|--- constructor (promiseFunction) | promiseFunction — function that returns a promise object such an instance of Promise ES6 or other promise objects, for example axios

Example of creating a Data Source object with a promise function:

const dataSourceProvider = new HierarchySelectorDataSourceProvider(() => (
  new Promise((resolve) => {
    resolve(require('.../platform/components/hierarchy-selector/services/mockData.json'));
  })
));

HierarchySelectorComboBox

This component looks like a combo-box and starts to load data after a user click on a down-arrow of a combo-box to open a popover window. However, if there's pre-checked data and initial data is not loaded the component starts to load initial data immediately to set pre-checked items.

Properties

Property name | Type | Required | Default | Description --------------------------|--------------------------|----------|---------|--- dataSourceProvider | dataSourceProviderType | yes | | Data provider for the component hideOnPopoverBlur | boolean | | true | The property defines whether a popover panel of this component should be closed on blur event. If true, then the popover will be closed after blur event was triggered. inputName | string | | <empty string> | The property defines Name property of DOM input element that contains a group name of selected items. noSelectionText | string | | 'Nothing selected...' | The property defines a text that will appear in the combo box as a placeholder of an input element and in a tooltip when no element is selected. popoverOptions | popoverOptionsType | yes | | Defines options for the popover panel of the combo box component (see popoverOptionsType for more information). popoverVisible | boolean | | false | Defines whether the popover panel should be opened from the start. preCheckedGroupName | string | | Default group | Defines group name for pre-checked items (will be shown as a combo box text). If there are no pre-checked items this property is not used preCheckedItems | preCheckedItemsListShape | | null | Defines pre-checked items for the view tooltipPlacement | string | | 'bottom' | Defines a placement for a tooltip and should contain one of the values described for OverlayTrigger component of React-Bootstrap framework (property placement) viewOptions | viewOptionsType | yes | | Defines options for the HierarchySelectorView component (see viewOptionsType and HierarchySelectorView for more information). onSelect | function | | <empty function> | A callback function that is called when user has selected items in the popover panel or in HierarchySelectorView component. tooltipItemRenderFunction | function | | null | A custom rendering function to render tooltip list items differently than by default. The function has two parameters: first represents the current selected item for rendering and second one key attribute for item. isClearable | boolean | | false | Allow clearing of selected value, renders 'X' to dropdown element. Enable Select button when nothing is selected. isBusy | boolean | | false | Let component know if it should show spinner and disable actions

Callback functions

Here is a list of HierarchySelectorComboBox callback functions.

• onSelect (items, groupName, flags) — Function is called when a user has selected items in the popover panel or in HierarchySelectorView component.
  • Parameter items is an array and contains information about items, that were selected in the popover panel or in HierarchySelectorView component
  • Data structure of items parameter:

    [
      {
        "id": 1,
        "name": "Company 1",
        "level": 1,
        "parentId": null,
        "parentIds": [],
        "isCheckedAll": true,
        "isChildren": true
      },
    ]

is the same as in onCheckListChanged callback function of View component. For an item that is selected from a popover the value of level attribute is 0 (zero).

• Parameter groupName is a string that contains a group name user entered in a group name field of HierarchySelectorView component
• Parameter flags is object containing information flags
  • interactive flag is true when onSelect was initiated by user interaction, not for example preCheckedItems prop change.

Types

Here is a list of types additional to JavaScript standard types:

• dataSourceProviderType: instanceOf(HierarchySelectorDataSourceProvider)
• foundItemsShape: arrayOf(selectedItemsShape)
• hierarchyItemListShape: arrayOf(hierarchyItemShape)
• hierarchyItemShape:

  {
    id: number.isRequired,
    name: string.isRequired,
    children: arrayOf(hierarchyItemShape)
  }

• popoverOptionsType:

Property name | Type | Required | Default value | Description ---|---|:---:|---|--- btnOpenViewLabel | string or element | | 'Select...' | A text of open button of the component foundItemRenderFunction | function | | null | A custom rendering function to render the found items in hierarchy differently than by default searchPlaceHolder | string or element | | 'Search...' | A text of Search placeholder of the component searchTooltip | string or element | | null | A text of Search tooltip of the component, tooltip disabled if null pinnedGroupLabel | string or element | | 'Pinned items' | A text of Pinned items recentGroupLabel | string or element | | 'Recently used' | A text of Recent group

  {
    btnOpenViewLabel: oneOfType([string, element]),
    foundItemRenderFunction: func,
    searchPlaceHolder: string,
    searchTooltip: PropTypes.oneOfType([PropTypes.element, PropTypes.string]),
    pinnedGroupLabel: oneOfType([string, element]),
    recentGroupLabel: oneOfType([string, element]),    
  }

• preCheckedItemsListShape: arrayOf(preCheckedItemsShape)
• preCheckedItemsShape:

  {
    id: oneOfType([number, string]).isRequired,
    parentId: oneOfType([number, string]),
    isCheckedAll: bool,
  }

• Parameter parentId is required if a checked element is deeper than in the first level of a hierarchy.

• Parameter isCheckedAll means that all child-elements of the checked element are checked as well. If isCheckedAll is missed it means false value.

• selectedItemsShape - the same structure that described for callback function onCheckListChanged.

• viewOptionsType:

  {
    allLabel: oneOfType([string, element]),
    btnSelectLabel: oneOfType([string, element]),
    btnCancelLabel: oneOfType([string, element]),
    groupNameLabel: oneOfType([string, element]),
    groupNamePlaceHolder: string,
    listItemRenderFunction: func,
    searchPlaceHolder: oneOfType([string, element]),
    searchTooltip: PropTypes.oneOfType([PropTypes.element, PropTypes.string]),
    selectedItemListLabel: oneOfType([string, element]),
    selectedItemRenderFunction: func,
    showInModal: bool,
    title: oneOfType([string, element]).isRequired,
    hideGroupNameInput: bool,
  }

Code example

For a usage see example's source code:

• HierarchySelectorView component
• HierarchySelectorComboBox component