Dynamics Mobile provides an integrated cross-platform mobile environment allowing the developers to develop enterprise mobile apps targeting multiple mobile platforms with a single piece of code.

The document contains a reference to the Dynamics Mobile Javascript API, which is used within the Dynamics Mobile mobile development environment.

There is section for each javascript namespace/object which can be used during the development.

$ma

The $ma object is the root object(namespace) for the APIs provided by Mobile Affairs.

$ma.uiManager

The $ma.uiManager object provides members and methods related to the user interface management

Following the list of the public methods of the $ma.uiManager instance:

Examples:

$ma.uiManager.alert('Oops, something goes wrong!');
.....
$ma.uiManager.confirm('Do you want to delete this customer?',function(yesNo){
if(yesno)//delete customer logic comes here
});
.....
$ma.uiManager.hideNextButton();
$ma.uiManager.hideCancelButton();
......
$ma.uiManager.alert($ma.userName,function(){
//alert is closed here
});
....
var title = $ma.uiManager.getTaskAttribute('$title');
alert('The task title is '+title);

$ma.uiManager.context

The $ma.uiManager.context object provides methods allowing the views within a task to pass data. The context stores JSON serialized object instances and is cleared after the task completes. It can survive the web browser’s page refresh.

Examples:

//store customer to task's context
var customer = {no:'1',title:'new customer'};
$ma.uiManager.context.set('c1',customer,function(){
//value was set
});
//get stored customer from the context
$ma.uiManager.context.get('c1',undefined,function(value){
alert(value.title);
});

$ma.device

The $ma.device object provides methods related to the device, where the code is executed.

Examples:

$ma.device.error('Ooops, something wrong happended!');
...
$ma.device.getIPAddress(function(addr){
console.log('my ip is '+addr.ip);
});
...
var content = 'some content';
$ma.device.fileSave('myfiles/file.txt',content,function(){
console.log('saved with success');
});
$ma.device.fileLoad('myfiles/file.txt',function(loadedContent){
console.log('loaded from file:' +loadedContent);
});
...
$ma.device.fileExists('myfiles/file.txt',function(exists){
if(exists)
$ma.device.fileDelete('myfiles/file.txt',function(){
console.log('file was deleted');
return;
})
else {
console.log('file does not exists!');
}});

$ma.cfgManager

The $ma.cfgManager object provides methods allowing the developer to work with the server-settings defined for the device’s role. The role’s server settings are managed by the system administrator. They are set of key/value pairs which the administrator can manage. Each module can support multiple server-settings. The exact set of the supported server-settings for a given mobile module is decided by the developer and must be included in the module’s documentation.

The setting’s name consists of two elements – module’s code and setting-name separated with dot.
if we our module has unique module identifier SLA and if we want to support a server-setting called activateFancyFeature which can have values of “true” and “false” the administrator will manage the setting by specifying the setting like:

SLA.activateFancyFeature = true

Note that other modules can support the same server-setting, but the administrator will have to prepend the other’s module unique identifier:

PLP.activateFancyFeature = false

If the developer wants to check the value of the setting at the mobile side using the javascript API in order to detect if specific feature must be activated or not he will use the following code:

Example:

$ma.cfgManager.get('activateFancyfeature',function(value){
if(value=='true') {
$ma.uiManager.alert('The feature is activated');
}
else{
$ma.uiManager.alert('The feature is NOT activated');
}});
//Note that the developer does not need to prepend the server-setting name with the module's code. It is automatically done behind the scene from the framework.
//If the developer needs to store specific key-value pairs for the particular device the $ma.cfManager object is the ideal candidate:
$ma.cfgManager.get('lastDocumentNumber',function(lastDocumentNumber){
if(lastDocumentNumber){
lastDocumentNumber = parseInt(lastDocumentNumber);
}
else{
lastDocumentNumber=0;
}
//increase the number and use it in some document releated operations
lastDocumentNumber++;
//....
$ma.uiManager.alert('this is {0} the new "last" number, now ').format(lastDocumentNumber);
//save the lastDocumentNumber setting in the mobile device's memory
$ma.cfgManager.set('lastDocumentNumber', lastDocumentNumber.toString());
});

