Mobile Custom Components

Define Components with WebRatio Mobile Platform
271 views Published on May 08, 2015 | Time 6 min
Applies to: 8.0 or higher

WebRatio Mobile Platform lets you extend the set of components that can be used inside Mobile Projects to add new functionalities to your mobile applications. In this lesson you learn how to create the "SendSMS" operation that allows to send messages from the mobile application. You can download the "Send SMS" operation from the WebRatio Add-ons.

Transcript

Table of contents

Introduction

WebRatio Mobile Platform lets you extend the set of components that can be used inside projects to add new functionalities. In this lesson you learn how to create a new custom component for Mobile Projects that allows to send a SMS.

How to Define the "Send SMS" Custom Operation

To create a new custom component for a Mobile Project you need a Mobile Components Project. Click on "File" menu, choose the "New" and then "Mobile Components Project" option, give a meaningful name for the Mobile Components Project, such as "MobileCustomComponents" and then press the "Finish" button.

Let's now create the "SendSMS" component. Click on the "File" menu, choose the "New" and then "Component" option. Select a target project in which the component resources will be stored, give a meaningful name for the component, such as "SendSMS" and then press the "Next" button. Select the "Operation" type for the custom component and press the "Finish" button.

Component.xml editor

General tab

Let's choose the main properties for the "SendSMS" operation. Check the "Success Flow Source" property and the "Error Flow Source" property. Click on the "16x16" icon, select the "16" image and click on the "Open" button to load the image. Use the same procedure for the other icon.

Native Plugins tab

The "SendSMS" component needs a specific Phone Gap plugin. Let's open the "Native Plugin" section for this purpose. You can download the zip file containing the plugin at this page this page. Press on the "Add..." button, enable the import to add the plugin from a ZIP file, press on the "Browse..." button, select the ZIP file and then click the "Open" button to load the file. Press the "OK" button to confirm.

The Input.template file

Once the main properties are defined, let's specify the component inputs in the "Input.template" file. Double-click on the "Input.template" node, past the code. The "name" is the parameter name to use for in the code of the service. Set the "name" property to "phoneNumber". The "label" is the parameter label shown in the Parameter Binding dialog. Set the "label" property to "Phone Number". Use the same procedure for the "Message Text" and the "Replace Line Breaks" input parameter.

The SendSMSService.js file

Finally, let's specify the component runtime behavior in the dedicated file. Click on th "SendSMSService.js". WebRatio Mobile Platform creates a skeleton for the component service.

The StringFunctionComponentService.java file

This line of code declares a new service for an operation.

