SMS Dialog Module for Titanium Mobile
Objective-C Python JavaScript Perl
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Classes
assets
dist
documentation
example
hooks
platform
sms.xcodeproj
.gitignore
BencodingSms_Prefix.pch
LICENSE
README.md
build.py
manifest
module.xcconfig
timodule.xml
titanium.xcconfig

README.md

benCoding.SMS Module

The benCoding.SMS module makes it easy to add SMS functionality into your iOS Titanium apps. We unleash the power of Apple's native Apple SMS component MFMessageComposeViewController to Titanium with an API fashioned after the Titanium EmailDialog to make it familiar to use.

Please Read Before Using

Limitations

  • The SMS.Dialog module can only be tested on the device itself. This is an Apple Simulator limitation and not a module feature.
  • If you are using iOS 6 or a Titanium SDK greater then 1.8.2 please read the iOS 6 section below.

Before you start

  • This is an iOS module designed to work with Titanium SDK 1.8.2.
  • Before using this module you first need to install the package. If you need instructions on how to install a 3rd party module please read this installation guide.

If you are running iOS 6 - Please read

If you are building for iOS 6 using Xcode 4.5 or greater you need to use SMS.Dialog 1.8 or greater. This version of the SMS.Dialog requires using the 2.1.4GA Titanium SDK.

Download the release

There is two ways you can download this module. The go to the releases/UseIfDownloadingFromGithub folder. This will have a release compiled for anyone download it from github.

You can also download it for free from Appcelerator's marketplace here.

Building from source?

If you are building from source you will need to do the following:

  • Modify the titanium.xcconfig file with the path to your Titanium installation
  • Make sure the the method moduleGUID in the class BencodingSmsModule has the variable marketPlace set to NO. This will avoid you running into any licensing issues.

Setup

  • Download the latest release from the releases folder ( or you can build it yourself )
  • Install the bencoding.sms module. If you need help here is a "How To" guide.
  • You can now use the module via the commonJS require method, example shown below.

var sms = require('bencoding.sms').createSMSDialog();

Now we have the module installed and avoid in our project we can start to use the components, see the feature guide below for details.

benCoding.SMS How To Example

For detailed documentation please reference this project's documentation folder. A code "How To" example is provided in the app.js located in the project's example folder.

Properties

This module provides access to most of the native MFMessageComposeViewController's functionality.

canSendText

Returns a boolean whether the device has the ability to send Text Messages. Please keep in mind this value will always be false when running on the simulator. (Read Only)

messageBody

The SMS message

toRecipients

An array of SMS recipients ie phone numbers

barColor

The bar color of the email dialog window when opened

Below is a description and example on how to use each supported method.


var sms = require('bencoding.SMS').createSMSDialog({
            barColor:'#336699', //set the SMS Dialog barColor
            messageBody:"Appcelerator Titanium Rocks!", //Set SMS Message
            toRecipients:[{"555-555-5555"},{"444-444-4444"}] //Who we are the SMS sending to
});

canSendText

This property returns a boolean indicator on whether or not sending SMS Messages is supported.

The below sample shows how you can check if this feature is supported.


Ti.API.info("Can I send messages?");
Ti.API.info("Is This Feature Supported? => " + sms.canSendText); 

//This is an example of how to check if the device can send Text Messages 
if(!sms.canSendText){ 
        var noSupport = Ti.UI.createAlertDialog({ 
           title:'Not Supported', 
           message:"This device doesn't support sending text messages" }).show(); 
      return; 
}

Methods

setBarColor

Sets the barColor property for the SMS Dialog, see below for an example on how to use this.

setToRecipients

Sets the toRecipients property with an array ( ie an array of phone numbers),see below for an example on how to use this.

setMessageBody

Sets the messageBody property with a string. This is used to set the message shown in the SMSDialog,see below for an example on how to use this.

open

This opens the SMS dialog. The SMS dialog itself is a modal window.

Method Usage Example

The below example shows how to use all of the methods. For additional samples please see the example folder contained within the module or here on Github.


//Set the SMS BarColor
sms.setBarColor('#336699');

//Set the SMS message, you can also do this when you create the SMSDialog
sms.setMessageBody("Appcelerator Titanium Rocks!");

//Set the SMS ToRecipients, you can also do this when you create the SMSDialog
//This is an array so you can pass in several numbers for the message to be sent to
sms.setToRecipients([{"555-555-5555"},{"444-444-4444"}]);

//This call opens the SMS Message Dialog window withe number and message you provided earlier
sms.open({ 
    animated:true, //Indicate if the dialog should be animated on open (OPTIONAL) 
    portraitOnly:true //Indicate if we lock the dialog into the portrait orientation only (OPTIONAL)
});     

Events

completed

This event is fired when the user presses the cancel button on the SMS Dialog

cancelled

This event is fired when an SMS message is sent successfully

errored

This event is fired when an error happens sending a message

Event Usage Example

The below example shows how to use all of the events. Please note the events will not become active until the open method is called.

For additional samples please see the example folder contained within the module or here on Github.


var sms = require('bencoding.sms').createSMSDialog({ barColor:'#336699' });

//If you want you can define some callbacks
function messageCompleted(e){
    alert(e.message); 
};
function messageErrored(e){
    alert(e.message); 
};

function messageCancelled(e){
    alert(e.message); 
};

//Add the listeners so we know when an action happens
sms.addEventListener('cancelled', messageCancelled);
sms.addEventListener('completed', messageCompleted);
sms.addEventListener('errored', messageErrored);

FAQ

How does module orientation work?

We use the orientation from your tiapp.xml file. Depending on how your project is structured this can cause repainting issues. In these cases it is recommended to fix your orientation either in your tiapp.xml file or by providing the portraitOnly on open.

If you want to lock into portrait only you can do so by adding the portraitOnly parameter to the open method.

Can I automately send the SMS message without showing it to the user?

No, this is not supported by Apple.

Can I send a MMS?

No, the current Apple API does not allow for this.

Can I change the style of the dialog?

You can update the barColor by setting the barColor property when creating the SMSDialog or by calling the setBarColor method before calling the open method.

Is there an Android version?

You can do this using activities on Android without the need of a module. This module is an iOS only wrapper around the native MFMessageComposeViewController component.

Licensing & Support

This project is licensed under the OSI approved Apache Public License (version 2). For details please see the license associated with each project.

Developed by Ben Bahrenburg available on twitter @benCoding

Learn More

Twitter

Please consider following the @benCoding Twitter for updates and more about Titanium.

Blog

For module updates, Titanium tutorials and more please check out my blog at benCoding.Com.