TheCocoaProject / cordova-plugin-nativestorage

Cordova plugin: Native storage of variables in Android, iOS and Windows
http://thecocoaproject.github.io/
Apache License 2.0
292 stars 106 forks source link
android cordova-nativestorage cordova-plugin ionic ios persistent-data storage windows

Cordova plugin NativeStorage

npm version Build Status Known Vulnerabilities

NPM

Join the chat for questions and updates Join the chat at https://gitter.im/TheCocoaProject/cordova-plugin-nativestorage


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}.


:) As per npm-stat we just crossed 150k downloads!! Thanks to everyone who helped and to everyone who have send in their kind words!

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.

Contents

Why?

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:

When to use the plugin

Examples

Storage of:

When not to use the plugin

Scientific Articles

Assessment of Data Storage Strategies Using the Mobile Cross-Platform Tool Cordova

Installation

The plugin can be installed via the Cordova command line interface:

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.

Reinstalling/installing developer version

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

Supported platforms

Supported frameworks

Usage

The parameter of the success-callback function will be the saved or retrieved value, the error-callback will specify the occurred error.

Supported data types

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.

Storing values

NativeStorage.setItem("reference_to_value",<value>, <success-callback>, <error-callback>);

Retrieving values

NativeStorage.getItem("reference_to_value",<success-callback>, <error-callback>);

Retrieving all keys

NativeStorage.keys(<success-callback>, <error-callback>);

Removing values

Removing a single variable:

NativeStorage.remove("reference_to_value",<success-callback>, <error-callback>);

Removing all stored variables:

NativeStorage.clear(<success-callback>, <error-callback>);

iOS specific features

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);
            });
        });
    });
});

Demo Example

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.

Installation

Security

Is it safe to store sensitive data via this plugin?

Errors

Error object contains:

Error codes

the code contains an integer whichs specifies the occurred error/problem

Problems

If 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.

F.A.Q.

Applications using this plugin

If you're utilizing this plugin and wish to add your application to this readme, please contact me.