Documentation : Titanium References

Prelude

This document will provide you with detailed documentation about creating Mobeelizer client application on Titanium platform.

In this document we assumes that you are familiar with:

Configure your application

Attach necessary resources

Download Mobeelizer Titanium SDK and follow using modules guide.

Add application definition

Next, download XML file of your application created in App Designer and put it in your Resources directory. If you use default setting then name of this file should be application.xml. You can use other name - but then you have to set definitionAsset property (see below)

Create properties file

In Resources directory you have to create mobeelizer.properties file. Inside you must specify properties in key = value format. Available configuration properties are:

NameRequiredDescription

mode

YES

There are three possible development modes:

  • development - application works off-line. Login and synchronization methods are mocked - they do nothing but returning success status. This mode allows you to develop client application completely separate from cloud deployment and management. Defining developmentRole parameter is necessary with this mode.

  • test - application will connect to test environment.

  • production - application will connect to production environment.

developmentRole

NO

This parameter is required only in 'development' mode - it is ignored on other modes.

Normally while login method system receives role of user. But as you can read above login method is off-line in development mode so you have to provide user role manually - as value of this parameter.

device

YES

Name of device category. See this document for more explanation.

definitionAsset

NO

Name of XML file with application definition. Default value is application.xml.

Obtain Mobeelizer object

To obtain Mobeelizer module object just call:

var Mobeelizer = require('ti.mobeelizer.sdk');

Log in to application

Before using any of Mobeelizer features you have to make user log in to your cloud application. Any activity - like accessing database - before login will have effect in throwing an exception!

You can do that by calling one of login static methods from Mobeelizer object. There are four version of this method:

  • synchronous, with default environment name
var error = Mobeelizer.loginAndWait(user, password);
 
if(error) {
  // login error, more info in error.message
}
  • asynchronous, with default environment name
Mobeelizer.login(user, password, function(e) {
	// login success
}, function(e) {
	// login error, more info in e.message
});
  • synchronous, with environment name
var error = Mobeelizer.loginToInstanceAndWait(instance, user, password);
 
if(error) {
  // login error, more info in error.message
}
  • asynchronous, with environment name
Mobeelizer.loginToInstance(instance, user, password, function(e) {
	// login success
}, function(e) {
	// login error, more info in e.message
});

You have to remember, that when you log in any user for the first time your client application must be on-line (except 'development' mode.) Also first login can take long time to perform - because of initial synchronization processes that are automatically triggered after login verification. So better supply user with nice looking loading indicator. And remember - DO NOT call synchronous methods in main thread - you application will freeze and can be killed by operating system after some time.

Also you may wonder what is the environment name. Firstly see this document to read about environments. As you can read there, when you create an app, then two environments are created - one for test and one for production purpose. They are named accordingly "test" and "production". When you want to connect to these instances use default environment name method. But if you want to connect with environment manually created - you have to provide its name.

To change user you should use logout method:

Mobeelizer.logout();

Remember to finish all background processes before calling it - logging out while synchronization process can effect with unpredictable connector behavior!

Use database

Obtaining database object

Database can be accessed using object MobeelizerDatabase which can be obtained by calling method:

var database = Mobeelizer.getDatabase();
Remember that to use database user have to be logged in.
You shouldn't connect to database directly without MobeelizerDatabase object! SDK will loose track of changes tracking and synchronize functionality will not work properly!

Entity object

Most of the database methods operates on MobeelizerEntity objects.

You can obtain MobeelizerEntity from database by calling list or findOne methods (see below) or create new one by:

var entity = database.entity("entityType");

where entityType is a name of the model.

MobeelizerEntity has methods:

var model = entity.getModel(); // returns entity model

var guid = entity.getGuid(); // returns object identifier
entity.setGuid("newGuid"); // sets new object identifier

var owner = entity.getOwner(); // returns owner of object
var conflicted = entity.isConflicted(); // returns true if object is conflicted
var modified = entity.isModified(); // returns true if record was modified by user - but not synchronized yet
var deleted = entity.isDeleted(); // returns true if object was deleted

