App storage

App Storage allows you to store data as (key, value) pairs on the server so it is available to all users of an app. An entry can be created by assigning to appStorage.setItem(key, value, callback), where key is specified by you. Data is retrieved a similar way. Apps can only read appStorage. Use the Dashboard to clear, remove or change the entries.

The value can be a string, number, array or object. The limit is 1 meg in size. If your app does not have a live internet connection, the request will time out and an error message will be passed to callback.

Since the calls access information on a server, they are asynchronous (so your app does not look up while the call is being processed). When the call is complete, the function named in callback is called in your app. It passes two parameters: (error, data). If the call is successful, error is empty and your results are in data. If the call is unsuccessful, error is not empty and the error message is in data.message.

appStorage is an alias for $volt.storage in the VoltServer API.

AppStudio comes with a Storage sample. Here's how to run it.

appStorage.clear

This call clears all the items in your app's appStorage. It is available in the Dashboard only.

The syntax of the function is:

appStorage.clear(callback)

• callback - function(error, data), required. The function in your app to call when the function is complete (or fails).

  butClear.onclick = function() {
    appStorage.clear(done);
  };

  function done(error, data) {
    if (error) {
      if (data == undefined) {
        data = {
          message: "Network Error"
        };
      }
      NSB.MsgBox(data.message);
    } else {
      console.log("success");
    }
  }

  Function butClear_onclick()
    appStorage.clear(done)
  End Function

  Function done(error, data)
    If error Then
      If data = undefined Then data = {message: "Network Error"}
      MsgBox data.message
    Else
      console.log("success")
    End If
  End Function

appStorage.getItem

This call returns the value of the item with the specified key.

The syntax of the function is:

appStorage.getItem(key, callback)

• key - The name of the item. String.
• callback - function(error, data), required. The function in your app to call when the function is complete (or fails).

  butGetItem.onclick = function() {
    appStorage.getItem("SimpleString", getItemCallback);
  };

  function getItemCallback(error, data) {
    if (error) {
      if (data == undefined) {
        data = {
          message: "Network Error"
        };
      }
      alert(data.message);
    } else {
      alert(data);
    }
  }

  Function butGetItem_onclick()
    appStorage.getItem("SimpleString", getItemCallback)
  End Function

  Function getItemCallback(error, data) 
    If error Then
      If data = undefined Then data = {message: "Network Error"}
      MsgBox data.message
    Else
      MsgBox data
    End If
  End Function

appStorage.getAllItems

This call returns all the items in your app's appStorage in an array of {key, value} objects.

The syntax of the function is:

appStorage.getAllItems(callback)

• callback - function(error, data), required. The function in your app to call when the function is complete (or fails).

  butGetAllItems.onclick = function() {
    appStorage.getAllItems(getAllItemsCallback);
  };

  function getAllItemsCallback(error, data) {
    if (error) {
      if (data == undefined) {
        data = {
          message: "Network Error"
        };
      }
      NSB.MsgBox(data.message);
    } else {
      NSB.Print((false) + "<br>");
      for (key in data) {
        console.log(key, data[key]);
      }
    }
  }

  Function butGetAllItems_onclick()
    appStorage.getAllItems(getAllItemsCallback)
  End Function

  Function getAllItemsCallback(error, data) 
    If error Then
      If data = undefined Then data = {message: "Network Error"}
      MsgBox data.message
    Else
      Print False
      For Each key in data
        console.log(key, data[key])
        k = [key, key][0]
        Print k & ": " & data[key].toString()
      Next
    End If
  End Function

appStorage.removeItem

This call removes the item with a specified key. It is available in the Dashboard only.

The syntax of the function is:

appStorage.removeItem(key, callback)

• key - The name of the item. String.
• callback - function(error, data), required. The function in your app to call when the function is complete (or fails).

  butRemoveItem.onclick = function() {
    appStorage.removeItem("SimpleString", done);
  };

  function done(error, data) {
    if (error) {
      if (data == undefined) {
        data = {
          message: "Network Error"
        };
      }
      NSB.MsgBox(data.message);
    } else {
      console.log("success");
    }
  }

  Function butRemoveItem_onclick()
    appStorage.removeItem("SimpleString", done)
  End Function

  Function done(error, data)
    If error Then
      If data = undefined Then data = {message: "Network Error"}
      MsgBox data.message
    Else
      console.log("success")
    End If
  End Function

appStorage.setItem

This call adds a key, value pair to appStorage. It is available in the Dashboard only.

The syntax of the function is:

appStorage.setItem(key, *value*, callback)

• key - The name of the item. String.
• *value* - The name of the item. Can be string, number, array, object: any JavaScript data type.
• callback - function(error, data), required. The function in your app to call when the function is complete (or fails).

  butSetItem.onclick = function() {
    appStorage.setItem("SimpleString", "ABCD", done);
    appStorage.setItem("Number", 123, done);
    appStorage.setItem("Array", [1, 2, 3, 4], done);
    appStorage.setItem("Object", {
      firstName: "Eric",
      lastName: "Cartman"
    }, done);
  };

  function done(error, data) {
    if (error) {
      if (data == undefined) {
        data = {
            message: "Network Error"
        };
      }
      NSB.MsgBox(data.message);
    } else {
      console.log("success");
    }
  }

  Function butSetItem_onclick()
    appStorage.setItem("SimpleString", "ABCD", done)
    appStorage.setItem("Number", 123, done)
    appStorage.setItem("Array", [1, 2, 3, 4], done)
    appStorage.setItem("Object", {firstName: "Eric", lastName: "Cartman"}, done)
  End Function

  Function done(error, data)
    If error Then
      If data = undefined Then data = {message: "Network Error"}
      MsgBox data.message
    Else
      console.log("success")
    End If
  End Function

Reference

• JavaScript API: https://docs.voltcloud.io/client/$volt.storage.html
• REST API: https://docs.voltcloud.io/api/#storage-plug-in