Manipulate DB Objects

Creating objects

A new object can be created using the syntax DB.model.create().

As an example, suppose we have a model "person" with a field "name".

We would define a variable for the object, and initialise it as follows:

View XML:

main.xml

<view ...>
    <var name="visitor" type="person" />
</view>

... and View JavaScript:

main.js

function init() {
    view.visitor = DB.person.create();
    view.visitor.name = "John";
}

All objects that are defined as variables in a view are saved automatically whenever a view is dismissed, but not when the user presses the back button. However, when defining an object only in JavaScript/TypeScript (and not in the view), you need to save the object manually:

JS

main.js

var visitor = DB.person.create();
visitor.name = "John";
visitor.save();

TS

main.ts

let visitor = await DB.person.create();
visitor.name = "John";
await visitor.save();

Setting datetimes

datetime fields are represented as the JavaScript/TypeScript Date type. To set a datetime to the current date and time, use new Date(). To set it to a specific time and date, use new Date(year, month, day, hour, minute, second). For more details, see this article at Mozilla.

Example:

main.js

view.current_time = new Date();

Setting dates

date fields are represented as a Day object. To set a date field to the current date, use new Day(). To set it to a specific date, use new Day(year, month, day).

Examples:

main.js

view.registration_date = new Day();
view.birthdate = new Day(1972, 3, 19);
var day = new Day("2014-01-05") // Parse some day.
var day = new Day(new Date());  // Convert Date to Day, in local timezone.

The Day object has additional functionality:

day.startOfDay();  // Start of day in local timezone, as a Date
day.endOfDay();    // End of day in local timezone, as a Date
day.toString();    // "2014-01-05"
day.toISOString(); // "2014-01-05"
day.toJSON();      // "2014-01-05"
day.valueOf();     // 1388880000000
day.getYear()      // 2014
day.getMonth()     // 0-11. January is 0, December is 11
day.getDay()       // Day of the month (1-31).
day.getDayOfWeek()  // Day of week (0-6). Sunday is 0, Saturday is 6.

Deleting objects

An object can be deleted using its destroy() function.

As an example, suppose we have a model "person":

View XML:

main.xml

<view ...>
    <var name="visitor" type="person" />
</view>

... and View JavaScript:

main.js

view.person.destroy();

Setting relationships

Unlike fields, a relationship is set using a setter function.

As an example, suppose that in our Data Model every person is part of a household:

schema.xml

<data-model>
    <model name="person">
        <field name="name" type="text" />
        
        <belongs-to model="household" />
        
        <display>{name}</display>
    </model>
    
    <model name="household">
        <field name="address" type="text" />
        
        <has-many model="person" name="members" />
        
        <display>{address}</display>
    </model>
</data-model>

In our view we define our household and person:

main.xml

<view ...>
    <var name="member" type="person" />
    <var name="household" type="household" />
</view>

... and initialize them in JavaScript:

main.js

function init() {
    view.household = DB.household.create();
    view.member = DB.person.create();
    view.member.household(view.household);
}

As you can see, we set the "household" relationship on the "member" by calling the household() function and passing the related "household" object as an argument.

As a more typical example, the household will be created in another view and passed as a parameter:

main.xml

<view ...>
    <param name="household" type="household" />
    <var name="member" type="person" />
</view>

... and the JavaScript:

main.js

function init() {
    view.member = DB.person.create();
    view.member.household(view.household);
}

Getting relationships

Getting a related object works that a particular object belongs to is done by calling a getter function, as seen below:

main.js

view.member.household();

Further Reading

When processing large datasets it is recommended to use batch operations. Please see the corresponding documentation here.