var fieldValue = entity.getField("fieldName"); // returns field value
entity.putField("fieldName", newValue); // sets new field value

Basic operations

MobeelizerDatabase object allows you to easily perform basic database operations. Let say you have model 'Product'.

Then you can write:

var allProducts = database.list("Product"); // returns list of MobeelizerEntity objects
var count = database.count("Product"); // counts all "product" type entities
var product = database.findOne("Product", "guidIdentifier"); // return single MobeelizerEntity object
var exists = database.exists("Product", "guidIdentifier"); // returns true if product with given guid exists

var product = database.entity("Product"); // creates new MobeelizerEntity
// fill entity
var errors = database.save(product); // saves entity
if(errors) {
	// notify the user about validation errors
}

database.removeObject(product); // removes object from database
database.remove("Product", "guidIdentifier"); // removes product with given guid
database.removeAll("Product"); // removes all "product" type entities

Notice that save method returns MobeelizerErrors object. On this object you can:

var isValid = errors.isValid(); // returns true if no errors
var globalErrors = errors.getErrors(); // returns list of global errors
var isFieldValid = errors.isFieldValid("fieldName"); // returns true if field is valid
var fieldErrors = errors.getFieldErrors("fieldName"); // returns list of field errors
// method on single error:
var error = globalErrors[0];
var errorCode = error.getCode(); // returns error code
var errorMessage = error.getMessage(); // returns error message (english)
var errorArgs = error.getArgs(); // returns error arguments

For more informations see titanium module documentation.

Relations

To define relation you have to add 'belongs to' type field to model. Lets say you have models Order and OrderPosition. To connect these objects with relation you have to add 'belongs to' field to OrderPosition - let's name it order.

As you can read above 'belongs to' type has to be mapped as String field. This field will contain identifier of related object. So you can write:

// ------- create new order with positions
var order = database.entity("Order");
// fill order fields
var orderSaveErrors = database.save(order);
var position = database.entity("OrderPosition");
// fill position fields
position.putField("order", order.getGuid());
var positionSaveErrors = database.save(position);

// ------- get order of position:
var position = database.findOne("OrderPosition", "positionIdentifier");
var order = database.findOne("Order", position.getField("order"));

Files

All binary data are wrapped inside MobeelizerFile object. Lets assume that you have OrderWithAttachment object. And it have attachment field of file type. Then you can access content of file by coding:

var order = database.findOne("OrderWithAttachment", "orderIdentifier");
var attachment = order.getField("attachment");
var attachmentIdentifier = attachment.getGuid();
var attachmentName = attachment.getName();
var attachmentBlob = attachment.getStream();

To create new MobeelizerFile instance you can:

// ------- create new file...
var file = // get file
var newAttachment = Mobeelizer.createFile("newAttachmentName", file.read());

// ------- ...or use existing one
var newAttachment = Mobeelizer.getExistingFile("newAttachmentName", "existingAtachmentGuid");

Remember about changing order file field:

var order = // get object from database or create new one
order.putField("attachment", newAttachment);
var orderSaveErrors = database.save(order);

Advanced database queries

Advanced queries can be accessed by MobeelizerCriteriaBuilder class.To get criteria object just call method:

var query = database.find("modelName");

Next define your query (see below). After that you can:

// get list of objects meeting query conditions
var entities = query.list();

// get number of objects meeting query conditions
var count = query.count();

// get single object meeting query conditions
var entity = query.uniqueResult();

While creating query you can:

  • Limit result objects number:
query.setMaxResults(10);
  • Set the first result
query.setFirstAndMaxResults(5, 10);
  • Add order
query.addOrder(database.Order.asc("name")); // order ascending by name field
query.addOrder(database.Order.desc("price")); // order descending by price field
  • Add restrictions
query.add(database.Restriction.eq("name", "table")); // name equals "table"
query.add(database.Restriction.or(
	database.Restriction.between("price", 10, 20),
	database.Restriction.isNull("price"))
); // price between 10 and 20 or no price at all

You can also combine many elements to create more complicated queries:

