# search-filters

Studyportals library of filter components to be used in Search pages e.g. StudySearch

## Available filters

- Attendance
- Certification-type
- Degree-type
- Discipline
- Duration
- Education-level
- Educational-form
- Format
- Location
- Area
- Country
- Continent
- Special-programmes
- Tuition-fee
- University

## Other components

- SearchFilterContainer (styling included)
- SelectedFilters (clear filters button and filter tags)

## Using filters in your project

Each SearchPage component must supply its own [IFilterProvider](#ifilterprovider) implementation by leveraging the provide / inject mechanism in Vue when using any Filter.

Each SearchPage component must supply its own [ILocationFilterProvider](#ilocationfilterprovider) implementation by leveraging the provide / inject mechanism in Vue when using

- CountryFilter
- LocationFilter (which is using CountryFilter)

Each SearchPage component must supply its own [ICurrencyFilterProvider](#icurrencyfilterprovider) implementation by leveraging the provide / inject mechanism in Vue when using

- AttendanceFilter
- TuitionFeeFilter

Each SearchPage component must supply its own [IUniversityFilterProvider](#iuniversityfilterprovider) implementation by leveraging the provide / inject mechanism in Vue when using

- UniversityFilter

Every Filter Component has a well-known key that integrating applications must use to configure the injection.
The only requirements for the correlation key are:

1. Uniqueness within the context of a SearchPage component (i.e., must not be shared by multiple
   filters)
2. Stability within the lifecycle of the SearchPage component (i.e., must not change)

## Interfaces

### IFilterProvider

```typescript
interface IFilterProvider {
	readonly trackedProduct: Product;
	readonly displayFacets: boolean;
	applySuggestion?: (payload: ISuggestionPayload) => Promise<void>;
	getCountOfResultsForSuggestion?: (payload: ISuggestionPayload) => Promise<number>;
	getFilterKeySelection: () => readonly FilterKey[];
	getFilterSelection: (key: FilterKey) => readonly string[];
	getFilterOptionInformation: (key: FilterKey) => readonly FilterOptionInformation[];
	getFilterOptionInformationById: (key: FilterKey, id: string) => FilterOptionInformation | null;
	getFacet: (key: FilterKey, optionValue: string) => number | null;
	isFilterCollapsed: (key: FilterKey) => boolean;
	isFilterRequired: (key: FilterKey) => boolean;
	toggleFilterExpandability: (key: FilterKey) => void;
	processFilterSelection: (payload: IFilterPayload) => Promise<void>;
	processFiltersSelection: (payload: IFilterPayload[]) => Promise<void>;
	clearFilter: (key: FilterKey) => Promise<void>;
	clearFilters: (keys: FilterKey[]) => Promise<void>;
	clearSelection: (payload: IFilterPayload[]) => Promise<void>;
}
```

### ICurrencyFilterProvider

```typescript
interface ICurrencyFilterProvider {
	getCurrency: () => string;
	requestCurrencyChange: () => void;
	currencyConvert: (originalAmount: number, originalCurrency: string, targetCurrency?: string) => Promise<number>;
	trackCustomClickEvent: (label: string, property: string) => void;
	getAreDependenciesLoaded: () => boolean;
}
```

### ILocationFilterProvider

```typescript
interface ILocationFilterProvider {
	readonly includeContinents: boolean;
	identifyAreasFor: (countryId: string) => string[];
	identifyTopCountries: () => string[];
	identifyCountryFor: (areaId: string) => string;
}
```

### IUniversityFilterProvider

```typescript
interface IUniversityFilterProvider {
	retrieveUniversityInfo(id: string): Promise<IUniversityInfo | null>;
}
```

## Tags hierarchy

![tags](./assets/image.png)

## Deployment

Use the `npm` CLI to version and publish the package.

### Unstable

You may need to publish a number of unstable versions while working on a new feature. You first need to select the new version of the package and then append the prerelease identifier. You can use the `preid` to contextualize the versions. The resulting version should match the pattern `a.b.c-<preid>.0` or `a.b.c.-0` if a `preid` is not necessary. You can use `npm version {premajor|preminor|prepatch} --preid=<feature>` or make the adjustments manually. Subsequent unstable versions can be incremented using `npm version prerelease`. You can publish the version using `npm publish --tag beta`.

Consider publishing unstable versions before the feature has been peer reviewed.

### Stable

Use `npm version {major|minor|patch}`, or adjust the version manually. Use `npm publish` to publish the package.

### DLL

The DLL package must be released for each stable version of the package.

1. Update the reference to the package in `dll/package.json`
2. Adjust the version of the DLL package in `dll/package.json`
3. Run `npm run deploy-dll` from the base directory, or `npm publish` from the `dll` directory; for unstable releases use `npm run deploy-dll-beta` from the base directory, or `npm publish --tag beta` from the `dll` directory