$ma.dataManager

The $ma.dataManager object provides methods allowing the developer to work with data stored in the mobile storage of the device via raw SQL queries. The underlying storage engine is based on SqLite. The developers can read the SqLite documentation for more info about the format of the queries.

If the developer wants to fetch all customers from the SL_Customer database table, he can use he following code:

$ma.dataManager.fetchsql('select * from SL_Customer order by fName',function(rows){
console.log('{0} rows fetched'.format(rows.length));
for(var i=0;i<rows.length;i++){
console.log('{0} customer'.format(rows[i].fName));
}});
//The develloper can insert execute sql queries using the following approach:
$ma.dataManager.execSql("delete from SL_Customer where no='123131' ",function(){
console.log('success')
},function(errorMessage){
console.log('failure:'+errorMessage)
});

$ma.printManager

The $ma.printManager object provides methods allowing the developer to work with printers connected to the device via Bluetooth.

var document = "Hello World\n";
docment+="Line2\n";
document+="Line3\n";
$ma.printerManager.getPrinters(function(printers){
$ma.printManager.print(printers[0].name,document,80,999,
'utf-8',false,
function() {
console.log('printed');
},
function(error){
console.log('print error:'+error);
}
)
});

$ma.bo.[module-id].BusinessObjectType

The $ma.bo namespace allows the developer to work with the mobile data using a simple Object Relational Management (ORM) style syntax. It allows the developer to query and create/update/insert data using the business object concept supported by MACloud Studio.

Each mobile module has unique two or three letter identifier specified by the developer. Each module can have many business objects defined via MACloud Studio. Let’s assume the developer develops a module with unique module identifier SLA. The developer can refer to the declared business objects in the SLA module by using the $ma.bo.SLA namespace like this:

$ma.bo.SLA.Customer

$ma.bo.SLA.Item

$ma.bo.SLA.Payment

In the example above we have 3 business objects – Customer, Item and Payment. These three business objects actually corresponds to database tables. Each business object instance corresponds to a table row.

Each business object type has the following static ( class level ) methods.

So, if we want to query a list of customer business object instances and filter them by name, we can use the following code:

Example:

var pattern = '%sometext%';
$ma.bo.SLA.fetchAll('fName like "'+pattern+'"','no descending',50,function(customers){
//iterate over the resulting list of customers
for(var i=0;i<customers.length;i++){
//display the value of the someProperty property for each customer
console.log(customers[i].someProperty);
}});

In the example above we filter only the customers, which contains some text in their fName property ( or column). We provide a sql-where clause to filter the customers by their fName property. We also limit the maximum number of the returned customers to 50 by supplying it as parameter to the fetchAll method. The result from the fetchAll method is an array of customer business object instances referred as customers variable. We can then iterate over the array and access each of the Customer instances and make anything with them – reading a property and displaying the value on the screen in this case.

Each business object instance has the following instance level methods:

We can use these methods to insert, update or delete the business object from the database. Let’s fetch a list of existing customers , change something for each fo them and save them back to the mobile database:

