EdenMobile Database

emResources Service

Access to user data is provided by the emResources service:

To use the service, it must be included in the controller dependencies:

EdenMobile.controller("MyController", [
    '$scope', '$stateParams', 'emResources',
    function($scope, $stateParams, emResources) {

        emResources.open(resourceName).then(function(resource) {

            // Do something with the resource
        });
    }
]);

See also: EdenMobile Resources API

emResources uses the emDB service to access the database.

emDB Service

EdenMobile provides the emDB service to access the database.

To use the service, it must be included in the controller dependencies:

EdenMobile.controller("MyController", [
    '$scope', '$stateParams', 'emDB',
    function($scope, $stateParams, emDB) {
        // controller code goes here
    }
]);

emDB automatically creates the database and tables when it is initialized for the first time.

API

Remember that all database transactions are asynchronous! Callback functions may therefore need to perform a $scope.$apply to trigger a digest cycle explicitly.

table

The table API provides fundamental methods to access data in database tables, examples:

// Instantiate the API with the table name
table = $emdb.table("mytable");

// Insert records into the table
table.insert({
    // The data to insert
    'name': 'Example',
    'number': 4
}, function(recordID) {
    // Callback function after successful insert
});

// Select records from the table - general pattern
var fields = ['id', 'name'],
    query = 'number > 3';
table.select(fields, query, function(result) {
    var rows = result.rows,
        record;
    for (var i=0, len=rows.length; i<len; i++) {
        record = rows.item(i);
        // do something with the record
    }
});

// Other variants of select:
// Extract all records, but only certain fields
table.select(fields, function(result) {
    // process the result
});

// Extract all fields, but only certain records
table.select(query, function(result) {
    // process the result
});

// Extract all fields from all records
table.select(function(result) {
    // process the result
});

Default Schema

The database schema is stored in the mobile database, in the em_schema table.

For the initial setup of the database, a static emDefaultSchema (in www/config/schema.js) is used. Once this schema has been written to the new database, it will be ignored.

The emDefaultSchema service also defines the meta-fields which are to be added to all user tables.

emSQL

$emDB uses the emSQL service to construct common SQL statements. It can be found in www/services/sql.js.

Components

Components are supported (currently only direct foreign-key relationships).

Components must be declared in the master table schema (see Table Schema Format).

Table Schema Format

The following format is used for both emDefaultSchema, and schema imports (as JSON).

var tableSchema = {

    // The table name
    _name: 'person',

    // Fields in the table
    'first_name': {             // Field name (key)
        type: 'string',         // Field type (required)
        label: 'First Name',    // Label in form
        placeholder: 'Jane',    // Placeholder (text fields only)
        notnull: true           // NOT NULL constraint
    },
    'last_name': {
        type: 'string',
        label: 'Last Name',
        placeholder: 'Doe'
    },
    'date_of_birth': {
        type: 'date',
        label: 'Date of Birth'
    },
    'missing': {
        type: 'boolean',
        label: 'Missing'
    },
    'gender': {
        type: 'integer',
        label: 'Gender',
        options: {2: 'female',  // Fixed set of options
                  3: 'male'     // value: label
                  },
        defaultValue: 2         // Default value
    },

    // Fields in the form (in order)
    _form: [
        'first_name',
        'last_name',
        'gender',
        'missing',
        'date_of_birth'
    ],

    // Data list card template
    _card: {

        // Fields to extract (analogous to "list_fields", required)
        fields: ['first_name', 'last_name'],

        // AngularJS expression for the card title
        title: '{{record.first_name}} {{record.last_name}}'
    },

    // CRUD strings and icons
    _strings: {

        // name and namePlural will be used as page titles
        name: 'Person',
        namePlural: 'Persons',

        // Icon for the form list
        icon: 'ion-person-stalker'
    },

    // Component declaration
    _components: {

        'photo': {                      // Component name (alias)
            title: 'Photos',            // Component title ("tab" title)
            resource: 'person_photo',   // Component table name (required)
            joinby: 'person_id',        // Name of the the joinby-key (required)
            multiple: true              // Multiple-setting (default true)
        }
    }
},

{
    // Component table
    _name: 'person_photo',

    'person_id': {

        // Lookup-field (component key)
        type: 'reference person',       
        notnull: true,

        // Representation of foreign keys:
        // - list of field names, values will be concatenated
        //   in order, separated by blanks
        represent: ['first_name', 'last_name']

    },
    'photo': {

        // Upload-fields automatically use photo widget
        type: 'upload'                  
    }
}