= EdenMobile Database =
[[TOC]]

== emResources Service ==

Access to user data is provided by the {{{emResources}}} service:

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

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

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

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

See also: [wiki:DeveloperGuidelines/EdenMobile/Database/Resources 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:

{{{
#!js
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 ==

{{{
#!div class="important" style="border: 2pt solid; text-align: center; width:80%"
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:

{{{#!js
// 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).

{{{#!js
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'                  
    }
}
}}}