JavaScript client in an ASP.NET application

This section contains details on how to connect to the zkBox server from JavaScript in an ASP .NET application.
The calls from the JavaScript of your application are not accessing directly the zkBox server, but instead everything is passed throught a zkBox proxy installed in your application server side. This is mainly necessary because all the calls should be signed with the secret key of your zkBox application.
You'll see an example for each API client function and also with the possible return response.
The library is available in the downloads section.

Users

Check user

This method is check if an user exists into the system.

javascript call

var result = $zkBox.CheckUser(

"john");

javascript return

true

or, if the operation failed

null

Add user

This method is adding a new user into the system.

javascript call

var result = $zkBox.AddUser(

"john",
"SeCrEtP@ssw0rd");

javascript return

true

or, if the operation failed

null

Authenticate user

This method is authenticating an user into the system.

javascript call

var result = $zkBox.AuthenticateUser(

"john",
"SeCrEtP@ssw0rd");

javascript return

true

or, if the operation failed

null

Update user

This method is updating the calling user's password.

javascript call

var result = $zkBox.UpdateUser(

"john",
"OLDpassw0rd",
"SeCrEtP@ssw0rd");

javascript return

true

or, if the operation failed

null

Logout user

This method is logging out from the system a logged in user.

javascript call

var result = $zkBox.Logout();

javascript return

true

or, if the operation failed

null

Delete user

This method is deleting the calling user from the system.

javascript call

var result = $zkBox.DeleteUser();

javascript return

true

or, if the operation failed

null

Objects

Add object

This method is adding an object into the system.

javascript call

var result = $zkBox.AddObject(

{
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
});

javascript return

{
objectId: "A6HNCRFZMDMMC4VW"
}

or, if the operation failed

null

Get object

This method is retrieving an existing object.

javascript call

var result = $zkBox.GetObject(

{
objectId: "A6HNCRFZMDMMC4VW"
});

javascript return

{
objectId: "A6HNCRFZMDMMC4VW",
type: "notes",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
}

or, if the operation failed

null

Update object

This method is updating an existing object into the system.

javascript call

var result = $zkBox.UpdateObject(

{
objectId: "A6HNCRFZMDMMC4VW",
data: "U2FsdGVkX18EBQYHAAECA7VOPk63Te+RMnHu8Baf[...]"
});

javascript return

true

or, if the operation failed

null

Delete object

This method is deleting an existing object.

javascript call

var result = $zkBox.DeleteObject(

{
objectId: "A6HNCRFZMDMMC4VW"
});

javascript return

{
type: "notes"
}

or, if the operation failed

null

Get objects list

This method is getting one or more objects. If there is no parameter specified, then all the objects are retrieved. If the "type" parameter is provided, then all objects of that type are retrieved. If a list of identifiers is provided, then only those objects are retrieved

javascript call

var result = $zkBox.GetObjectsList(

{
type: "null",
objectsList: ["FIR8JUFUO3Q1YFSQ", "A6HNCRFZMDMMC4VW", ...]
});

javascript return

[
{
objectId: "FIR8JUFUO3Q1YFSQ",
type: "account-preferences",
data:
{
theme: "vivid"
autosave: "true"
}

},
{
objectId: "A6HNCRFZMDMMC4VW",
type: "note",
data:
{
content: "Lorem ipsum dolor sit amet, consectetur[...]"
}

},
...
]

or, if the operation failed

null

Get objects list IDs

This method is getting the identifiers of all user's objects or only the ones of a given type. If there is no parameter specified, then the identifiers for all the objects are retrieved. If the "type" parameter is provided, then the identifiers of all objects of that type are returned.

javascript call

var result = $zkBox.GetObjectsListIDs(

{
type: "notes"
});

javascript return

[
"5FAUHANNFAI6NKD0",
"A6HNCRFZMDMMC4VW"
...
]

or, if the operation failed

null

Set single object

This method is setting on object of a given type. There is only one object of that given type.

javascript call

var result = $zkBox.SetSingleObject(

{
type: "account-settings",
data: { autolocktime: "10" }
});

javascript return

true

or, if the operation failed

null

Get single object

This method is getting on single object for a given type. There is only one object of that given type. If the object of the given type doesn't exist the default data is returned.

javascript call

var result = $zkBox.GetSingleObject(

{
type: "account-settings",
dataDefault: { autolocktime: "30" }
});

javascript return

{
objectId: "A6HNCRFZMDMMC4VW",
type: "account-settings",
data: { autolocktime: "10" }
}

or, if the operation failed

null

Transactions

Run a transaction

This method is executing multiple operations in a single transaction. Use this operation to ensure a consistent state of data in your application.

javascript call

var result = $zkBox.RunTransaction(

function(tran)
{
// add the note content
return tran.AddObject(
{
type: "nc",
data: { content: "some note content" }
});
},
function(tran)
{
// this is the previously added objectId
addedNoteId = tran.prevResult;

// add the new noteId to the notes list
notesList.push(addedNoteId);

// save the notes list
return tran.SetSingleObject(
{
type: "notes-list",
data: notesList
});
},
function(tran)
{
// return the added note id
return tran.results[0];
});

javascript return

"A6HNCRFZMDMMC4VW"

or, if the operation failed

null

Batch

Run batch

This method is executing multiple operations in a batch. Use this method, where possibleto cumulate multiple operation in a one single call to the zkBox server.

javascript call

var result = $zkBox.RunBatch(

{
atStartBeginTransaction: "true",
atEndCommitTransaction: "true",
onErrorRollbackTransaction: "true",
operations:
[
{
operation: "AddObject",
type: "expense",
data: { title: "pizza at Jerry's", amount: "32.5" }
},
{
operation: "GetObject",
objectId: "Y2SRP7AAJMK5CMWO"
}
]
});

javascript return

[
{
objectId: "241O748I1ZO51TQC"
},
{
objectId: "Y2SRP7AAJMK5CMWO",
type: "book",
data:
{
title: "The Catcher in the Rye",
pages: "288"
}
}
]

or, if the operation failed

null