From 48ffb2105fdbef0765fdbf90b6c6098f978fa84e Mon Sep 17 00:00:00 2001 From: lotte Date: Fri, 4 Sep 2020 12:30:29 +0200 Subject: [PATCH] added missing typedoc --- .../shared/cookies/browser-klaro.service.ts | 78 ++++++++++++++++++- src/app/shared/cookies/klaro-configuration.ts | 7 ++ src/app/shared/cookies/klaro.service.ts | 10 +++ src/assets/i18n/en.json5 | 2 +- 4 files changed, 94 insertions(+), 3 deletions(-) diff --git a/src/app/shared/cookies/browser-klaro.service.ts b/src/app/shared/cookies/browser-klaro.service.ts index 8ca495de36..bf5a51e674 100644 --- a/src/app/shared/cookies/browser-klaro.service.ts +++ b/src/app/shared/cookies/browser-klaro.service.ts @@ -14,15 +14,39 @@ import { cloneDeep } from 'lodash'; import { ANONYMOUS_STORAGE_NAME_KLARO, klaroConfiguration } from './klaro-configuration'; import { Operation } from 'fast-json-patch'; +/** + * Cookie for has_agreed_end_user + */ export const HAS_AGREED_END_USER = 'dsHasAgreedEndUser'; + +/** + * Metadata field to store a user's cookie consent preferences in + */ export const COOKIE_MDFIELD = 'dspace.agreements.cookies'; +/** + * Prefix key for app title messages + */ const cookieNameMessagePrefix = 'cookies.consent.app.title.'; + +/** + * Prefix key for app description messages + */ const cookieDescriptionMessagePrefix = 'cookies.consent.app.description.'; + +/** + * Prefix key for app purpose messages + */ const cookiePurposeMessagePrefix = 'cookies.consent.purpose.'; +/** + * Browser implementation for the KlaroService, representing a service for handling Klaro consent preferences and UI + */ @Injectable() export class BrowserKlaroService extends KlaroService { + /** + * Initial Klaro configuration + */ klaroConfig = klaroConfiguration; constructor( @@ -32,9 +56,14 @@ export class BrowserKlaroService extends KlaroService { private cookieService: CookieService) { super(); } - + /** + * Initializes the service: + * - Retrieves the current authenticated user + * - Checks if the translation service is ready + * - Initialize configuration for users + * - Add and translate klaro configuration messages + */ initialize() { - console.log(this.klaroConfig) this.translateService.setDefaultLang(environment.defaultLanguage); const user$: Observable = this.getUser$(); @@ -66,6 +95,10 @@ export class BrowserKlaroService extends KlaroService { } + /** + * Initialize configuration for the logged in user + * @param user The authenticated user + */ private initializeUser(user: EPerson) { this.klaroConfig.callback = (consent, app) => this.updateSettingsForUsers(user); this.klaroConfig.storageName = this.getStorageName(user.uuid); @@ -79,6 +112,10 @@ export class BrowserKlaroService extends KlaroService { } } + /** + * Retrieves the currently logged in user + * Returns undefined when no one is logged in + */ private getUser$() { return this.authService.isAuthenticated() .pipe( @@ -93,14 +130,26 @@ export class BrowserKlaroService extends KlaroService { ); } + /** + * Create a title translation key + * @param title + */ private getTitleTranslation(title: string) { return cookieNameMessagePrefix + title; } + /** + * Create a description translation key + * @param description + */ private getDescriptionTranslation(description: string) { return cookieDescriptionMessagePrefix + description; } + /** + * Create a purpose translation key + * @param purpose + */ private getPurposeTranslation(purpose: string) { return cookiePurposeMessagePrefix + purpose; } @@ -136,6 +185,10 @@ export class BrowserKlaroService extends KlaroService { this.translate(this.klaroConfig.translations.en); } + /** + * Translate string values in an object + * @param object The object containing translation keys + */ private translate(object) { if (typeof (object) === 'string') { return this.translateService.instant(object); @@ -146,11 +199,20 @@ export class BrowserKlaroService extends KlaroService { return object; } + /** + * Retrieves the stored Klaro consent settings for a user + * @param user The user to resolve the consent for + */ getSettingsForUser(user: EPerson) { const mdValue = user.firstMetadataValue(COOKIE_MDFIELD); return hasValue(mdValue) ? JSON.parse(mdValue) : undefined; } + /** + * Stores the Klaro consent settings for a user in a metadata field + * @param user The user to save the settings for + * @param config The consent settings for the user to save + */ setSettingsForUser(user: EPerson, config: object) { user.setMetadata(COOKIE_MDFIELD, undefined, JSON.stringify(config)); this.ePersonService.createPatchFromCache(user) @@ -166,14 +228,26 @@ export class BrowserKlaroService extends KlaroService { ).subscribe(); } + /** + * Restores the users consent settings cookie based on the user's stored consent settings + * @param user The user to save the settings for + */ restoreSettingsForUsers(user: EPerson) { this.cookieService.set(this.getStorageName(user.uuid), this.getSettingsForUser(user)); } + /** + * Stores the consent settings for a user based on the current cookie for this user + * @param user + */ updateSettingsForUsers(user: EPerson) { this.setSettingsForUser(user, this.cookieService.get(this.getStorageName(user.uuid))) } + /** + * Create the storage name for klaro cookies based on the user's identifier + * @param identifier The user's uuid + */ getStorageName(identifier: string) { return 'klaro-' + identifier } diff --git a/src/app/shared/cookies/klaro-configuration.ts b/src/app/shared/cookies/klaro-configuration.ts index 45b5f8013f..04a870a6f4 100644 --- a/src/app/shared/cookies/klaro-configuration.ts +++ b/src/app/shared/cookies/klaro-configuration.ts @@ -3,8 +3,15 @@ import { IMPERSONATING_COOKIE, REDIRECT_COOKIE } from '../../core/auth/auth.serv import { LANG_COOKIE } from '../../core/locale/locale.service'; import { HAS_AGREED_END_USER } from './browser-klaro.service'; +/** + * Storage name used to store klaro cookie + */ export const ANONYMOUS_STORAGE_NAME_KLARO = 'klaro-anonymous'; +/** + * Klaro configuration + * For more information see https://kiprotect.com/docs/klaro/annotated-config + */ export const klaroConfiguration: any = { storageName: ANONYMOUS_STORAGE_NAME_KLARO, diff --git a/src/app/shared/cookies/klaro.service.ts b/src/app/shared/cookies/klaro.service.ts index 1e4f348d2b..64dee85b65 100644 --- a/src/app/shared/cookies/klaro.service.ts +++ b/src/app/shared/cookies/klaro.service.ts @@ -1,7 +1,17 @@ import { Injectable } from '@angular/core'; +/** + * Abstract class representing a service for handling Klaro consent preferences and UI + */ @Injectable() export abstract class KlaroService { + /** + * Initializes the service + */ abstract initialize(); + + /** + * Shows a the dialog with the current consent preferences + */ abstract showSettings(); } diff --git a/src/assets/i18n/en.json5 b/src/assets/i18n/en.json5 index bcb58a6f17..3b5dc0d9ee 100644 --- a/src/assets/i18n/en.json5 +++ b/src/assets/i18n/en.json5 @@ -990,7 +990,7 @@ "cookies.consent.app.title.google-analytics": "Google Analytics", - "cookies.consent.app.description.google-analytics": "Required for storing statistical data", + "cookies.consent.app.description.google-analytics": "Allows us to track statistical data",