Skip to content

DSP-UI library

User Interface library for DSP-API

DSP-UI library is published on npmJS. DSP-UI contains 4 modules: core, viewer, search and action.

The modules help create a GUI to allow the user to use DSP-API in a quick and simple way from within a web application. The modules are written in Typescript for use with Angular (version 9). We decided to style components and directives with Angular Material design.

DSP-UI-LIB implements DSP-JS-LIB to connect with DSP-API. DSP-API is a software framework for storing, sharing, and working with primary sources and data in the humanities.

DSP-UI requires DSP-API version ^12.0.0

Library modules


Special pipes and buttons

DspActionModule contains special pipes to sort lists or to get the index key in arrays, but also directives and components for images, sort buttons and s.o.


Services for API requests

DspCoreModule is a configuration handler for @knora/api which offers all the services to make DSP-API requests.


Full search panel

DspSearchModule allows to make full text or extended searches in DSP-API. Filter by resource class and its properties related to an ontology.


Resources, Properties, Lists, Value components

DspViewerModule contains object components to show a resource class representation, the property gui-elements and various view frameworks.


npm install @dasch-swiss/dsp-ui


The module has the following package dependencies, which you also have to install.


The module supports runtime config to load the API configuration on load as opposed to on build. This helps run an App as a docker image in various environments. However, this requires some modifications in your app. We suggest building the app with @angular/cli.

First, let's make a file in an additional folder src/config/:

  "apiProtocol": "http",
  "apiHost": "",
  "apiPort": 3333,
  "apiPath": "",
  "jsonWebToken": "",
  "logErrors": true

It's possible to create several config files e.g. one for productive use. In this case, logErrors should be set to false and the filename would be In the environment files, we have to add the corresponding name:

export const environment = {
  name: 'dev',      // <-- add the name 'dev', 'prod', etc. here.
  production: false

The config files have to be integrated in angular.json in all "assets"-sections:

"assets": [
    "src/config"    <-- add this line and do not forget the comma on the previous line

Then we can make a service that will fetch the configs:

ng generate service app-init
import { Injectable } from '@angular/core';
import { KnoraApiConfig, KnoraApiConnection } from '@knora/api';

  providedIn: 'root'
export class AppInitService {

  static dspApiConnection: KnoraApiConnection;

  static dspApiConfig: KnoraApiConfig;

  constructor() { }

  Init() {

    return new Promise<void>((resolve) => {

      // get api config information from temp storage
      const dspApiConfig: KnoraApiConfig = window['tempConfigStorage'] as KnoraApiConfig;

      // init dsp-api configuration
      AppInitService.dspApiConfig = new KnoraApiConfig(

      // set knora-api connection configuration
      AppInitService.dspApiConnection = new KnoraApiConnection(AppInitService.dspApiConfig);


Once we have this service, we have to edit the app.module.ts with a function to load the config:

export function initializeApp(appInitService: AppInitService) {
  return (): Promise<any> => {
    return appInitService.Init();

Provide it in the main module and include the desired DSP-UI modules in the imports:

import { DspApiConfigToken, DspApiConnectionToken, DspCoreModule, DspViewerModule } from '@dasch-swiss/dsp-ui';

  declarations: [
  imports: [
    DspCoreModule,      // <-- add the dsp-ui modules here
  providers: [
      // add the following code block
      provide: APP_INITIALIZER,
      useFactory: initializeApp,
      deps: [AppInitService],
      multi: true
      provide: DspApiConfigToken,
      useFactory: () => AppInitService.dspApiConfig
      provide: DspApiConnectionToken,
      useFactory: () => AppInitService.dspApiConnection
  bootstrap: [AppComponent]
export class AppModule { }

Do not forget to import APP_INITIALIZER from @angular/core and the desired DSP-UI modules from @dasch-swiss/dsp-ui.

Finally, the main.ts file must be modified to load the environment specific config file and test that the config is correct:

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

if (environment.production) {

function bootstrapFailed(result) {
  console.error('bootstrap-fail! Config is missing or api parameters are not defined', result);

  .then(response => response.json())
  .then(config => {
    if (!config) {

    // store the response somewhere that the AppInitService can read it.
    window['tempConfigStorage'] = config;

      .catch(err => bootstrapFailed(err));


Add the desired modules from DSP-UI to the app.module.ts. DspCoreModule must be imported at the very minimum!

  declarations: [
  imports: [
    DspCoreModule        // <-- add the dsp-ui core module here
  providers: [ ... ]    // <-- add providers as mentioned in section above
  bootstrap: [AppComponent]
export class AppModule { }

For more usage examples, check the corresponding DSP-UI module documentation.

Contribute to develop DSP-UI modules

If you want to contribute to develop DSP-UI modules with us, please consult the contribution guideline.

DSP-API and DSP-UI-LIB are free software, released under GNU Affero General Public license.

It is developed by the design team of the Data and Service Center for the Humanities DaSCH at the University of Basel.