The storage object provides an interface to device and cloud-based storage and backup for user input. Device storage allows the application to restart with the same settings when it was last active. Device storage is implemented using the browser's localStorage. The user's saved input is stored in localStorage under the key ${ctl.appId}_input. A new set of user input is saved after an input state variable change causes the Controller to synchronize the Model and View.
If the browser tab is cloned, one app instance will detect a localStorage change by the other tab and will set the application state of the instance to the updated values.
When an application starts up on a device for the first time, it creates a globally unique ID (GUID) by storing the string GUID-${Date.now()} in localStorage under the key ${ctl.appId}_guid.
Cloud storage saves the current data and takes backup snapshots of the data that the user can request in case local storage becomes corrupt or they make an unrecoverable mistake when entering data. When the server detects it is storing new data that is more than a day newer than the previous data, it saves the previous data as a backup snapshot. Up to four backup snapshots will be preserved. When a new snapshot is created, the oldest snapshot is discarded after four snapshots are present. If the user has not entered an email address and password, all cloud storage is associated with the GUID.
The storage.setState() method saves user input data locally, and if online, a copy is sent to the cloud. The storage.getState() method only gets the local state.
Saving data can be disabled and re-enabled using the storage.disable() and storage.enable() methods, respectively. Storage can be disabled for many reasons, such as running a self-test or loading a trouble report. A subsystem that disables and enables saving uses a unique id string so that competing requests can be matched. Storage is only re-enabled when all the disabled IDs have been re-enabled.
Cloud Sync allows user input data to be transferred between devices and saved input to be recovered when a device is lost. It is enabled when the user enters an email address and a password. Once Cloud Sync is enabled, data stored on the server is associated with the email address and password. Any data previously associated with the GUID (including backup snapshots) is also associated with the email address and password.
By design, this procedure does not require any user registration process. The user may choose any combination of email address and password. Setting a new password will create an independent set of data from the old password. The user can deliberately use this to keep, for example, a different set of aircraft data for testing or to keep aircraft associated with different companies separated.
The server will accept email addresses and passwords with the following characters:
/[\w\-+!#$%&'()*+,.;=@\[\]\^_`{}~]/
The email must have the form of an email address with any illegal characters stripped out but is otherwise unverified. The password must have at least two characters after any illegal character are stripped out. The character restrictions allow the server to use raw files to store user data.
When new user input is storage to device storage, a copy is also sent to the cloud using the server.setSavedInput() method. The server will return an error if the GUID in the passed id argument does not match the GUID in the previously saved input data. This tells the app that another device with a different GUID but the same email and password has written new data since the last time is wrote. The app then asks the user whether they want to use this device's current data or transfer the other device's data from the cloud.
If the user wants to use the cloud data, the data is retrieved using the server.getSavedInput() method, and the data is used to set the app's inputs. In either case, the app's state is then saved to the cloud using storage.setCloudData() method with the takeover argument set to true. This forces the server to overwrite the other device's data with this device's data, which includes this device's GUID.
The storage object also contain interfaces to the indexedDB browser service to store larger objects using a key. In the POH Performance apps, this is primarily used to store airport database updates. The object storage interfaces are:
storage.getObjStoreVal()storage.setObjStoreVal()storage.hasObjStoreVal()storage.deleteObjStoreVal()storage methodsdeleteObjStoreVal()storage.deleteObjStoreVal(key)
Deletes the value associated with key.
keyReturns a Promise that resolves if the operation is successful and rejects with the event errorCode when it is unsuccessful.
disable()storage.disable(id)
Disables storage saving. An id string that identifies the subsystem that will re-enable storage must be provided.
idenable()storage.enable(id)
Enables storage saving if no other subsystems have disabled storage. An id string that identifies the subsystem that disabled storage must be provided.
idgetCloudData()storage.getCloudData()
Gets the cloud data associated with server.id. Returns a Promise that resolves with a input state object, if the operation is successful. The method calls the server.getSavedInput() to make the request. The result is decoded from JSON and upgraded to the current app version using ctl.upgradeSavedState()) before being returned.
If ctl.upgradeSavedState() returns an error string, then the Promise is rejected with the error string.
Returns a Promise that resolves if the operation is successful and rejects with one of the following error strings:
'corrupt''incompatible''nodata'server.id,offline'serverOffline'getObjStoreVal()storage.getObjStoreVal(key)
Returns a Promise that resolves with the value associated with key.
keyReturns a Promise that resolves with the value associated with key if the operation is successful. The Promise rejects with the event errorCode when it is unsuccessful.
getState()storage.getState()
Get and decode locally stored user input data. Returns the result of fetching and decoding the JSON string stored in localStorage under the ${ctl.appId}_input key. If successful, the decoded results are upgraded to the current app version (see ctl.upgradeSavedState()) before being returned.
An object that represents the saved user input passed to a previous call to storage.setState() and upgraded to be compatible with the current app version.
hasObjStoreVal()storage.hasObjStoreVal(key)
Returns a Promise that resolves with true if there is a value associated with key.
keyReturns a Promise that resolves with true if there is a value associated with key, if the operation is successful. The Promise rejects with the event errorCode when it is unsuccessful.
isValidCloudId()storage.isValidCloudId(email, password)
Returns true if both mail and password are valid. To be valid, the email string must be empty or form a valid email address when illegal characters are stripped. To be valid, the password string must be empty or be at least two characters in length when illegal characters are stripped.
emailserver.id.passwordserver.id.A Boolean that is true if both parameters meet the validity requirements.
newCloudId()storage.newCloudId(email, password)
Sets a new cloud sync email and password. If the server has data associated with this email/password, then use it to set the app state. If not, then ask the user whether they want to create a new data store on the server. This prevents accidentally creating a new store for a mis-typed email or password.
If email and password are valid(see storage.isValidCloudId(), then newCloudId() composes a new JSON-encoded ID object containing email, password, and guid elements and set server.id.
If the retrieved state is from a newer version of the app, then it's considered incompatible and Cloud Sync is disabled until the app is upgraded.
Return a Promise that is resolved on success and is rejected if the user cancels email/password change or if it's invalid.
emailserver.id.passwordserver.id.Return a Promise that is resolved on success and is rejected if the user cancels email/password change or if it's invalid. Rejection returne one of the following strings:
'badSaveId''cancel'server.id is unchanged.'incompatible'setCloudData()storage.setCloudData()
storage.setCloudData(input)
storage.setCloudData(input, ask)
Sets the cloud data associated with server.id to input. Returns a Promise that resolves if the operation is successful. The method calls the server.setSavedInput() to make the request.
If the server responds with a status code of 409 (Conflict), it indicates that the GUID element in server.id did not match the GUID in the previously stored input data because another device last wrote it. In that case, if ask is omitted or falsey, then storage.setCloudData() will retrieve the cloud data using the server.getSavedInput() method and use it to set the app's input state. If ask is truthy, then storage.setCloudData() will issue a dialog.choose() that ask the user to choose between the current app state and the cloud data from the other device. If the cloud data is chosen then the storage.setCloudData() will retrieve the cloud data using server.getSavedInput() and use it to set the app's input state. Finally, once the previous steps are done, storage.setCloudData() calls the server.setSavedInput() method one more time with the latest app state and the takeover argument set to true to store take ownership of the cloud data.
input (optional)server.setState() in localStorage is used.ask (optional)ask is omitted or falsey, then storage.setCloudData() will retrieve the cloud data and use it to set the app's input state. Otherwise, if ask is truthy, then storage.setCloudData() will ask the user to choose between the current app state and the cloud data from the other device.Returns a Promise that resolves if the operation is successful and rejects with the server.setSavedInput() response status code when it is unsuccessful.
startCloudSync()storage.startCloudSync(email, password)
Starts Cloud Sync with an initial email and password. Sets storage.email to email. If both email and password are valid (see storage.isValidCloudId(), then it sets storage.password to password. Otherwise, it sets it to ''.
Called from the initialization routing of the page that contains the email and password.
emailserver.id.passwordserver.id.setObjStoreVal()storage.setObjStoreVal(key, value)
Sets the value associated with key.
keyvaluekey.Returns a Promise that resolves if the operation is successful and rejects with the event errorCode when it is unsuccessful.
setState()storage.setState(input)
Set the locally stored saved input to input. If the app is online, it saves a copy of input to the cloud as well (see storage.setCloudData()).
inputctl.getSavedState().Returns a Promise that resolves when the local and cloud operations are complete.
storage propertiesemailThe current email address to use in server.id.
guidThe current GUID to use in server.id.
passwordThe current password to use in server.id.