HexagonJS
About
InstallationCore ConceptsChangelog[Migration (1.x -> 2.x)]
Tutorials
Getting StartedPrint Styles
Demos
Component Demo Page
Css Components
BaseButtonBadgeError PagesFormInputsInput GroupLabelLayoutLogoNoticeSpinnerTable
Js Components
Alerts and MessagesAutocomplete PickerAutocompleteButton GroupCardCollapsibleColor PickerCrumbtrailData TableDate PickerDate Time PickerDrag ContainerDrawingDropdownDropdown ButtonExtended TableFile InputFluidForm BuilderInline EditableInline PickerInline SelectMenuMeterModalMore ButtonNotifyNumber PickerPaginatorPickerPivot TablePlotProgress BarSide CollapsibleSidebarSingle SelectSliderStepperSticky Table HeadersTabsTag InputTime PickerTime SliderTitlebarToggle ButtonToggleTooltipTreeVisualization Bar
Utilities
AnimateClick DetectorColor ScaleColorComponentEvent EmitterFast ClickFilterFormatInterpolateListMapMorph SectionMorphsPalettePointer EventsPreferencesRequestResize EventsSearch DomSelectSelectionSetSortTransitionUser Facing TextUtilView
Edit Page
Preferences
A method for storing user settings across applications for things like time zone and locale settings.
Examples

HTML

<button id="example" class="hx-btn hx-positive"><i class="fa fa-cog"></i> Preferences</button>

JavaScript

hx.select('#example').on('click', function(){
  hx.preferences.load(function() {
    hx.preferences.show()
  })
})
Api
Change Log
Properties
hx.preferencesPreferences
Global instance of Preferences
hx.preferences.localStorageStore
The default backing store used by hx.preferences
Prototypes
PreferencesextendsEventEmitter
A class for storing and retrieving user preferences such as timezone and locale preference.
Events
localechange
Emitted when the time zone changes.
timezonechange
Emitted when the time zone changes.
Methods
applyTimezoneOffsetdateDatetimezoneOrOffsetString / NumberDate
A method that takes a date and returns a new date with the timezone offset applied.
Arguments
dateDate
The date to offset
timezoneOrOffsetString / Number
The timezone or offset to apply. Gets the offset from the timezone when passing a string or uses the offset value directly.
If this is not provided, the offset is retrieved from the currently set timezone.
Returns
Date
The date, offset by the timezone amount.
backingStorestoreObjectPreferences
Sets the backing store to use.
Arguments
store
The store to use for storage of the preferences. By default this will be set to use local storage (hx.preferences.localStorageStore)
Properties
loadcallbackFunction
Loads the preferences
Arguments
callbackerrorErrorencodedPreferencesString
The callback to call when you have finished storing the preferences
Arguments
errorError
If there was an error this will be defined
encodedPreferencesString
The encoded preferences string that was retrieved from storage
saveencodedPreferencesStringcallbackFunction
Saves the preferences
Arguments
encodedPreferencesString
The string to store that contains the user preferences (encoded as json)
callbackerrorError
The callback to call when you have finished storing the preferences
Arguments
errorError
If there was an error this will be defined
Returns
Preferences
This Preferences
isLocaleSupportedlocaleStringBoolean
Checks the list of supportedLocales to see whether the locale is supported
Arguments
localeString
The locale to check
Returns
Boolean
Whether the locale is in the list of supported locales
isTimezoneSupportedtimezoneStringBoolean
Checks the list of supportedTimezones to see whether the timezone is supported
Arguments
timezoneString
The timezone to check
Returns
Boolean
Whether the timezone is in the list of supported timezones
loadcallbackFunctionPreferences
Loads the preferences from somewhere (the location of which depends on the store type in use). The loaded settings should be accessed through the normal getter methodspreferences.locale() and hx.preferences.timezone())
Arguments
callbackerrorError
Arguments
errorError
If something went wrong in the loading process, the error will be supplied. If all was fine, this argument will be undefined.
Returns
Preferences
This Preferences
localelocaleStringPreferences
Sets the locale preference. This will just set the value in memory, and should be persisted with the save() method.
Arguments
localeString
Should be a locale identifier in LCID format.
Returns
Preferences
This Preferences
localeString
Gets the locale preference
Returns
String
The locale identifier in LCID format.
savecallbackFunctionPreferences
Saves the preferences somewhere (the location of which depends on the store type in use)
Arguments
callbackerrorError
Arguments
errorError
If something went wrong in the loading process, the error will be supplied. If all was fine, this argument will be undefined.
Returns
Preferences
This Preferences
setupoptionsObject
A method for re-initialising the preferences object with a new configuration.
Calling with no arguments returns it to the default configuration.
Arguments
options
Properties
backingStorePreferencesStore
The storage location to get and set preferences from when calling preferences.save() and preferences.load()
The default uses local storage: 
const LocalStoragePreferencesStore = {
  save(prefs, cb) {
    localStorage.setItem(localStorageKey, prefs);
    return cb();
  },
  load(cb) {
    return cb(undefined, localStorage.getItem(localStorageKey));
  },
};
Default: LocalStoragePreferencesStore
featureFlags
Properties
useIntlFormatBoolean
Whether to use the Intl API for localisation of dates and times within Hexagon.
See MDN -> Intl for more information
Default: false
locale
The locale to set. By default will attempt to lookup the current locale based on the browser.
Default: undefined
supportedLocalesArray[String]
Set the list of supported locales. The default is to use all supported locales
Default: []
supportedTimezonesArray[String]
Set the list of supported timezones. The default is to use all supported timezones
Default: []
timezone
The timezone to set. By default will attempt to lookup the current locale based on the browser.
Default: undefined
showPreferences
Shows the preferences modal
Returns
Preferences
This Preferences
supportedLocaleslocalesArray[String]Preferences
Sets the list of supported locales for this app
Arguments
localesArray[String]
An array of locale identifiers in LCID format.
Returns
Preferences
This Preferences
supportedLocalesArray[String]
Gets the list of supported locales for this app
Returns
Array[String]
An array of locale identifiers in LCID format.
supportedTimezonesArray[String]
A method for getting the currently supported timezones.
Returns
Array[String]
The array of supported timeszones
supportedTimezonestimezonesArray[String]Preferences
A method for setting the currently supported timezones.
Arguments
timezonesArray[String]
The array of timezones to set. The default list of timezones is in the format of "UTC+00:00". If timezones in different formats are required, a new timezoneOffsetLookup function must be set.
Returns
Preferences
This Preferences
timezonetimezoneStringPreferences
Sets the timezone preference. This will just set the value in memory, and should be persisted with the save() method.
Arguments
timezoneString
Should be a time zone identifier string in the following format: 'America/New_York'.
Returns
Preferences
This Preferences
timezoneString
Gets the timezone preference
Returns
String
The time zone identifier
timezoneOffsetLookupFunction
A method for getting the timezoneOffsetLookup function
Returns
function
The currently set timezoneOffsetLookup function
timezoneOffsetLookupfnFunctionPreferences
A method for setting the timezoneOffsetLookup function
Arguments
fntimezoneStringdatestampNumberNumber
A function that takes a timezone and a datestamp and returns the offset amount (in hours) for that timezone at that time.
Arguments
timezoneString
The timezone to get the offset for. Should always be one of the timezones listed in supportedTimezones.
datestampNumber
A datestamp in ms. Can be used to get an exact timezone offset when using libraries like Moment.js for offset lookup.
Returns
Number
The timezone offset in hours. E.g. "UTC+01:00" = 1
Returns
Preferences
This Preferences