// Get products with price less than 100 order from cheaper to more expensive.
// Products with same price order alphabetically.
// Display page 3 of results (10 results on page).
var products = database.find("Product").add(
	database.Restriction.le("price", 100)
).addOrder(
	database.Order.desc("price")
).addOrder(
	database.Order.asc("name")
).setFirstAndMaxResults(20, 10).list();

For more informations see titanium module documentation.

Synchronize data

Synchronizing data with cloud cannot be easier! Just call one of sync methods on Mobeelizer object.

Normal synchronization

To perform data synchronization call sync method.

var error = Mobeelizer.syncAndWait();

if(error) {
  // sync error, more info in error.message
}
// or asynchronous version
Mobeelizer.sync(function(e) {
	// sync success
}, function(e) {
	// sync error, more info in e.message
});

Synchronization process can take long time, so if you want to block application on this time - better supply user with nice-looking loading indicator. And remember - DO NOT call synchronous method in main thread - you application will freeze and can be killed by operating system after some time.

Full synchronization

Full synchronization is a process which removes all data and downloads all data from cloud. It is triggered automatically when user logs in for the first time - but you can call it manually. Just call syncAll method.

var error = Mobeelizer.syncAllAndWait();

if(error) {
  // sync error, more info in error.message
}
// or asynchronous version
Mobeelizer.syncAll(function(e) {
	// sync success
}, function(e) {
	// sync error, more info in e.message
});

You should block all user actions for this process (database will be erased). And once again remember not to call synchronous method in main thread.

In full synchronization process user-modified data is not send to cloud, so all not synchronized data (with modified flag) will be lost! To prevent this perform normal synchronization before.

You can check the sync status at any time:

var status = Mobeelizer.checkSyncStatus();

The status values are:

Mobeelizer.SYNC_NONE // Sync has not been executed in the existing user session
Mobeelizer.SYNC_STARTED // Sync is in progress
Mobeelizer.SYNC_FILE_CREATED // Sync is in progress
Mobeelizer.SYNC_TASK_CREATED // Sync is in progress
Mobeelizer.SYNC_TASK_PERFORMED // Sync is in progress
Mobeelizer.SYNC_FILE_RECEIVED // Sync is in progress
Mobeelizer.SYNC_FINISHED_WITH_SUCCESS // Sync has finished successfully
Mobeelizer.SYNC_FINISHED_WITH_FAILURE // Sync has not finished successfully

Broadcast notifications

You can register listener for all notifications about sync status changes. To do it just call registerSyncStatusListener method:

Mobeelizer.registerSyncStatusListener(function(e) {
	var syncStatus = e.status;
	// rest of your code
});

Available sync status values are listed above.

Push notifications

To learn about Push notification see Push notifications key concept page.

Configuring application

To register to push notifications first you need to obtain registration token. The best way to do it is to use some platform-dependent module.

Remember about configuring application in App Designer - see Android references or iOS references for more informations.

Registering to receive push notifications

After that you have to send registration token to Mobeelizer server by calling method:

var status = Mobeelizer.registerForRemoteNotifications("token");

where status can be:

Mobeelizer.COMMUNICATION_SUCCESS // Communication completed successfully
Mobeelizer.COMMUNICATION_FAILURE // Connection error. Look for the explanation in the application logs

To unregister your application from receiving push navigation just call:

var status = Mobeelizer.unregisterForRemoteNotifications();

Sending push notification

To send Push notification call one of methods on Mobeelizer object:

var notification = {
	// message content
};
var status = Mobeelizer.sendRemoteNotification(notification);
var status = Mobeelizer.sendRemoteNotificationToDevice(notification, "deviceName");
var status = Mobeelizer.sendRemoteNotificationToUsers(notification, ["user1", "user2"]);
var status = Mobeelizer.sendRemoteNotificationToUsersOnDevice(notification, ["user1", "user2"], "deviceName");
var status = Mobeelizer.sendRemoteNotificationToGroup(notification, "group");
var status = Mobeelizer.sendRemoteNotificationToGroupOnDevice(notification, "group", "deviceName");