@boewa-software/react-searchbar v3.2.0

React Searchbar

ACHTUNG: VERSION 3.0.0 ENTHÄLT NOCH EINEN BUG IM CHOICEFILTER, DER IN VERSION 3.0.1 BEHOBEN WURDE.

Installation

Das Modul kann via NPM zu einem existierenden Projekt hinzugefügt werden:

$ npm install @boewa-software/react-searchbar

Usage

Die Nutzung erfolgt als klassische React-Komponenten.

import {
  ChoiceFilter,
  DatePickerFilter,
  DateTimePickerFilter,
  FilterPicker,
  NumberFilter,
  TextFilter,
  ValueFilter,
  Searchbar,
} from '@boewa-software/react-searchbar';

CSS

Optional gibt es im dist Ordner auch eine CSS Datei, die einige Default Styles der Searchbar definiert.

import '@boewa-software/react-searchbar/dist/css/react-searchbar.min.css';

HTML

Die Searchbar generiert folgendes Markup:

<div class="searchbar-wrapper">
  <div class="searchbar">
    <ul class="searchbar-filter-list">
      <!-- START Spezielles Markup für den FilterPicker -->
      <li class="searchbar-filter searchbar-search">
        <label for="search" class="visually-hidden">Suchbegriff</label>
        <input
          type="text"
          class="form-control"
          placeholder="Search"
          id="search"
        />
        <ul class="dropdown-menu show">
          <li>
            <button class="dropdown-item">
              Press Enter or click to search
            </button>
          </li>
          <li>
            <button class="dropdown-item">Filter by <strong>X</strong></button>
          </li>
          <li>
            <button class="dropdown-item">Filter by <strong>Y</strong></button>
          </li>
        </ul>
      </li>
      <!-- ENDE Spezielles Markup für den FilterPicker -->
      <li class="searchbar-filter">
        <label class="searchbar-filter-label" for="container">Container</label>
        <div class="searchbar-filter-input-wrapper">
          <!-- Hier wird der gesetzte FilterComponent hineingerendert -->
        </div>
        <button class="btn btn-xs btn-icon btn-search btn-secondary">
          <span class="visually-hidden">Filter entfernen</span>
        </button>
      </li>
    </ul>
  </div>
</div>

Types

Falls explizitere interne Typescript-Types benötigt werden, können diese wie folgt importiert werden:

import type {
  FilterComponentProps,
  FilterProps,
  Filters,
  FilterSuggestionProps,
  RemoveFilterButtonComponentProps,
  SetValue,
  UnknownFilter,
  UseFilter,
  SearchbarContextProps,
  SearchbarProps,
  SearchbarRef,
} from '@boewa-software/react-searchbar';

Searchbar

Dies ist die eigentliche Searchbar und muss mit einem Array von Filterobjekten initialisiert werden.

Props:

• filters : array, required

  Array mit Filter-Deklarationen in folgendem Format:

  type Filters = {
    name: string;
    label: string;
    showLabel: boolean;
    allowRemove: boolean; // Entscheidet ob der RemoveFilterButton angezeigt wird
    filterComponent: React.ElementType<any>;
    value: any;
    alwaysVisible?: boolean; // Entscheidet ob der Filter immer angezeigt und mit abgeschickt wird
    isFilterPicker?: boolean; // Nötig, da der FilterPicker spezielles Markup generiert
    hideInFilterPicker?: boolean; // Entscheidet ob der Filter im FilterPicker angezeigt wird
    [x: string]: any; // Alle anderen custom Attribute werden an den FilterComponent übergeben
  }[];

• submitButtonComponent : React-Komponente, optional

  Props:

  interface SubmitButtonComponentProps {
    onClick: () => void; // Funktion die die Suche ausführt
  }

  Komponente die den Submit-Button darstellt. Eine Default-Komponente wird mitgeliefert.

• removeFilterButtonComponent : React-Komponente, optional

  Props:

  interface RemoveFilterButtonComponentProps {
    name: string;
    removeFilter: (name: string) => void; // Funktion die den Filter entfernt
  }

  Komponente die den Remove-Filter-Button darstellt. Eine Default-Komponente wird mitgeliefert.

• ref : React.RefObject, optional

  interface SearchbarRef {
    setValue: SetValue;
    removeFilter: (name: string) => void;
    submitSearch: () => void;
    addUnknownFilter: (unknownFilter: UnknownFilter) => void;
    resetFilters: () => void;
  }

  RefObject der Searchbar. Wird benötigt um den inneren SearchbarState zu manipulieren. Die oben zu sehenen Funktionen werden durch das RefObject zur Verfügung gestellt.

  Beispielnutzung:

  const searchBarRef = useRef<SearchbarRef>(null);
  if (!searchBarRef.current) return;
  searchbarRef.current.setValue('search[query]', 'test');
  searchbarRef.current.submitSearch();
  searchbarRef.current.resetFilters();

FilterPicker

Der FilterPicker baut ein Dropdown mit allen verfügbaren Filtern und ist selber auch ein Filter.

Das Filter Objekt für den FilterPicker könnte beispielhaft so aussehen:

{
  "name": "search[query]",
  "label": "Search",
  "allowRemove": false,
  "showLabel": false,
  "alwaysVisible": true,
  "filterComponent": "FilterPicker",
  "isFilterPicker": true,
  "value": null
}

Hinweise zu FilterComponents

Die FilterComponents erhalten folgende Props:

interface FilterComponentProps {
  name: string; // Name des Filters
  value: any; // Wert des Filters
  setValue: (name: string, value: any) => void; // setzt den Wert des Filters
  submitSearch: () => void; // setzt die url search params und führt die Suche aus
  focusedFilter: string | null; // Name des aktuell zu fokussierenden Filters
  [x: string]: any; // hier werden wie oben beschrieben alle custom Attribute aus dem Parent Filter Objekt übergeben
}