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¹
How to reach it
Section titled “How to reach it”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.
Functions
Section titled “Functions”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.
| Parameter | Type | Description |
|---|---|---|
value | <ConfigurationName>.ValueType | The 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()
Section titled “isSet()”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()
Section titled “createDefaultValue()”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()
Section titled “reset()”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()
Section titled “getForUser()”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.
| Parameter | Type | Description |
|---|---|---|
userOrId | Sys.Types.User | string | The End user, or their user id. |
Returns: Promise<<ConfigurationName>.ValueType> · Availability: Server
setForUser()
Section titled “setForUser()”setForUser(userOrId: Sys.Types.User | string, value: <ConfigurationName>.ValueType): Promise<void>Stores a value for the given End user.
| Parameter | Type | Description |
|---|---|---|
userOrId | Sys.Types.User | string | The End user, or their user id. |
value | <ConfigurationName>.ValueType | The 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.
ValueType
Section titled “ValueType”type <ConfigurationName>.ValueTypeThe type of the stored value, as set on the User-Defined Configuration. any if no type is set.
Availability: Both
Related
Section titled “Related”- User-Defined Configurations
- Access Control
¹ On the client, the call is sent to the server and is subject to access control.