Join the chat for questions and updates
Cite this plugin:
@misc{callebautNS,
author = {Gilles Callebaut and Alok Rajiv},
title = {{NativeStorage - A Cordova Plugin}},
doi = {10.5281/zenodo.1312615},
howpublished = {\url{https://github.com/TheCocoaProject/cordova-plugin-nativestorage}},
}
You can also provide a version
field to include a version number e.g., version = {2.3.1}
.
NEW: Windows and OS X is supported! UPDATE: The Plugin can now also be found at the Telerik Plugin Market.
Documentation about the API prior to v2 can be found at the wiki
The plugin was created and developed by Gilles Callebaut, in the scope of an IWT/VlAIO Tetra project CrossMoS which assesses Mobile Cross-Platform Tools. This wouldn't be possible without the contributions of Alok Rajiv, our Cordova and JavaScript guru.
Please consider reading our wiki for more documentation about this plugin.
This plugin is created because of the non-persistent property of LocalStorage in the WebView of Android and iOS. In iOS stored data from LocalStorage can be removed by the OS, when running out of memory.
Some complaints:
Storage of:
Assessment of Data Storage Strategies Using the Mobile Cross-Platform Tool Cordova
The plugin can be installed via the Cordova command line interface:
cordova plugin add cordova-plugin-nativestorage
or through this git repo if you want to be running the development version:
cordova plugin add https://github.com/TheCocoaProject/cordova-plugin-nativestorage
If you're using ngCordova you can use the ngCordova-wrapper:
bower install git://github.com/TheCocoaProject/ngcordova-wrapper-nativestorage --save-dev
For more information about the usage of the plugin check the repo for the ngCordova-wrapper - Ionic V1. The plugin is also supported for Ionic, please check the official Ionic documentation for the installation procedure and use.
Remove the plugin from the current project:
cordova plugin remove cordova-plugin-nativestorage
Install the developer version from Github:
cordova plugin add https://github.com/TheCocoaProject/cordova-plugin-nativestorage
The parameter of the success-callback function will be the saved or retrieved value, the error-callback will specify the occurred error.
As of version v2.0 all data types that can be stringified can be stored with the setItem
and getItem
method, see storing values. A more fine grained storage method is also provided. These methods can be used to store type-specific data types, see API prior to v2.
NativeStorage.setItem("reference_to_value",<value>, <success-callback>, <error-callback>);
NativeStorage.getItem("reference_to_value",<success-callback>, <error-callback>);
NativeStorage.keys(<success-callback>, <error-callback>);
Removing a single variable:
NativeStorage.remove("reference_to_value",<success-callback>, <error-callback>);
Removing all stored variables:
NativeStorage.clear(<success-callback>, <error-callback>);
App Groups (share data between apps) First the suite name must be provided before accessing and retrieving data.
NativeStorage.initWithSuiteName("suitename");
var app = {
initialize: function () {
this.bindEvents();
},
bindEvents: function () {
document.addEventListener('deviceready', this.onDeviceReady, false);
},
onDeviceReady: function () {
var obj = {name: "NativeStorage", author: "GillesCallebaut"};
// be certain to make an unique reference String for each variable!
NativeStorage.setItem("reference", obj, this.setSuccess, this.setError);
},
setSuccess: function (obj) {
console.log(obj.name);
NativeStorage.getItem("reference", this.getSuccess, this.getError);
},
setError: function (error) {
console.log(error.code);
if (error.exception !== "") console.log(error.exception);
},
getSuccess: function (obj) {
console.log(obj.name);
NativeStorage.remove("reference", this.removeSuccess, this.removeError);
},
getError: function (error) {
console.log(error.code);
if (error.exception !== "") console.log(error.exception);
},
removeSuccess: function () {
console.log("Removed");
},
removeError: function (error) {
console.log(error.code);
if (error.exception !== "") console.log(error.exception);
}
};
app.initialize();
### <a name="ngcordova_example"></a>ngCordova (Ionic V1) example
```javascript
var app = angular.module('starter.controllers', ['ngCordova.plugins.nativeStorage'])
app.controller('myCtrl', function ($ionicPlatform, $scope, $cordovaNativeStorage, $log) {
$ionicPlatform.ready(function () {
$scope.$apply(function () {
$cordovaNativeStorage.setItem("ref", "value").then(function (value) {
$log.log(value);
$cordovaNativeStorage.getItem("ref").then(function (value) {
$log.log(value);
}, function (error) {
$log.log(error);
});
}, function (error) {
$log.log(error);
});
});
});
});
A demo application can be found at cordova-plugin-nativestorage/examples/demo
. This application will save a String when the SAVE (btn_load
) is pushed. This String is the value which has been typed in the input field (data_input
). When the LOAD button is pressed, the value is shown by means of an alert message.
git clone https://github.com/GillesC/cordova-plugin-nativestorage.git
cd cordova-plugin-nativestorage/examples/demo/
cordova platform add ios
cordova platform add android
cordova platform add browser
cordova platform add windows
cordova plugin add cordova-plugin-nativestorage
cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-test-framework.git
cordova plugin add https://github.com/TheCocoaProject/cordova-plugin-nativestorage.git#:/tests
cordova emulate ios
cordova run android
cordova run browser
cordova run windows
Is it safe to store sensitive data via this plugin?
Error object contains:
the code contains an integer whichs specifies the occurred error/problem
NATIVE_WRITE_FAILED
= 1ITEM_NOT_FOUND
= 2NULL_REFERENCE
= 3UNDEFINED_TYPE
= 4JSON_ERROR
= 5WRONG_PARAMETER
= 6If you encounter any problems, please remove the current plugin and re-add it. This will install the latest version.
If you have code issues, things not related to a bug of the plugin please consider posting your question on Stackoverflow. And add our own tag, cordova-nativestorage.
ng-app
from body
index.html
:<script type="text/javascript"> document.addEventListener('deviceready', function onDeviceReady() { angular.bootstrap(document.querySelector('body'), ['starter']); }, false); </script>
Unknown provider: $cordovaNativeStorageProvider
Failed to instantiate module ngCordova.plugins.nativeStorage
Module 'ngCordova.plugins.nativeStorage' is not available
bower.json
) to see if everything is correctSharedpreferences
in Android and NSUserDefaults
in iOS.android:allowBackup=false
in the application tag of AndroidManifest.xml. More information at this issue and this StackOverflow question.Sharedpreferences
in Android and NSUserDefaults
in iOS. These strategies are designed for storing data quick and easy. See the usage of the plugin for more info about DB vs NativeStorage.If you're utilizing this plugin and wish to add your application to this readme, please contact me.