User Defaults

Overview

The UserDefaults are the place where user's preferences are stored. UserDefaults are similar in concept to a HashTable; they are stored as string values with a string key.

For speed reasons UserDefaults are cached both on client and on server side. In the OpenPetra DB they reside in the DB table s_user_defaults.

Some UserDefaults are just internal to the operation of OpenPetra and the user will never see or alter their value directly, but most UserDefaults are meant to be seen by the user (or at least their effect) and meant to be changed by the user...

• in the Preferences Dialog;
• in some other way that relates to operations on screens that the user performs.
  • Example 1 - 'Implementation of 'sticky' values/settings': The act of checking a certain CheckBox on a certain OpenPetra screen could alter an specific underlying (boolean) UserDefault. The checked/not-checked state of that CheckBox would be set to the value of the UserDefault the next time the user brings up the same screen.
  • Example 2 - 'Retaining the collapsed/expanded state of a Collapsible Panel (somewhere in OpenPetra)'. One instance where this is already implemented is the 'Partner Info' Collapsible Panel in the Partner Find screen.

Data Management

• Once a user logs in, the server-side cache is filled from the DB table and its contents are transferred to the client.
• Any changed UserDefaults are sent back to the server and get saved in the DB when the client is closed.
  • In the time between they stay cached in both the client-side and server-side caches for fast access!
• It is possible to save a given UserDefault (or all changed UserDefaults) to the DB on request at any given time using the SaveChangedUserDefault or SaveChangedUserDefaults Methods of the client-side TUserDefaults Class.
  • That is useful if the server-side cache needs to be updated (which is not often the case as many UserDefaults relate either to client-side-only or server-side-only operations), or if some legacy 4GL code needs to access a changed UserDefault's value direct from the DB table.
• From the server side the saving of all changed UserDefaults is possible using the SaveUserDefaultsFromServerSide Method of the server side TUserDefaults Class.

Accessing UserDefaults

The two Classes that provide access to the UserDefaults are:

• Client Side: Ict.Petra.Client.App.Core.TUserDefaults
• Server Side: Ict.Petra.Server.MSysMan.Maintenance.UserDefaults.WebConnectors.TUserDefaults

Reading UserDefault Values

Both the server-side and client-side Classes have methods named 'GetXXXXDefault' where XXXX is one of the following: Boolean, Char, Double, Int16, Int32, Int64, String. An overload exists for each of the Methods that allows a default value to be supplied. That would be returned in case the UserDefault doesn't exist.

These Methods cast the string value that is stored for a given UserDefault to the desired Type.

Example

To get a boolean value of a new UserDefault one would introduce a new UserDefault constant in file

\trunk\csharp\ICT\Petra\Client\app\Core\UserDefaults.cs

in the Internal Class

TUserDefaults.NamedDefaults 

and utilise the Method

GetBooleanDefault(String AKey, bool ADefault)

- setting AKey to the new Constant and ADefault to be false.

The result of calling that Method will be false if

• the user has never set that UserDefault, or if
• the user has set the UserDefault to false.

- otherwise the result will be true.

Updating UserDefault Values

Both the server-side and client-side Classes have a Methods named 'SetDefault'. Pass in the name of the UserDefault and a Value that the UserDefault should be set to. The Value is defined as Type object. The ToString() Method will be called on to it get the value of the object that is to be saved as the value of the UserDefault. Since that works for all the Types that can be read (Boolean, Char, Double, Int16, Int32, Int64), one can just pass the value as such a Type and its string representation will be stored.

The server-side Method has got an optional Argument called 'ASendUpdateInfoToClient' (which is by default 'true'). If it is true, the client is informed about the change to the UserDefault (by means of sending a ClientTask). In case the user is logged in with several client instances at the same time (e.g. from different PC's) then all the users' clients will get the updated value!

User-facing: Preferences Dialog

There is a 'Preferences' Dialog in OpenPetra that allows the user to set various UserDefaults to her/his preference: Main Menu -> Settings 'Module' -> Preferences Sub-Module -> User Preferences.