Corona HTML5 Session Storage Plugin

Store and retrieve data using the browsers Session Storage API in Corona HTML5 apps.

Browser Tests

Installation

• Download the Corona HTML5 Session Storage Plugin repository.

• Move plugin/sessionStorage.lua and plugin/sessionStorage_js.js to the root of your HTML5 project.

• Require the plugin in your code where you need it.

local sessionStorage = require("sessionStorage")

Overview

In Corona HTML5 apps you can use system.setPreferences and system.getPreference to store user data. This data is stored using the browsers "localStorage" which is stored indefinitely until manaully removed.

This plugin utilizes the browsers "sessionStorage" which only lasts as long at the user session is active. When the browser window is closed, all session data is removed. This can be useful in certain use cases.

Data stored in "sessionStorage" is always of the String type. This plugin helps with the conversion of Lua types when storing and retrieving "sessionStorage" data.

Cookies VS Sessions

A browser page session lasts for as long as the browser is open and survives over page reloads and restores. Opening a page in a new tab or window will cause a new session to be initiated, which differs from how session cookies work.

API

setItem

Save data to sessionStorage. Data can be String, Number, Boolean, or Table.

sessionStorage.setItem(key, data)

Arguments

Name	Description	Type	Required
key	The key name to store the data with.	String	Y
data	The data to store. Data type can be String, Number, Boolean, or Table.	Variable	Y

Returns

On success the Boolean true, or nil otherwise.

Examples

String

sessionStorage.setItem('username', 'Donna')

--Or to verify
if (sessionStorage.setItem('username', 'Donna')) then
  print('stored')
else
  print('failed')
end

Table

sessionStorage('config', {username="Donna", score=100})

Notes

Lua Table types are converted to JSON strings before being stored. You must use the 'table' valType to retrieve them (see getItem below).

---

getItem

Get saved data from sessionStorage.

sessionStorage.getItem(key[, valType])

Arguments

Name	Description	Type	Required
key	The key name to retrieve the data from.	String	Y
valType	The preferred returned data type. (see below).	String	N

Returns

The data stored at key. By default this will be a String data type. Pass a valType to convert the data.

Valid valTypes are:

• 'string' (default)
• 'number'
• 'boolean'
• 'table'

Examples

String

local username = sessionStorage.getItem('username')
print(username) --> Donna

--Or to verify
local username = sessionStorage.getItem('username')
if not username then
  print('no username')
else
  print(username) --> Donna
end

Note: You can also verify a key is present using the exists method.

Number

--values are returned as strings unless a valType is specified.
local score = sessionStorage.getItem('score', 'number')
print(score) --> 100

Boolean

--values are returned as strings unless a valType is specified.
local isWinner = sessionStorage.getItem('winner', 'boolean')
print(isWinner) --> true

Table

--values are returned as strings unless a valType is specified.
local config_tbl = sessionStorage.getItem('config', 'table')
print(config_tbl.username) --> Donna

---

removeItem

Remove saved data from sessionStorage.

sessionStorage.removeItem(key)

Arguments

Name	Description	Type	Required
key	The key name to delete the data from.	String	Y

Returns

On success the Boolean true, or nil otherwise.

Example

sessionStorage.removeItem('username')

--Or to verify
if (sessionStorage.removeItem('username')) then
  print('deleted')
else
  print('failed')
end

---

exists

Check if key is present in sessionStorage.

sessionStorage.exists(key)

Arguments

Name	Description	Type	Required
key	The key name to check for existence.	String	Y

Returns

If the key exists returns the Boolean true, or false otherwise.

Example

if (sessionStorage.exists('username')) then
  print('username exists')
else
  print('username does not exist')
end

---

clear

Remove all saved data from sessionStorage.

sessionStorage.clear()

Arguments

This method takes no arguments

Returns

On success the Boolean true, or nil otherwise.

Example

sessionStorage.clear()

--Or to verify
if (sessionStorage.clear()) then
  print('cleared')
else
  print('failed')
end

Demo

In the demo directory is a Corona project that you can build for HTML5 testing.

Notes

You can view the "sessionStorage" data using the Google Chrome Developer Tools window (or similar on other browsers). Click the Application tab, and then Session Storage (on the left side menu).

---

©2018 C. Byerley (develephant)