alfresco-ng2-components/docs/core/services/user-preferences.service.md

Title, Added, Status, Last reviewed

Title	Added	Status	Last reviewed
User Preferences Service	v2.0.0	Active	2025-11-20

User Preferences Service

Stores preferences for the app and for individual components.

Class members

Methods

• get(property: string, defaultValue?: string): string
  Gets a preference property.
  • property: string - Name of the property
  • defaultValue: string - (Optional) Default to return if the property is not found
  • Returns string - Preference property
• getDefaultLocale(): string
  Gets the default locale.
  • Returns string - Default locale language code
• getPropertyKey(property: string): string
  Gets the full property key with prefix.
  • property: string - The property name
  • Returns string - Property key
• getStoragePrefix(): string
  Gets the active storage prefix for preferences.
  • Returns string - Storage prefix
• hasItem(property: string): boolean
  Check if an item is present in the storage
  • property: string - Name of the property
  • Returns boolean - True if the item is present, false otherwise
• select(property: string): Observable<any>
  Sets up a callback to notify when a property has changed.
  • property: string - The property to watch
  • Returns Observable<any> - Notification callback
• set(property: string, value: any)
  Sets a preference property.
  • property: string - Name of the property
  • value: any - New value for the property
• setStoragePrefix(value: string)
  Sets the active storage prefix for preferences.
  • value: string - Name of the prefix
• setWithoutStore(property: string, value: any)
  Sets a preference property.
  • property: string - Name of the property
  • value: any - New value for the property

Details

The preferences are bound to a particular prefix so the application can switch between different profiles on demand.

For example, upon login you can set the prefix to the current username:

import { UserPreferencesService, AuthenticationService } from '@alfresco/adf-core';

@Component({...})
class AppComponent {
    constructor(private userPreferences: UserPreferencesService,
                private authService: AuthenticationService) {
    }

    onLoggedIn() {
        this.userPreferences.setStoragePrefix(
            this.authService.getUsername()
        );
    }
}

As soon as you assign the storage prefix, all settings that you get or set via the UserPreferencesService will be saved to a dedicated profile.

You can import the service into your controller and use its APIs as shown below:

@Component({...})
class AppComponent {
    constructor(userPreferences: UserPreferencesService) {

        userPreferences.set('myProperty1', 'value1');
        userPreferences.set('myProperty2', 'value2');

        console.log(
            userPreferences.get('myProperty1')
        );
    }
}

The service also provides quick access to a set of the "known" properties used across ADF components:

Name	Type	Description
authType	string	Authorization type (can be "ECM", "BPM" or "ALL").
disableCSRF	boolean	Prevents the CSRF Token from being submitted if true. Only valid for Process Services.
paginationSize	number	Pagination size.
locale	string	Current locale setting.

User Preference onChange Stream

Whenever a property is set with the user preferences service, an onChange event is sent with the whole set of user properties. This is useful when a component needs to react to a property change:

    userPreferences.paginationSize = 10;
    userPreferences.onChange().subscribe((userStatusValues) => {
        console.log(userStatusValues.PAGINATION_SIZE); //this will be 10
    });

You can also use the select method to get notification when a particular property is changed. A set of basic properties is added into the enumeration UserPreferenceValues which gives you the key value to access the standard user preference service properties:

• PaginationSize
• DisableCSRF
• Locale
• SupportedPageSizes
• ExpandedSideNavStatus

    userPreferences.disableCSRF = true;
    userPreferences.select(UserPreferenceValues.DisableCSRF).subscribe((CSRFflag) => {
        console.log(CSRFflag); //this will be true;
    });

Convenience Observables and Signals

For commonly accessed preferences like locale, the service provides both observables and signals that simplify access patterns.

Using Signals (Recommended - No Subscription Needed!)

Signals automatically handle cleanup and don't require manual unsubscription:

export class MyComponent {
    private userPreferences = inject(UserPreferencesService);
    
    // Signal - automatically reactive, no subscription needed!
    currentLocale = this.userPreferences.localeSignal;
    
    // Use in template or computed values
    displayText = computed(() => `Current locale: ${this.currentLocale()}`);
}

Available signals:

• localeSignal - Current locale value
• paginationSizeSignal - Current pagination size
• supportedPageSizesSignal - Supported page sizes array

Benefits of signals:

• ✅ No manual subscription/unsubscription needed
• ✅ Automatic cleanup when component is destroyed
• ✅ Better performance with fine-grained reactivity
• ✅ Simpler code - just read the value with ()

Using Observables (For Advanced Cases)

If you need RxJS operators or imperative subscriptions:

constructor(private userPreferences: UserPreferencesService) {
    // Observable - requires takeUntilDestroyed() to prevent memory leaks
    this.userPreferences.locale$
        .pipe(takeUntilDestroyed())
        .subscribe(locale => {
            this.currentLocale = locale;
        });
}

Available observables:

• locale$ - Observable for locale changes
• paginationSize$ - Observable for pagination size changes
• supportedPageSizes$ - Observable for supported page sizes changes

Note: When subscribing to observables from a singleton service in a component, always use takeUntilDestroyed() or takeUntil() to prevent memory leaks.