Skip to content

Latest commit

 

History

History
142 lines (107 loc) · 7.71 KB

README.md

File metadata and controls

142 lines (107 loc) · 7.71 KB

FCS SRU Aggregator UI

Technologies

The frontend uses the following technologies:

For development and building a few additional dependencies are required:

Features

  • Modern, mobile-friendly, dark-mode, accessibility (ARIA) support
  • Single¹ SPA bundle for easy integration
  • Various usability features like fuzzy filtering, ...

¹ The build process will generate multiple JS and CSS files to split application code from vendor code but those files only need to be included as scripts/styles in a static index.html page without requiring any complicated server setup.

Requirements

  • Node 18+ (?)

How to deploy

Building

Running the following command will create a fully static bundle that is ready to be deployed. The build artifacts will be placed into the dist/ folder. The index.html file is the entry point with all dependencies (scripts, styles, images and other assets) in the lib/ subfolder.

npm run build

To generate a single bundle build (one script and one style file, with picture assets) use the following command. This will also disable dynamic imports.

npm run build:bundle

An overview over all the dependency modules and code files will be generated by rollup-plugin-visualizer and can be found in either bundle-visualization.html or dist/bundle-visualization.html depending on the plugin configuration.

Configuration

The bundle can be pre-configured by adjusting the import.meta.env. constants found in the vite.config.ts configuration file.

  • "branding" related configs:
    • HEAD_TITLE: the base application title for the browser
    • CONTACT_ADDRESS: the contact email address for users to get in contact with
    • TERMS_AND_DISCLAIMER_ADDRESS: the webpage with information about the website like disclaimer, imprint, GDPR, ...
    • CANONCIAL_URL: the canonical URL to the application (head meta information), unused for now?
  • deployment base configuration
    • DEPLOY_PATH: the (sub-)path the application is served from, by default / for the root
    • API_URL: the backend FCS SRU Aggregator REST API endpoint, required!
    • VALIDATOR_URL: the URL to the FCS Endpoint Validator
  • optional features
    • SHOW_SEARCH_RESULT_LINK: boolean, whether to display a semi-permanent search results link, use only for development to avoid confusion
    • FEATURE_TRACKING_MATOMO: boolean, whether to include Matomo/Piwik tracking/statistics calls
      • FEATURE_TRACKING_MATOMO_PARAMS: parameters for tracking setup, set with JSON.stringify({}) where the parameter object {} should contain the following entries:
        • siteId: number, required, for setSiteId
        • trackerUrl: URL for tracking server, required, for setTrackerUrl, likely something like <baseUrl>/matomo.php
        • enableLinkTracking: boolean, optional, by default true, can be disabled
        • domains: string[], optional, can be a list of to be considered "local" domain names, for setDomains
        • userId: string, optional, will be hashed with cyrb53, for setUserId
        • srcUrl: URL for JS script source to load Matomo/Piwik script, required, likely something like <baseUrl>/matomo.js
        • NOTE: if not set or any required value is likely invalid, then tracking will not be configured!
    • FEATURE_QUERY_BUILDER: boolean, whether to include a Visual Query Builder (FCS-QL). If not specified (or explicitely set to true) then it will be excluded from the generated build. Enabling it, multiple output files will be generated, a vendor/antlr.js chunk as well as *-query-builder-*.{js,css} files that will be dynamically loaded when the UI requires them.
    • FEATURE_LAZY_LOADING: boolean, whether to enable lazy loading of some optional component using dynamic imports, if not set to true (truthy value) then all optional components will be included statically (might be tree-shaken).

Runtime configuration can be set using the window.MyAggregator object and needs to be included before the application script fcs-sru-aggregator-ui-X.Y.Z.js is being loaded. They are completely optional but can be used to override bundle configuration.

  • DEPLOY_PATH: the basename of the application, e.g. if deployed on some subpath like example.org/aggregator/ use /aggregator, by default /
  • API_URL: the base URL to the FCS SRU Aggregator REST API, e.g. https://contentsearch.clarin.eu/rest/
  • VALIDATOR_URL: the base URL to the FCS Endpoint Validator, e.g. https://www.clarin.eu/fcsvalidator/
  • SHOW_SEARCH_RESULT_LINK: boolean (true/false) for whether to display a semi-permanent link to search results using the internal searchID

Development

Based on React + TypeScript + Vite template (npm create vite@latest), a minimal setup to get React working in Vite with HMR and some ESLint rules. Uses the @vitejs/plugin-react uses Babel plugin for Fast Refresh.

For local testing run:

npm run dev

Update dependencies

  • Check possible upgrades with npx npm-check-updates
  • Check system information (for bug reports etc.) npx envinfo --system --npmPackages --binaries --browsers

Expanding the ESLint configuration (TODO)

If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:

  • Configure the top-level parserOptions property like this:
export default tseslint.config({
  languageOptions: {
    // other options...
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
})
  • Replace tseslint.configs.recommended to tseslint.configs.recommendedTypeChecked or tseslint.configs.strictTypeChecked
  • Optionally add ...tseslint.configs.stylisticTypeChecked
  • Install eslint-plugin-react and update the config:
// eslint.config.js
import react from 'eslint-plugin-react'

export default tseslint.config({
  // Set the react version
  settings: { react: { version: '18.3' } },
  plugins: {
    // Add the react plugin
    react,
  },
  rules: {
    // other rules...
    // Enable its recommended rules
    ...react.configs.recommended.rules,
    ...react.configs['jsx-runtime'].rules,
  },
})