You can load and save category settings using the following functions:
Framework.LoadCategorySettings(id, callback) // id required
Framework.SaveCategorySettings(data) // no id — bound by Load
You can load category settings using Framework.LoadCategorySettings(), passing the function a name which you want to identify your widget/script/UDIX. For example:
Framework.LoadCategorySettings("my-widget", function(settings) {
// Asynchronously receives existing settings, or an empty object {}
// The retrieved settings are also now available thorough Framework.categorySettings
});
As well as being sent to your asynchronous callback function, the settings data is also stored in Framework.categorySettings.
You must use LoadCategorySettings() before trying to save settings, even if you know that there are no stored settings and that it will return an empty object, {}. This is because the parameter which you pass to LoadCategorySettings() also identifies your widget/script/UDIX for later saving of data.
You should regard the ID which you use in LoadCategorySettings() as mildly sensitive. If someone else's code knows the ID which you are using, it can read and overwrite your data - which might, for example, include a password which you have asked the user for, in order to log in to some external service.
You can save category settings by using Framework.SaveCategorySettings(). You simply pass in the block of data which you want to store. For example:
Framework.SaveCategorySettings({
instrumentId: "EUR/USD",
timeframe: 3600,
visualOptions: {
color: "blue"
}
});
Note: Unlike LoadCategorySettings(), SaveCategorySettings() does NOT take an ID. Passing one as the first argument will cause your ID string to be saved as the data with no runtime error, and your real settings to be silently discarded.
If there are multiple running copies of your widget, script, or UDIX, then they all - including the one which makes the change - receive a CATEGORY_SETTINGS_CHANGE message telling them about the update. Note: you don't need to call LoadCategorySettings() on receipt of this message. The new settings are guaranteed to have been populated already into Framework.categorySettings.
For example, let's say that you have some sort of "view" mode in your widget, switchable between mode A and mode B. If the user changes the setting in one widget, you want all other running copies of your widget to update automatically. You can do the following:
In the widget where the user has changed the selection, you use SaveCategorySettings() to store the new settings.
But you don't act on the change immediately.
Instead, you wait for the CATEGORY_SETTINGS_CHANGE message, and both the widget making the change plus any other copies of your widget all have the same single path of execution where they update themselves in response to a change in settings.
However, one final note: you should not use SaveCategorySettings() as a way of communicating between widgets (and scripts and UDIXes) unless you specifically need permanent storage of the data. If you just want to send transient information between widgets, there are better and (even) faster ways of communicating.