var pattern = '%somename%';
$ma.bo.SLA.fetchAll('fName like "'+pattern+'"','no descending',50,function(customers){
for(var i=0;i<customers.length;i++){
//assign some value to a property, e.g. making a change in-memory
customers[i].someProperty=124.5;
//update the mobile storage with the changes and send update message to the connected ERP with a single line
//the message will be sent whenever connection is detected
customers[i].update(function(){
console.log('customer saved')
}
);
}}
//create new business object instance
var newCustomer = new $ma.bo.SLA.Customer();
//assign values to the customer's property
newCustomer.no='1234';
newCustomer.fName='';
//insert the new customer instance into the mobile storage database - e.g. inserting a new record into the mobile database
// and send insert message to the connected ERP - the message will be sent whenever connection is detected
newCustomer.add(function(){
console.log('customer was saved');
});
//fetch a single business object instance
$ma.bo.SLA.Customer.fetch('1234',function(oldCustomer){
if(oldCustomer){
//delete the business object instance from the mobile storage
// and send delete message to the connected ERP
oldCustomer.del(function(){
console.log('customer was deleted');
});
}});

$ma.liveLink

The $ma.liveLink object allows the developer to communicate with the MACloud service via the standard communication channel. Most of the methods found within the $ma.liveLink object require online connection from the mobile device to MACloud.

Example:

//create new invoice document
var invoice = $ma.bo.SLA.Invoice();
//assign some values of the invoice's properties
invoice.no='1234';
invoice.customerName = 'some customer';
nvoice.customerTaxNo='123456789';
invoice.amount = 100;
invoice.amountWithVAT = 120;
invoice.lines=[];
//attach a line object to the invoice
var line = $ma.bo.SLA.InvoiceLinw();
line.no = 'SF-0001';
line.title='red car';
line.quantity=1;
line.amount=50;
invoice.lines.push(line);
//attach another line object to the invoice
line = $ma.bo.SLA.InvoiceLinw();
line.no = 'SF-0002';
line.title='green car';
line.quantity=1;
line.amount=50;
invoice.lines.push(line);
//send the new invoice including the lines to the ERP
//the operation requires the Invoice and InvoiceLine objects to be declared in MACloud Studio Business Object Desginer
$ma.liveLink.postToSyncLog(invoice,function(){
console.log('packet was sent');
});
//invoking on-line code, which runs inside the ERP and receive the result
//for example this can be used to run Microsoft Dynamics NAV codeunit or Microsoft Dynamics AX class method
$ma.uiManager.CompanyName = 'CRONUS International Ltd.'
$ma.liveLink.execCommand("CalcPrice",{customerNo:"123",ItemNo:"45678",Quantity:123},function(result){
alert("The price is"+result.Price);
},
function(err){
alert(err);
});
//selecting records from a local ( on-device) database table
$ma.liveLink.fetchAll($ma.bo.ITA.Customer,'[Balance]>0','[No] asc',100,function(customers){
alert(customers.length+' customers were found');
});

$ma.liveLink.syncPacket

The $ma.liveLink.syncPacket object allows the developer to perform a fine-grained control over the SyncPacket generation process in response to changes in the mobile storage.

Example:

try{
$ma.liveLink.syncPacket.start();
var customerBusinessObject2 = new $ma.bo.SLA.Customer();
customerBusinessObject.no="1";
customerBusinessObject.name="someCustomer";
//add the business object in the local storage and queue it for sending to the backend
customerBusinessObject.Add();
var customerBusinessObject2 = new $ma.bo.SLA.Customer();
customerBusinessObject2.no="2";
customerBusinessObject2.name="anotherCustomer";
//add the business object in the local storage and queue it for sending to the backend
customerBusinessObject2.Add();
var customerBusinessObject3 = new $ma.bo.SLA.Customer();
customerBusinessObject3.no="3";
customerBusinessObject3.name="yetanotherCustomer";
//queue the business object for sending to the backend without storing it in the local storage
$ma.liveLink.syncPacket.addEntity(customerBusinessObject3);
// send the packet to server
$ma.liveLink.syncPacket.post(function(){
console.log('success');
});
}
catch(error){
$ma.liveLink.syncPacket.cancel();
$ma.uiManager.alert(error);
}

$ma.docSeries

The $ma.docSeries object allows the developer to work with document numbers tracked on the device/browser.

They can be used to generate and track unique numbers of documents created on the device/browser such as invoices, orders, contracts and others.

The administrator can define a document series using the Application Area Management Console. Each document series contains the following attributes:

• documentType
  a string defininng the document type. Any string can be used. The following ‘standard’ strings in the standard mobile modules are defined by default:
  • DT0 – order
  • DT1 – invoice
  • DT2 – transfer
  • DT100 – customer
• current
  integer value containing the last number for the specific document type.
  calls to $ma.docSeries.increaseNumber actually increments the current attribute
• mask
  a string defining how the document number is actually composed.
  it allows the document numbers to contain leading zeroes or characters.
  Let’s assume we have document series with current value of 999;
  Following some examples about the composed document number using different masks:

{0} , generates 999
{0:00000} , generates 00999
{0:0000} , generates 0999
SF-{0:00000} , generates SF-00999
SF-{0:00000}OR , generates SF-00999OR

invoking $ma.docSeries.getNextNumber will returned the actual number composed from the current value and the mask of the document series for the specified document type

• max
  specifies the maximum allowed number for the specific document series. Currently it is not forced from the API and is only informational attribute which can be used by the developer

Flow

The flow of the events regarding the document series goes like this:

Web browser:

• The user starts a task from the UI
• The browser retrieves all document series from the server over the network
• The first step of the task is rendered
• The next number for a specific document type is retrieved by invoking $ma.docSeries.getNextNumber method
• The number returned is used in certain way by the developer
• The next number is persisted in memory by invoking $ma.docSeries.increaseNumber method
• All changes ( the new number increased ) is persisted to server by invoking $ma.docSeries.saveAll

Mobile device ( Android, iOS):

• The user starts a task from the UI
• The device retrieves all document series from device’s local storage
• The first step of the task is rendered
• The next number for a specific document type is retrieved by invoking $ma.docSeries.getNextNumber method
• The number returned is used in certain way by the developer
• The next number is persisted in memory by invoking $ma.docSeries.increaseNumber method
• All changes ( the new number increased ) is persisted to the device local storage by invoking $ma.docSeries.saveAll
• The changes in the document series in the device local storage are sent to the server whenever it launches the synchronization process either manually or automatic

Example:

//create some document using business object
$ma.docSeries.getNextNumber("DT1",function(newDocNo){
var invoice = new $ma.bo.SLA.SalesHeader();
//assign a new document number for the invoice, assuming the invoice document number
//is tracked under DT1 document type
invoice.No = newDocNo;
// modify some of the invoice attributes
invoice.amount = 10.00;
//save the invoice in the storage
invoice.add();
//increase the document serie current value after successfull persistance of the invoice
$ma.docSeries.increaseNextNumber();
//persist all document series changes in the storage
},function(error){
alert('error');
});

$ma.utils

The $ma.utils object provides a set of general tools.

Example

var str = "-12345-";
var x = $ma.utils.trim(str,'-');
console.log(x);// prints 12345
var str = "-12345-";
var x = $ma.utils.ltrim(str,'-');
console.log(x); // prints 12345-
var str = "-12345-";
var x = $ma.utils.rtrim(str,'-');
console.log(x);// prints -12345

$ma.utils.dates

The $ma.utils.dates object provides a set of date related tools

Example:

var d1 = $ma.utils.dates.convert('01/01/2013');
var d2 = $ma.utils.dates.convert('01/01/2014');
if($ma.utils.dates.eq(d1,d2))
alert("equal");
if($ma.utils.dates.lt(d1,d2))
alert("lower");
if($ma.utils.dates.gt(d1,d2))
alert('greater');
var d3 = $ma.utils.dates.convert('5/5/2013');
if($ma.utils.dates.between(d3,d1,d2))
alert('between');

$ma.utils.utf8

The $ma.utils.utf8 object provides a set of date related tools

Extensions

There are several extensions over the standard javascript objects/types

Example

var x = "1234";
var y = x.padLeft(x,'0');
console.log(y); //prints 001234
y = x.padRight(x,'0');
console.log(y); //prints 123400
var y = "My name is {0} {1}".format('John','MCloud');
console.log(y); //prints My name is John MCloud
var d = new DateTime();
var query = "select * from mytable where startdate>'"+d.toSqLiteFormat()+"'";
var d = new DateTime();
console.log(d.format('DD/MM/YYYY'));

Other

Example

var encoded = $.base64.encode("1234");
var decoded = $.base64.decode(encoded);
//-------------------------------------------------
var standardArray = [1,2,3];
var observableArray = ko.observableArray();
observableArray.fromArray(standardArray);