Documentation

HDDatabase

Object to provide access to long-term persistent storage.

Object Properties & Methods

 constructorConstruct an HDDatabase object.
 deleteRecordRemove a record from the database
 errorReturns information about the last database error
 findSearch the database
 getRetrieve a previously stored record from the database
 putStore a record in the database

constructor

MethodFirst available in version 1.0.0

Construct an HDDatabase object.

Usage:

var db = new HDDatabase(name);

Arguments:

nameThe name of the database. (string)

Example:

// Create an HDDatabase object for the "db1" database:
var db = new HDDatabase("db1");

deleteRecord

MethodFirst available in version 1.0.0

Remove a record from the database.

Usage:

db.removeRecord(id);

Arguments:

idThe unique identifier of the record to be deleted.

Returns true on success or false on an error. In the event of an error, more details are returned by the db.error() method.

Example:

// delete a record
var db = new HDDatabase("my-database");
var success = db.deleteRecord("record-id-1");
if(!success)
{
	console.log(db.error());
}

error

MethodFirst available in version 1.0.0

Returns information about the last database error.

Usage:

db.error();

Returns information about the last database error, or null if no error has occurred.

Example:

var err = db.error();
console.log("Database error: " + err);

find

MethodFirst available in version 1.0.0

Search the database for records containing fields with certain values. You can also request that a partial match be performed. (When you know the record's unique identifier, use the simpler get() method instead.)

Usage:

db.find(match_fields);

Arguments:

match_fieldsA JavaScript object containing the fields and values to be matched. Only records with matching field values will be returned. Include a percent-sign (%) at the end of of a field value to indicate that a partial match should be performed. Pass an empty object ({}) to return all records.

Returns an array of matching records, or false if there was an error.

Example:

// find all records where the last name begins with "Smi"
var match_fields = {};
match_fields.lastName = "Smi%";

var db = new HDDatabase("my-database");
var results = db.find(match_fields);
if(results == false)
{
	console.log("error: " + db.error());
	return;
}

// log the results.
for(var i = 0; i < results.length; i++)
{
	var record = results[i];
	var name = record["lastName"] + ", " + record["firstName"];
	console.log("Found: " + name);
}

// or, get all records:
var match_fields = {};
var results = db.find(match_fields);

// even shorter version:
var results = db.find({});

get

MethodFirst available in version 1.0.0

Retrieve a previously stored record from the database.

Usage:

db.get(id);

Arguments:

idThe record's unique identifier. (string or number)

Returns a JavaScript object containing the record fields and values, or null if no record exists in this database for that identifier.

Example:

// Retrieve a record from the database
var db = new HDDatabase("my-database");
var record = db.get("record-id-1");
if(record == null)
{
	console.log("record-id-1 not found");
}
else
{
	console.log("field1 = " + record["field1"]);
}

put

MethodFirst available in version 1.0.0

Store a record in the database.

Usage:

db.put(id, record);

Arguments:

idThe unique identifier that will be used to store this record. The record can later be retrieved by this identifier. (string or number)
valueA JavaScript object containing the record fields and values to be stored.

Returns true on success or false on an error. In the event of an error, more details are returned by the db.error() method.

Example:

// create a record
var record = {};
record["field1"] = "value1";
record["field2"] = 123;

// store it
var db = new HDDatabase("my-database");
var success = db.put("record-id-1", record);
if(!success)
{
	console.log(db.error());
}

Alternate usage:

db.put(record);

If you want to store a new record and have Handheld Designer automatically create a unique identifier, simply pass the record to the put() method without an id parameter. The server will store the record, generate a new unique identifier, and save the generated id in the record under the _id field.

Example:

// create a record
var record = {};
record["field1"] = "value1";
record["field2"] = 123;

// store it
var db = new HDDatabase("my-database");
db.put(record);
if(!success)
{
	console.log(db.error());
}

var newIdentifier = record["_id"];

Copyright © 2010-2017, Handheld Designer, LLC, All Rights Reserved.
Made by hand in New England, USA.