Skip to main content

Organization Unit Set Autocomplete

This component can be used whenever we want to select an Organization Unit Set - either for filtering, either for creating / updating other entities. The component itself is based on the Autocomplete from @material-ui/lab.

Props#

The Autocomplete only needs the ID (number) / IDs (number[]) of the selected set(s) and a way to modify that data, so that you can easily use that in requests outside of this component.

The component is flexible in terms of the data source used for getting the options and in terms of it being able to select only one, or multiple Organization Unit Sets(s) as well.

The typings are designed in a way that they won't allow invalid combinations of these props.

Prop types (click to show / hide)
// Simplified OUSet, which holds only what is absolutely necessary for the Autocomplete componentexport interface IOUSetAutocompleteItem {  ID: number;  Name: string;}
export interface IOUSetAutocompleteProps {  name?: string; // Name of the Input  label?: string; // Label of the Autocomplete  passive?: boolean; // Is the component read-only?  endIcon?: React.ReactNode; // additional icons displayed as the endAdornment of the Autocomplete field
  mixed?: boolean; // specifies if the selection can contain foreign IDs                   // (IDs that are not present as Autocomplete items)
  // Helper props for using the component with Formik  error?: boolean;  helperText?: string;  defaultHelperText?: string;  onBlur?: (    event: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>,  ) => void;
  // Use either one or the other, but not both (this will result in an error)!
      // Use these props for simpler applications,      // where one ListOrganizationUnitSets request yields all the necessary results      // (the component has an inner mechanism that will fetch the list for you)      familyName: string; // Family key for the ListOrganizationUnitSets service family      filters: Partial<EVA.Core.ListOrganizationUnitSetsFilter>; // filters for the request
      // Use this prop when the options array is more complex      // (just one request doesn't yield every necessary item)      // or is the result of the aggregation of multiple ListOrganizationUnitSets service responses      items: IOUSetAutocompleteItem[];
  // Use either one or the other, but not both (this will result in an error)!
      // Props to use for multi select      multi: true;      selectedOUSetIDs: number[] | undefined;      setSelectedOUSetIDs: (newIds: number[] | undefined) => void;
      // Props to use for single select      selectedOUSetID: number | undefined;      setSelectedOUSetID: (newId: number | undefined) => void;}

Usage#

Data source#

You can specify the source of the Organization Unit Set List that the component is using, which can be either the result a (filtered) request towards the ListOrganizationUnitSets service (in this case you can set the filters of the request) or a precompiled list of Organization Unit Sets (providing finer control over the options for more complex cases, such as the Organization Unit Set Selector).

Internal data source (for simple applications)#

When you can fetch the entire list of Organiation Unit Set options for the Autocomplete, you can leave the fetching part to the component: you only need to define a family key (for the ServiceFamily - it needs to be unique in the context of the application that you are working in) and the filter that you would like to use on the ListOrganizationUnitSets service request.

import { useState } from 'react';import { OUSetAutocomplete } from '@springtree/eva-suite-composite';
const Example = () => {  const [selectedOUSetID, setSelectedOUSetID] = useState<number | undefined>(undefined);
  return (    <OUSetAutocomplete      selectedOUSetID={selectedOUSetID}      setSelectedOUSetID={setSelectedOUSetID}      name="ExampleOUSetAutocomplete_InternalData"      filters={{ Types: [0, 1], HasSubsets: true  }}      familyName="ExampleOUSetAutocomplete:DataSource:Internal"      label="Example OUSet Autocomplete with internally fetched data"    />  );};

External data source#

Whenever you need a more complex list of Organization Unit Sets (e.g. you also want to add certain AdHoc sets to a list, without including all AdHoc sets), you can compile the list yourself, and pass it as a prop (in this case the component won't initiate service requests).

import { useMemo, useState } from 'react';import { OUSetAutocomplete, IOUSetAutocompleteItem } from '@springtree/eva-suite-composite';
const Example = () => {  const [selectedOUSetID, setSelectedOUSetID] = useState<number | undefined>(undefined);
  const { ouSetList } = useSpecialOUSetList();
  // You need to extract the relevant information from your list  const ouSetAutocompleteItems = useMemo<IOUSetAutocompleteItem[] | undefined>(    () => ouSetList?.map(      (ouSet) => ({ ID: ouSet.ID, Name: ouSet.Name }),    ),    [ouSetList],  );
  return (    <OUSetAutocomplete      selectedOUSetID={selectedOUSetID}      items={ouSetAutocompleteItems ?? []}      setSelectedOUSetID={setSelectedOUSetID}      name="ExampleOUSetAutocomplete_ExtrenalData"      label="Example OUSet Autocomplete with externally fetched data"    />  );};

Single or Multi select#

Single select#

Use these props when you want the component to operate on a single Organization Unit Set (number | undefined).

import { useState } from 'react';import { OUSetAutocomplete } from '@springtree/eva-suite-composite';
const Example = () => {  const [selectedOUSetID, setSelectedOUSetID] = useState<number | undefined>(undefined);
  return (    <OUSetAutocomplete      selectedOUSetID={selectedOUSetID}      setSelectedOUSetID={setSelectedOUSetID}      name="ExampleOUSetAutocomplete_SingleSelect"      filters={{ Types: [0, 1], HasSubsets: true  }}      familyName="ExampleOUSetAutocomplete:Selection:Single"      label="Example OUSet Autocomplete with single selection"    />  );};

Multi select#

When you want to select multiple Organization Unit Sets (number[] | undefined), you can use the following props:

import { useState } from 'react';import { OUSetAutocomplete } from '@springtree/eva-suite-composite';
const Example = () => {  const [selectedOUSetIDs, setSelectedOUSetIDs] = useState<number[] | undefined>(undefined);
  return (    <OUSetAutocomplete      multi      selectedOUSetIDs={selectedOUSetIDs}      setSelectedOUSetIDs={setSelectedOUSetIDs}      name="ExampleOUSetAutocomplete_MultiSelect"      filters={{ Types: [0, 1], HasSubsets: true  }}      familyName="ExampleOUSetAutocomplete:Selection:Multi"      label="Example OUSet Autocomplete with multi selection"    />  );};
tip

The aforementioned props can be used in combination (e.g. multi select with external data source).

Mixed selection#

This behaviour can be controlled by the mixed?: boolean property, and it only affects the behaviour of the component if it is in multi-select mode.

If this prop is set to true, then the component will allow foreign Organization Unit Set IDs (IDs that are ont present in the Autocomplete items list) to be present in the selection. This means that whenever the user selects, deselects or clears the selection, then these operations will not affect the items that are not present in the Autocomplete items list.

On the other hand, when this prop is unset / set to false, then the foreign IDs will be discarded upon selection operations.

Example:

import { useState } from 'react';import { OUSetAutocomplete } from '@springtree/eva-suite-composite';
const Example = () => {  const [selectedOUSetIDs, setSelectedOUSetIDs] = useState<IOUSetAutocompleteItem[] | undefined>(    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],  );
  const autocompleteItems = useMemo<IOUSetAutocompleteItem[] | undefined>(    () => [1, 4, 5, 6].map(      (ouSetId) => ({ ID: ouSetId, Name: `OUSet #${ouSetId}` }),    ),    [ouSetList],  );
  const 
  return (    <OUSetAutocomplete      multi      options={{ mixed: true }}      items={autocompleteItems}      selectedOUSetIDs={selectedOUSetIDs}      setSelectedOUSetIDs={setSelectedOUSetIDs}      familyName="ExampleOUSetAutocomplete:Selection:Multi:Mixed"      label="Example OUSet Autocomplete with mixed multi selection"    />  );};