cockpit-core v7.3.10

cockpit-core

This package provides an Angular library with the core features used by a Cockpit NextGen application. Cockpit NextGen is the name of a set of web applications used by the Scientific Network South Tyrol as intranet portal.

This documentations describes the API of the services that are exposed by the library, if you are interested in developing the library itself, or if you need to understand the content of this code repository, please refer to ./doc/development.md.

The quickest way to get ready to work on a new Cockpit NextGen project is to start from our template project.

Services

It follows an overview of the services available.

Cockpit Service

A general purpose service for app-wide settings and functions.

The service keeps a public reference to three attributes:

• config: any: Reference to the app config, contained in environment.ts
• appName: string: Human readable name of the app
• appIcon: string: The icon of the app - ask Yuval which icons are available, or to add a new one

Note: before being used should be initialized calling init(). This is usually done only once for the app, in app.component in method ngOnInit.

Data Service

DataService is simple way to store any kind of javascript object in the browser's local storage. Stored objects are persisted indefinitely, and can even be accessed by different apps, provided that they reside under the same domain (e.g. cockpit.scientificnet.org). DataService provides two methods:

• set(key: string, value: any): void: to store any kind of value
• get<T>(key: string): any: to retrieve a value of a given type T (if nothing is found it returns undefined)
• remove(key: string): void: to delete an object given its key.

Profile Service

The ProfileService is used to get user-specific data with respect of the current logged or impersonated user. It has two primary purposes:

• getProfile(): Observable<Profile>: returns an observable to the profile
• fetchUserPicture(): Observable<any>: returns an observable to a stream of bytes representing the user's picture

Mail Service

The MailService sends email messages. It authenticates against the Microsoft Graph's endpoint with the current logged username (does not support impersonation). It's only interface is send():

send(
  to: string | string[],
  subject: string,
  body: string,
  cc: string | string[] = []
): void

Navigation Service

The navigation in the sidebar can be changed at run-time using NavigationService. You can get the current links in the navigation and you can set new ones. The navigation can also be configured statically, which is preferable if you don't need to change it at run time. See section Configuration in the documentation of the template project.

• getSidebarLinks(): MenuLink[]
• setSidebarLinks(links: MenuLink[]): void

Note: in the next release of this template, there will be the possibility to have localized navigation. For the moment just use a default, english, one.

Message Service

The message service allows to dynamically display messages to the end user. Messages are shown in the bottom-right corner of the screen. The Message Service exposes only one method: push().

Messages can be displayed with different severity levels: success, info, warning, danger. The default severity level is "danger".

Messages can optionally have a custom icon. All icons part of Bootstrap's Glyphicons are available. Only the last part of the CSS class has to be taken into account. So, for example, if you use the string "ok", you will get glyphicon glyphicon-ok.

If you pass an error object (e.g. result of a thrown exception), it will be logged in the browser's console, but only if the current user is an administrator.

public push(
  message: string,
  error?: any,
  severity: 'success' | 'info' | 'warning' | 'danger' = 'danger',
  icon: string = 'info-sign'
): void

Automatic handling of error messages

A nice feature offered by ErrorInterceptor, is to automatically push new error messages to the Message Service.
If you add the Error Interceptor to your App module, it will automatically intercept all HTTP traffic that is sent/received using Angular's HttpClient.
By intercepting an HTTP response with an error status (4XX), and containing a header "X-Error-NonBlocking", the interceptor will push a new message to the Message Service.
Therefore, if you can develop your webservice to return a "X-Error-NonBlocking" header in case of error, the response body will automatically shown on the user interface.

Spinner Service

The Spinner Service is used to control the display/hide state of a spinner component: a page-blocking spinning wheel placed in the middle of the page which is used to tell the user that something is loading, and to prevent the user from clicking anything on the page.

The Spinner Service exposes two methods:

• spin() to start the spinner
• stop() to stop it

Translation Service

The Translation Service helps you to translate "runtime" translations where the text cannot be captured from the template by the i18n's angular service. An example is when you need to push messages (see Message Service) where the key is passed via typescript. Do not use this service when you can capture the text from the template.

The Translation Service exposes one method:

• getTranslations() that returns the list of key-values based on your translations.ts of the current language.

Example:

  constructor(private translationSvc: TranslationService) { }

  ngOnInit() {
    const translations = this.translationSvc.getTranslations();
    console.log(translations['hello_world']); // <-- return "Ciao Mondo!" if the current lang is IT
  }

The translations.ts file is located under the folder src/enviroments.