The JayData ItemStore API 101

Author: Peter Aron Zentai November 4th, 2012

html5, ItemStore Api, JayData examples, JayData providers

The JayData ItemStore API is an ideal data library for most client data solutions, where information has to be stored on the client on a durable manner. For example persisting the cart in an E-Shop or recording unsaved form data to survive an unintentional F5 in the browser. No matter what the client capabilities are in terms of local data storage, JayData will find the best fit by probing for sqLite, indexedDb and HTML5 localStore. Or if you wanted to use cloud data instead of the client databases, with the help of the ItemStore API you can work with cloud hosted data endpoints as easily as you did it with local stores.

The JayData ItemStore API is a simplified API on the top of the JayData Entity classes to allow simple but common data management tasks to be done in even less code. While the JayData Entity API with its ORM approach is perfect for complex data models the ItemStore API in its design is closer to what most jQuery users are familiar with: a simple promise based fluent API and is a more convenient way to deal with simple data models.

Setup client

You will need jQuery and JayData for the following examples to work.

<script src="http://code.juery.com/jquery.js"></script>
<script src="http://include.jaydata.org/jaydata.js"></script>
<script>//work with $data here</script>

Define the CartItem model to work with

The ItemStore API in the current release only provides typed data management: you have to define what fields you data object will have prior storing that kind of information. Untyped JSON object support will come in the following release.

Use the $data or jayData global variables as the entry point to work with data.

$data.define('CartItem', { ProductName: String, ProductID: Number, Amount: Number });

1	$data.define('CartItem', { ProductName: String, ProductID: Number, Amount: Number });

API comparison

ItemStore API

Entity Classes API

  $data.define(<span class="str">'CartItem'</span>, {
              ProductName: String,
              ProductID: Number,
              Amount: Number
  });

$data.define(<span class="str">'CartItem'</span>, {

ProductName: String,

ProductID: Number,

Amount: Number

});

  $data.Entity.extend("CartItem", {
    Id: { key: true, computed: true },
    ProductName: { type: String },
    ProductID: { type: Number },
    Amount: { type: Number }
  })

  $data.EntityContext.extend("CartItemsDB", {
   Items:{ type: $data.EntitySet, elementType: CartItem }
  });

 var db = new CartItemsDB({
        name:'local', databaseName: 'CartItems'
  });

$data.Entity.extend("CartItem", {

Id: { key: true, computed: true },

ProductName: { type: String },

ProductID: { type: Number },

Amount: { type: Number }

})

$data.EntityContext.extend("CartItemsDB", {

Items:{ type: $data.EntitySet, elementType: CartItem }

});

var db = new CartItemsDB({

name:'local', databaseName: 'CartItems'

});

Calling $data.define is only required once per application run, best is on the application start. Subsequent calls redefine the CartItem type.

Create and save a new data item

$data(‘typeName’) provides the CartItem type that eventually provides a static API to work with. Use save() to create or update data.

$data("CartItem") .save({ 
    ProductName: 'Tea', 
    Amount: 1, 
    ProductID: 15
}).then(function (newItem) {
    var r = JSON.stringify(newItem);
    $('#output').append(r); 
});

$data("CartItem") .save({

ProductName: 'Tea',

Amount: 1,

ProductID: 15

}).then(function (newItem) {

var r = JSON.stringify(newItem);

$('#output').append(r);

});

API Comparison

ItemStore API

Entity Classes API

$data("CartItem")
    .save({ 
        ProductName: 'Tea',
        Amount: 1,
        ProductID: 15,
    })
    .then(function (newItem) {
       var r = JSON.stringify(newItem)
       $('#output').append(r);
    });

$data("CartItem")

.save({

ProductName: 'Tea',

Amount: 1,

ProductID: 15,

})

.then(function (newItem) {

var r = JSON.stringify(newItem)

$('#output').append(r);

});

var cart = new CartItem();
cart.ProductName = 'Tea';
cart.Amount = 1;
cart.ProductID = 15;
db.CartItems.add(cart);
db.saveChanges(function () {
    var r = JSON.stringify(newItem);
    $('#output').append(s);
});

var cart = new CartItem();

cart.ProductName = 'Tea';

cart.Amount = 1;

cart.ProductID = 15;

db.CartItems.add(cart);

db.saveChanges(function () {

var r = JSON.stringify(newItem);

$('#output').append(s);

});

The result:

Alternatively you can mix the typed approach with the fluent API:

var newItem = new CartItem();
newItem.ProductName = "Tea";
newItem.save();

var newItem = new CartItem();

newItem.ProductName = "Tea";

newItem.save();

Get all previously saved data with readAll

Once you saved one or more items the next thing you will want to do is reclaiming them. Use the readAll function for that:

$data("CartItem") .readAll().then(function (items) {
    items.forEach(function (item) {
        var t = item.ProductName + " " + item.Id;
        $("#output").append(t +"<br/>"); 
    });
});

$data("CartItem") .readAll().then(function (items) {

items.forEach(function (item) {

var t = item.ProductName + " " + item.Id;

$("#output").append(t +"<br/>");

});

Get previously saved data based on its Id/Key

If you need a specific item from the set of items you need to know its unique identifier. Unique IDs are autogenerated if the model does not provide any key information.

$data("CartItem") .read(42).then(function (item) {
    var t = item.ProductName + " " + item.Id;
    $("#output").append(t +"<br/>");
});

$data("CartItem") .read(42).then(function (item) {

var t = item.ProductName + " " + item.Id;

$("#output").append(t +"<br/>");

});

Update data with save()

$data("CartItem") .read(42).then(function (item) {
    item.amount += 1; 
    return item.save(); 
}) .then(function () {
    alert("item updated!");
});

$data("CartItem") .read(42).then(function (item) {

item.amount += 1;

return item.save();

}) .then(function () {

alert("item updated!");

});

Remove data by key

$data("CartItem").read(1).then(function (item) {
    return item.remove(); 
}).then(function (item) { 
    alert("item removed:" + item.Id); 
});

$data("CartItem").read(1).then(function (item) {

return item.remove();

}).then(function (item) {

alert("item removed:" + item.Id);

});

RemoveAll

The removeAll method is convenient if you want to wipe out the entire collection without actually knowing what items will be removed.

$data("CartItem") .removeAll().then(function (items) {
    alert("items removed:" + items.length);
});

$data("CartItem") .removeAll().then(function (items) {

alert("items removed:" + items.length);

});

html5, ItemStore Api, JayData examples, JayData providers

JayData.org