Home

Awesome

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

<a name="why"></a>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:

<a name="when"></a>When to use the plugin

Examples

Storage of:

When not to use the plugin

<a name="articles"></a>Scientific Articles

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

<a name="installation"></a>Installation

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.

<a name="reinstalling_dev"></a>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

<a name="supported_platforms"></a>Supported platforms

<a name="supported_frameworks"></a>Supported frameworks

<a name="usage"></a>Usage

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

<a name="supported_data_types"></a>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.

<a name="storing_values"></a>Storing values

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

<a name="retrieving_values"></a>Retrieving values

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

<a name="retrieving_keys"></a>Retrieving all keys

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

<a name="removing_values"></a>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

NativeStorage.initWithSuiteName("suitename");

<a name="example"></a>Example

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

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 name="demo_example"></a>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

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

<a name="security"></a>Security

Is it safe to store sensitive data via this plugin?

<a name="errors"></a>Errors

Error object contains:

Error codes

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

<a name="problems"></a>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.

<a name="FAQ"></a>F.A.Q.

<a name="applications"></a>Applications using this plugin

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