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

DspActionModule

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.

DspCoreModule

Services for API requests

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

DspSearchModule

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.

DspViewerModule

Resources, Properties, Lists, Value components

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


Installation

npm install @dasch-swiss/dsp-ui

Dependencies

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

Setup

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 config.dev.json file in an additional folder src/config/:

{
  "apiProtocol": "http",
  "apiHost": "0.0.0.0",
  "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 config.prod.json. 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/favicon.ico",
    "src/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';

@Injectable({
  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(
        dspApiConfig.apiProtocol,
        dspApiConfig.apiHost,
        dspApiConfig.apiPort,
        dspApiConfig.apiPath,
        dspApiConfig.jsonWebToken,
        dspApiConfig.logErrors
      );

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

      resolve();
    });
  }
}

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';
...

@NgModule({
  declarations: [
    AppComponent,
    ProjectsComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    DspCoreModule,      // <-- add the dsp-ui modules here
    DspViewerModule
  ],
  providers: [
      // add the following code block
    AppInitService,
    {
      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) {
  enableProdMode();
}

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

fetch(`config/config.${environment.name}.json`)
  .then(response => response.json())
  .then(config => {
    if (!config) {
      bootstrapFailed(config);
      return;
    }

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

    platformBrowserDynamic()
      .bootstrapModule(AppModule)
      .catch(err => bootstrapFailed(err));
  })
  .catch(bootstrapFailed);

Usage

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

@NgModule({
  declarations: [
    AppComponent,
    ProjectsComponent
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    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.