MMI
MMI stands for Mobilet Manager Interface. It is one of the core components of the appEz hybrid application development paradigm. MMI provides set of tools that enables the developer to leverage the capabilities of native mobile platforms such as Android and iOS.
By enabling the developer to access the native capabilities, MMI can help improve the overall experience of the application and adds that element of responsiveness to the application.
As the name suggests, the Mobilet Manager Interface is an interface that facilitates the communication between the native layer and the web layer.
This component provides a standard and common set of APIs for the developers to be used at the web layer in JavaScript which can help access the platform specific services without bothering about the implementation at the respective native containers.
Use of these APIs will invoke the platform specific components when the appEz enabled application runs in the respective containers.
The architecture of the appEz MMI layer is based on callback mechanism i.e. the operations requested by the application provides their response in a callback function specified at the time of initiating the request. Though, most of the operations are based on this mechanism, there are certain events which do not require callback to inform their completion. Details about such events will be provided in the subsequent sections.
Communication between web layer and the native layer is single threaded. This means that once you have dispatched request for using one of the services, then you must wait for the service operation response in the callback. Failure to do so might cause inconsistency in the data response callbacks and in some situations might even lead to application crashing.
Services
Service in the MMI layer is the interaction point for the client application with native capabilities of respective platforms.
In its current form, MMI layer has exposed a certain set of operations which are most likely to be used by a developer for developing enterprise applications.
Some of these operations include the use of native dialogs, pickers and similar user interaction components, providing secure environment for storing application data in a variety of storage forms such as SQLite database, Persistence storage, executing HTTP requests, showing maps within user application etc.
Also, exposed are APIs for accessing device hardware such as camera by exposing interface to access the device camera.
Standard Service Request
In order to use MMI service, you need to create a service request object that contains parameters which are required by the service for its execution. This request object will always be a JSON object. Service specific request parameters in this object will be specified in the forthcoming sections. Once the request object is prepared, it is supplied to the helper function of MMI library corresponding to that service operation. In addition, the user also needs to provide the callback function and callback scope to the helper function.
Specified below is a standard service request format:
var requestObj = {
<REQUEST-PROPERTY-1>: < REQUEST-PROPERTY-1-VALUE>,
<REQUEST-PROPERTY-2>: < REQUEST-PROPERTY-2-VALUE>,
…
<REQUEST-PROPERTY-n>: < REQUEST-PROPERTY-n-VALUE>,
};
appit.mmi.<HELPER-FUNCTION>(requestObj, <CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>);
Where
requestObj - Refers to the JSON request that needs to be provided by the user containing the required request parameter(s) as specified in the table above.
<CALLBACK-FUNC>- Callback function where the SmartEventResponse will be received on completion of operation completion
<CALLBACK-FUNC-SCOPE>-Callback function scope
Standard Service Response
The response on completion of a service operation is received in the callback function as provided in the service helper function argument. The received response will be of the type SmartEventResponse model. Specified below is the information provided to the user by SmartEventResponse model:
| Information type | Access method | Value set |
|---|---|---|
| Operation completion status | smEventResp.getOperationComplete() | true or false based on whether the operation was successful or unsuccessful respectively |
| Operation Response | smEventResp.getServiceResponse() | JSON object containing the response of service operation |
| Exception type | smEventResp.getExceptionType() | Numeric value indicating the type of exception or operation error that occurred during execution of service operation. Will be 0 when getOperationComplete() returns true. Returns a negative value if getOperationComplete() returns false. The type of error is given by error code specified in section Exception Types. |
| Exception message | smEventResp.getExceptionMessage() | A detailed message that describes the exception or operation error. Will be null if getOperationComplete() returns true, non-null if it returns false. |
Here smEventResp is the SmartEventResponse model received in the callback function of the service operation initiated by the user.
Services Layer API - UI Service
This service helps provide informational and interactional components such as dialogs of varying types from the respective native platforms. Refer to the subsections as specified below for information
Activity Indicator
To keep the user informed about a long, pending operation, activity indicator can be used. It blocks the UI of the application and hence, user cannot interact with any of the components of its page.
Show Activity indicator: This operation is meant for showing the activity indicator with the desired message to keep the user informed of the background operations occurring in the application.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | Yes | String message to be shown on the activity indicator | NA |
Response format:
For knowing the generic response format for this service operation, visit the section on Standard Service Response.
The structure of the service response is following:
{‘userSelection’:null}
Example: Refer to the following snippet for showing the activity indicator in your application.
Request:
var UI_ACTIVITY_INDICATOR_REQ = {
'message' : 'My first loading indicator...'
};
appit.mmi.showProgressDialog(UI_ACTIVITY_INDICATOR_REQ,scope.showDialogCallback,scope);
Response:
{"userSelection":"null"}
Hide Activity Indicator: This operation hides the activity indicator. Make sure that the indicator is shown before the request to hide is initiated.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | No | null | NA |
Helper method:
appit.mmi.hideProgressDialog(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’:null}
Example: Refer to the following snippet for hiding the activity indicator in your application:
Request:
var UI_HIDE_ACTIVITY_INDICATOR_REQ = {
'message' : null
};
appit.mmi.hideProgressDialog(UI_HIDE_ACTIVITY_INDICATOR_REQ,scope.hideDialogCallback,scope);
Response:
{"userSelection":"null"}
Loading Indicator
This UI component is supported on iOS only. This component can be used when the application does not intend to block the user interface while a pending operation is underway in background. The loading indicator is thus not visible on application page but on the status bar of the iOS devices.
Show Loading Indicator: This operation is meant for showing the loading indicator which is currently specific to iOS.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | No | null | NA |
Helper method:
appit.mmi.showProgressIndicator(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’:null}
Example: Refer to the following snippet for showing the loading indicator in your application:
Request:
var UI_LOADING_INDICATOR_REQ = {
'message' : null
};
appit.mmi.showProgressIndicator(UI_LOADING_INDICATOR_REQ,scope.showDialogCallback,scope);
Response:
{"userSelection":"null"}
Hide Loading Indicator:
This operation is meant for hiding the loading indicator. Make sure that the indicator is shown when the request for hide is initiated.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | No | null | NA |
Helper method:
appit.mmi.hideProgressIndicator(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’:null}
Example: Refer to the following snippet for hiding the loading indicator in your application.
Request:
var UI_HIDE_LOADING_INDICATOR_REQ = {
'message' : null
};
appit.mmi.hideProgressIndicator(UI_HIDE_LOADING_INDICATOR_REQ,scope.hideDialogCallback,scope);
Response:
{"userSelection":"null"}
Information Dialog
This dialog is meant for informing the user of an action that is about to take place or has taken place in the application. In this case, the user does not have control/ choice over the action as it is only for informational purpose.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | Yes | String message to be shown on the activity indicator | NA |
| buttonText | No | Custom button text | “OK” |
Helper method:
appit.mmi.showInformationDialog(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’:”2”}
Here 2 means that the user has dismissed dialog by pressing OK button on the dialog.
Example: Refer to the following snippet for showing the information dialog in your application.
Request:
var UI_INFO_DIALOG_REQ = {
'message' : 'An important message'
};
appit.mmi.showInformationDialog(UI_INFO_DIALOG_REQ,scope.onClickShowInfoDialogCallback, scope);
Response:
{"userSelection":"2"}
Decision Dialog
This dialog is used when the application wants the user to take a decision on a flow. This dialog has a positive button as well as negative button. Any button that the user selects is communicated to the web layer. The application can then act according to the selection of the user.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | Yes | null | NA |
| positiveBtnText | No | Custom message string denoting the positive button action | “Yes” |
| negativeBtnText | No | Custom message string denoting the negative button action | “No” |
Helper method:
appit.mmi.showDecisionDialog(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’:’<USER-SELECTION>’}
Here <USER-SELECTION> can be either of 0 or 1 based on user selection of Positive button or Negative button respectively.
Example: Refer to the following snippet for showing the decision dialog in your application-
Request:
var UI_DECISION_DIALOG_REQ = {
'message' : 'Are you sure you want to quit?'
};
appit.mmi.showDecisionDialog(UI_DECISION_DIALOG_REQ,scope.onClicksShowDecisionDialogCallback,scope);
Response:
This response is received after we pressed Yes on the decision dialog. If we press No on the dialog, then we receive 1 in userSelection info.
{"userSelection":"0"}
Single Choice List Dialog
This operation shows a list dialog whose elements have been specified by the user. User can now select an element from the list. Then the information regarding the selected element is sent back to the web layer.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | Yes | JSON array containing the list of elements to be displayed on the dialog. Each element in the JSON array need to have key called item whose value should be the title of list element. | NA |
Helper method:
appit.mmi.showSelectionList(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’: ’<USER-SELECTION>’}
Here <USER-SELECTION> is the index of the list element selected by the user.
Example: Refer to the following snippet for showing the single selection dialog in your application.
Request:
var UI_SINGLE_LIST_REQ = {
'message' : [
{
'item': 'Item 1'
},
{
'item': 'Item 2'
},
{
'item': 'Item 3'
}
]
};
appit.mmi.showSelectionList(UI_SINGLE_LIST_REQ,scope.onClickShowSingleSelectionDialogCallback, scope);
Response:
Here we have selected the first element of the list:
{"userSelection":"0"}
Single Choice List Dialog with Radio
This operation shows a list dialog whose elements have been specified by the user. User can now select an element from the list. Then the information regarding the selected element is sent back to the web layer. It is in a way a variation of the Single Choice list component but shows Radio button alongside each list element.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | Yes | JSON array containing the list of elements to be displayed on the dialog. Each element in the JSON array need to have key called item whose value should be the title of list element. | NA |
Helper method:
appit.mmi.showSelectionListRadio(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’: ’<USER-SELECTION>’}
Here <USER-SELECTION> is the index of the list element selected by the user.
Example: Refer to the following snippet for showing the single selection dialog with radio in your application.
Request:
var UI_SINGLE_LIST_RADIO_REQ = {
'message' : [
{
'item': 'Item 1'
},
{
'item': 'Item 2'
},
{
'item': 'Item 3'
}
]
};
appit.mmi.showSelectionListRadio(UI_SINGLE_LIST_RADIO_REQ,scope.onClickShowSingleSelectionRadioDialogCallback,scope);
Response:
Here we have selected the second element of the list
{"userSelection":"1"}
Multiple Choice List Dialog
This operation shows a list dialog whose elements have been specified by the user. User can now select multiple elements from the list. Then the information regarding the selected indices is sent back to the web layer.
Request parameters
:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | Yes | JSON array containing the list of elements to be displayed on the dialog. Each element in the JSON array need to have key called item whose value should be the title of list element. | NA |
Helper method:
appit.mmi.showMultiSelectionList(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’:<USER-SELECTED-INDICES>}
Here <USER-SELECTED-INDICES> is a JSON array whose each element contains a key named selectedIndex and whose value is the selected index. This means that if you have created a multiple selection dialog of 5 list elements of which user has selected any 3 elements, then this JSON array will contain 3 JSON elements each having a node named selectedIndex and its value will be the selected index.
Example: Refer to the following snippet for showing the multi-selection dialog in your application.
Request:
var UI_MULTI_SELECTION_REQ = {
'message' : [
{
'item': 'Item 1'
},
{
'item': 'Item 2'
},
{
'item': 'Item 3'
}
]
};
appit.mmi.showMultiSelectionList(UI_MULTI_SELECTION_REQ,scope.onClickShowMultiSelectionDialogCallback,scope);
Response:
Here we have selected the first and second element of the list
{"userSelection":"[{"selectedIndex":0},{"selectedIndex":1}]"}
Date Picker
As the name suggests this operation shows a date picker to the user from where it can select the date of its choice. The selected date is then communicated back to the web layer in a specified format.
Request parameters:
| Request Parameter | Mandatory | Value Set | Default Value |
|---|---|---|---|
| message | Yes | null | NA |
Helper method:
appit.mmi.showDatePicker(<REQUEST-OBJ>,<CALLBACK-FUNC>,<CALLBACK-FUNC-SCOPE>)
Response format:
{‘userSelection’:’<SELECTED-DATE>’}
Here <SELECTED-DATE> is the date selected by the user from the date picker in the MM-DD-YYYY format.
Example: Refer to the following snippet for showing the activity indicator in your application.
Request:
var UI_DATE_PICKER_REQ : {
'message' : 'null'
};
appit.mmi.showDatePicker(UI_DATE_PICKER_REQ,scope.onClickShowDatePickerCallback,scope);
Response:
{"userSelection":"5-30-2014"}