export default wrm.defineService(wrm.core.AbstractOperationService, {

The "initialize" method let's you retrieve information from the descriptor (descr) file.

initialize: function(descr) {
  // TODO initialize the service from descriptor contents
	// - return a promise (with no value) if doing asynchronous work
		
	// this._attrValue = descr["model"]["attribute"];
},

The "executeOperation" method specifies the component behavior.

executeOperation: function(context) {
  // TODO prepare a wrm.nav.Outout object containing the outputs the code for
  // selecting a Success/Error Flow and the outputs to send along it
  // - return the object or a promise thereof
		
  var output = new wrm.nav.Output("success"); // or "error"
  // var input = context.getInput();
  // output["bar"] = input["foo"];  // see Input.template and Output.template
  return output;
},

Let's write the JavaScript code for the Send SMS behavior.

executeOperation: function(context) {
		
  var phoneNumber = context.getInput()["phoneNumber"]
	var messageText = context.getInput()["messageText"]
	var replaceLineBreaksOption = context.getInput()["replaceLineBreaks"]
		
	var options = {
	  replaceLineBreaks: replaceLineBreaksOption,
    android: { intent: '' }
	}
		       
  //Use of the plugin
  return new Promise( function( resolve, reject ) {
    sms.send(phoneNumber, messageText, options, resolve, reject);        
  }).then(function(result){
    return new wrm.nav.Output("success");
  }, function(e){
    return new wrm.nav.Output("error");
  });

},

These lines retrieve the value of the binding done on the component input parameters.

var phoneNumber = context.getInput()["phoneNumber"]
var messageText = context.getInput()["messageText"]
var replaceLineBreaksOption = context.getInput()["replaceLineBreaks"]

These lines create the "options" variable requires by the plugin code.

var options = {
  replaceLineBreaks: replaceLineBreaksOption,
  android: { intent: '' }
}

These lines invoke the Phone Gap plugin to send the SMS and manage the result of this invocation.

return new Promise( function( resolve, reject ) {
  sms.send(phoneNumber, messageText, options, resolve, reject);        
}).then(function(result){
    return new wrm.nav.Output("success");
}, function(e){
    return new wrm.nav.Output("error");
});

How to Model the User Interaction

Let's create a sample project to test the "SendSMS" operation. Click on "File" menu, choose the "New" and then "Mobile Project" option. Give a meaningful name for the Mobile Project, such as "SendSMSsample" and press the "Finish" button.

Now let's add the Mobile Components Project as a dependency in order to see the "SendSMS" operation in the toolbar. Press on the "Add.." button, choose the "Mobile Component Project", press the "OK" button and then press the "Yes" button.

Let's open the "App View" of the Mobile Project and start to model.

First of all, let's add a screen where the user can write a message to send. Click on the "View Container" section of the toolbar, choose the "Screen" item and place the screen in the work area to add it. Type a meaningful name for the home screen, such as "Send SMS".

Let's model the form containing the fields for writing a message. Click on the "View Components" section of the toolbar, choose the "Form" item and click inside the "Send SMS" screen to add it. Type a name for the "Form" component, such as "SMS Info". Right-click on the "Form" view component to add fields, choose the "Edit Form..." option. Press the "Add Field" button to add a field and give a meaningful name to the field, for example "Phone Number". Use the same procedure to the "Message Text" field. Then press the "OK" button to confirm.

Now let's add the action for sending the message. Select the "Action" in the toolbar and click inside the work area to add it.

In order to let the user send the message, let's use a Select Event with a "Navigation Flow". Click on the "Flows" section of th toolbar, choose the "Navigation Flow" item, click first on the "Form" Component and then on the "Action". Type a name for the "Event", such as "Send".

Let's open the Action Definitions View to create the action behavior. Open the Action Definitions View, press the "Action Definition" button and type a meaningful name for the "Action Definition", such as "Send SMS". Double-click on the "Action Definition" to open it.

Now let's model the operation chain containing the "SendSMS" operation. Select the "SendSMS" item in the toolbar and click inside the work area to add it.

Click on the "Flows" section of the toolbar, choose the "Success Flow" item, click first on the "Input Port" and then on the "SendSMS" operation.

Right-click on the "Input Port", choose the "Input Port Wizard..." option. In the opening dialog, choose the parameters to add: in this case, "Message Text" and the "Phone Number". Then press on the "Finish" button.

Click on the "Flows" section of the toolbar, choose the "Success Flow" item, click first on the "SendSMS" operation and then on the "Success Port".

Click on the "Flows" section of the toolbar, choose the "Error Flow" item, click first on the "SendSMS" operation and then on the "Error Port".

Open the "App View". In the Properties View of the Action, press the "Select" button next to the "Action Definition" property to associate an "Action Definition", choose the "Send SMS" action definition and press the "OK" button.

Double-click on the "Navigation Flow", uncheck the "Enable Default Binding" property, press the "Guess Binding" button and press the "OK" button.

Add an other "Screen" in the "App View" to show a feedback message. Click on the "View Containers" section of the toolbar, choose the "Screen" item and click inside the work area to add. Type a name for the screen, for example "Feedback".

Click on the "View Components" section of the toolbar, choose the "Message" component, click inside the "Feedback" screen to add it and then click on the "Flows" section of the toolbar.

Click on the "Flows" section of the toolbar, choose the "Navigation Flow" item, click first on "Success Event" of the "Action" and then on the "Message" component. Double-click on the "Navigation Flow", uncheck the "Enable Default Binding" property, write a message as feedback and press on the "OK" button to confirm.

How to use the build to emulate the Mobile App

The best way to test a custom component is to create a build of the mobile project. In this example we are going to create an Android build. Press on the "Build" button and then on "Build Configurations..." option. Double-click on the "Mobile - Android" option and press the "Build" button to run the build.

Once the build is ready, let's use the Mobile Developer App to download the app package. Press on the "Scan QR Code" button to download the build on the device. Scanning the QR Code with the device. You may see a message like the one shown. Enable the "Unknown sources" option in the "Settings" of your device to proceed. Click on the "Settings" button, enable the "Unknown sources" property, click on the "OK" button and then click on the "Install" button.

When the installation is completed let's open the app. Click on the "Open" button.

Write a phone number to send the message and the text of message. Then press the "Send" button to confirm.