Home

Awesome

Cordova plugin NativeStorage cordova-ios@3.9.2 compatible

Build Status npm version

NPM

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

NEW: Windows 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="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 1. The plugin is also supported for Ionic 2, pleas 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="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="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>);

###<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) 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="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.