Skip to content

User-Defined Configuration

A User-Defined Configuration Business Object stores one value per End user, such as a preference or the state of a menu. In code, each one is a class with static methods under This.<ConfigurationName> that read, store and reset the current End user’s value.

Availability: Both¹

This.<ConfigurationName>

User-Defined Configurations are not grouped under a $ namespace: they are reached directly as This.<ConfigurationName>.

They are typed in server-side code, client-side code and shared code with availability serverAndClient, but not in calculation code.

On the client, the methods marked Both¹ forward the call to the server. The server accepts them only from a logged-in End user, except get(), which returns the default value when no End user is logged in. No AccessControl rules are evaluated for these calls.

Values are stored as JSON, per End user. Values that JSON cannot represent, such as Date objects or class instances, come back as plain JSON values.

get(): Promise<<ConfigurationName>.ValueType>

Returns the current End user’s value. If none is stored yet, Lowgile evaluates the default value, stores it for the End user, and returns it. Without a logged-in End user, it returns the default value without storing it.

Returns: Promise<<ConfigurationName>.ValueType> · Availability: Both¹

On the client, the first result is cached: later calls return the cached value until the app is reloaded or set() is called.

set(value: <ConfigurationName>.ValueType): Promise<void>

Stores a value for the current End user. Throws an error if no End user is logged in.

ParameterTypeDescription
value<ConfigurationName>.ValueTypeThe value to store.

Returns: Promise<void> · Availability: Both¹

On the client, the cached value used by get() is replaced right away, before the server has stored it.

isSet(): Promise<boolean>

Tells whether a value is stored for the current End user.

Returns: Promise<boolean> · Availability: Both¹

Note

On the server, isSet() always resolves to true, whether or not a value is stored. On the client, it calls get() and returns whether the result is not undefined; since get() stores the default value on first use, it returns true unless the default value is undefined.

createDefaultValue(): Promise<<ConfigurationName>.ValueType>

Evaluates the default value defined on the User-Defined Configuration and returns it, without storing it. On the client, the default value is evaluated on the server.

Returns: Promise<<ConfigurationName>.ValueType> · Availability: Both¹

reset(): Promise<<ConfigurationName>.ValueType>

Stores the default value for the current End user and returns it.

Returns: Promise<<ConfigurationName>.ValueType>, the default value · Availability: Both¹

Note

On the client, reset() does not update the value cached by get(): later get() calls keep returning the previous value until the app is reloaded. Use the returned value, or call set() with it.

getForUser(userOrId: Sys.Types.User | string): Promise<<ConfigurationName>.ValueType>

Returns the value of the given End user. If none is stored yet, Lowgile evaluates the default value, stores it for that End user, and returns it.

ParameterTypeDescription
userOrIdSys.Types.User | stringThe End user, or their user id.

Returns: Promise<<ConfigurationName>.ValueType> · Availability: Server

setForUser(userOrId: Sys.Types.User | string, value: <ConfigurationName>.ValueType): Promise<void>

Stores a value for the given End user.

ParameterTypeDescription
userOrIdSys.Types.User | stringThe End user, or their user id.
value<ConfigurationName>.ValueTypeThe value to store.

Returns: Promise<void> · Availability: Server

Note

getForUser() and setForUser() can appear in client-side typings, but the server rejects them when they are called from the client.

type <ConfigurationName>.ValueType

The type of the stored value, as set on the User-Defined Configuration. any if no type is set.

Availability: Both

  • User-Defined Configurations
  • Access Control

¹ On the client, the call is sent to the server and is subject to access control.