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 implementation by leveraging the provide / inject mechanism in Vue when using any Filter.

Each SearchPage component must supply its own 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 implementation by leveraging the provide / inject mechanism in Vue when using

• AttendanceFilter
• TuitionFeeFilter

Each SearchPage component must supply its own 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

interface IFilterProvider {
  readonly trackedProduct: Product;
  readonly displayFacets: boolean;
  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

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

ILocationFilterProvider

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

IUniversityFilterProvider

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

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

ESM modules in Jest

Some of our packages are published as ECMAScript modules. This is the official specification on packaging JavaScript code.

Jest does not natively support ESM modules. Attempting the import instruction will result in the following error: SyntaxError: Cannot use import statement outside a module.

To resolve this, add the names of your ESM dependencies in the esmPackages array in the jest.config.js file. This will instruct Jest to transform the ESM modules into CommonJS modules using jest-esm-transformer.

⚠️ The esmPackages array is used to generate a regular expression that matches file paths. Linux and Window use different path separators. @studyportals/<package_name> is a valid path in Linux, but Windows expects the path to be formatted as @studyportals\<package_name>. Use the [/\\\\] separator to cover both cases: @studyportals[/\\\\]<package_name>.