A crucial part of the generated TypeScript ViewModels that Coalesce creates for you is the hierarchical configuration system that allows coarse-grained or fine-grained control over their behaviors.
The configuration system has four levels where configuration can be performed, structured as follows:
- Root Configuration
The root configuration contains all configuration properties which apply to class category (TypeScript ViewModels, TypeScript ListViewModels, and Services). The
appproperty contains global app configuration that exists independent of any models. Then, for each class kind, the following are available:
- Root ViewModel/ListViewModel Configuration
Additional root configuration objects exist, one for each class kind. These configuration objects govern behavior that applies to only objects of these types. Root configuration can be overridden using these objects, although the practicality of doing so is dubious.
- Class Configuration
Each class kind has a static property named
coalesceConfigthat controls behavior for all instances of that class.
- Instance Configuration
Each instance of these classes also has a
coalesceConfigproperty that controls behaviors for that instance only.
All configuration properties are Knockout
ComputedObservable<T> objects. These observables behave like any other observable - call them with no parameter to obtain the value, call with a parameter to set their value.
Whenever a configuration property is read from, it first checks its own configuration object for the value of that property. If the explicit value for that configuration object is null, the parent's configuration will be checked for a value. This continues until either a value is found or the root configuration object is reached.
When a configuration property is given a value, that value is established on that configuration object only. Any dependent configuration objects will not be modified, and if those dependent configuration objects already have a value for that property, their existing value will be used unless that value is later set to null.
To obtain the raw value for a specific configuration property, call the
raw() method on the observable:
Available Properties & Defaults¶
The following configuration properties are available. Their default values are also listed.
These properties on
Coalesce.GlobalConfiguration are available to both ViewModelConfiguration, ListViewModelConfiguration, and ServiceClientConfiguration.
- baseApiUrl -
- The relative url where the API may be found.
- baseViewUrl -
- The relative url where the admin views may be found.
- showFailureAlerts -
- Whether or not the callback specified for
onFailurewill be called or not.
- onFailure -
(obj, message) => alert(message)
- A callback to be called when a failure response is received from the server.
- onStartBusy -
obj => Coalesce.Utilities.showBusy()
- A callback to be called when an AJAX request begins.
- onFinishBusy -
obj => Coalesce.Utilities.hideBusy()
- A callback to be called when an AJAX request completes.
These properties on
Coalesce.GlobalConfiguration.app are not hierarchical - they govern the entire Coalesce application:
- select2Theme -
- The theme parameter to select2's constructor when called by Coalesce's select2 Knockout Bindings.
- saveTimeoutMs -
- Time to wait after a change is seen before auto-saving (if
autoSaveEnabledis true). Acts as a debouncing timer for multiple simultaneous changes.
- saveIncludedFields -
An array of property names that, if set, will determine which fields will be sent to the server when saving. Only those values that are actually sent to the server will be mapped to the underlying entity.
This can improves the handling of concurrent changes being made by multiple users against different fields of the same entity. Specifically, if one page is designed to edit fields A and B, and another page is designed for editing fields C and D, you can configure this setting appropriately on each page to only save the corresponding fields.
Due to design limitations, this cannot be determined dynamically like it can with Vue's $saveMode property
Surgical saves require DTOs on the server that are capable of determining which of their properties have been set by the model binder, as surgical saves are sent from the client by entirely omitting properties from the
x-www-form-urlencodedbody that is sent to the server.
The Generated C# DTOs implement the necessary logic for this; however, any Custom DTOs you have written are unlikely to be implementing the same behavior. For Custom DTOs, either implement the same pattern that can be seen in the Generated C# DTOs, or do not use this setting.
- autoSaveEnabled -
- Determines whether changes to a model will be automatically saved after
saveTimeoutMsmilliseconds have elapsed.
- autoSaveCollectionsEnabled -
- Determines whether or not changes to many-to-many collection properties will automatically trigger a save call to the server or not.
- showBusyWhenSaving -
- Whether to invoke
- loadResponseFromSaves -
- Whether or not to reload the ViewModel with the state of the object received from the server after a call to
- validateOnLoadFromDto -
- Whether or not to validate the model after loading it from a DTO from the server. Disabling this can improve performance in some cases.
- setupValidationAutomatically -
- Whether or not validation on a ViewModel should be setup in its constructor, or if validation must be set up manually by calling
viewModel.setupValidation(). Turning this off can improve performance in read-only scenarios.
- onLoadFromDto -
- An optional callback to be called when an object is loaded from a response from the server. Callback will be called after all properties on the ViewModel have been set from the server response.
- initialDataSource =
- The dataSource (either an instance or a type) that will be used as the initial dataSource when a new object of this type is created. Not valid for global configuration; recommended to be used on class-level configuration. E.g.
No special configuration is currently available for ListViewModels.
No special configuration is currently available for ServiceClients.