Class: ActiveSms::Base

Inherits:
Object
  • Object
show all
Includes:
ActionController::UrlWriter, AdvAttrAccessor
Defined in:
lib/activesms/base.rb,
lib/activesms/connections.rb,
lib/activesms/connection_adapters/bulk_sms_adapter.rb,
lib/activesms/connection_adapters/clickatell_adapter.rb,
lib/activesms/connection_adapters/simplewire_adapter.rb

Overview

Active SMS allows you to send SMS messages from your application using an SMS model.

SMS models

To use Action SMS, you need to create an SMS model.

$ script/generate sms Notifier

The generated model inherits from ActiveSms::Base. SMS messages are defined by creating methods on the model which are then used to set variables to be used in the message or to change options on the message.

Examples:

class Notifier < ActiveSms::Base
  def 
    recipients "447987654321"
    from       "447123456789"
    body       "Your account has been created"
  end
end

Sender methods have the following configuration methods available.

  • recipients - Takes one or more destination numbers. These numbers should be formatted in standard international number format.

  • from - Who the SMS message you are sending is from. This may be either a number formatted in standard internation number format, or, if the gateway supports it, an alphanumeric origination.

  • body - The content of the message. This must fit within the length limitation of SMS messages.

Sending SMS messages

Once an SMS action is defined, you can deliver you message or create it and save it for delivery later.

Notifier.(david) # sends the SMS message

sms = Notifier.(david) # an SMS object
Notifier.deliver(sms)

You never instantiate your model class. Rather, your delivery instance methods are automatically wrapped in class methods that start with the word deliver followed by the name of the SMS method that you would like to deliver. The signup_notification method defined above is delivered by invoking Notifier.deliver_signup_notification.

Configuration options

These options are specified on the class level.

  • logger - The logger is used for generating information about the sending run if available. This can be set to nil for no logging. It is compatible with Ruby’s own Logger and Log4r loggers.

  • gateway_settings - Allows detailed configuration of the SMS gateway used to deliver the messages. Some gateways may require additional configuration settings.

  • raise_delivery_errors - Determines whether or not errors should be raised if the SMS fails to be delivered.

  • delivery_method - Defines a delivery method. Possible values are :gateway (default) or :test.

  • perform_deliveries - Determines whether or not deliver_* methods are actually carried out. By default they are, but this can be turned off to help functional testing.

  • deliveries - Keeps an array of all the messages sent out through Active SMS with deliver_method :test. Most useful for unit and functional testing.

Constant Summary collapse

@@logger = 
nil
@@raise_delivery_errors = 
true
@@delivery_method = 
:gateway
@@perform_deliveries = 
true
@@deliveries = 
[]
@@connection = 
nil

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from AdvAttrAccessor

included

Constructor Details

#initialize(method_name = nil, *parameters) ⇒ Base

Instantiate a new Active SMS model object. If method_name is not nil, the model will be initialized according to the named method. If not, the model will remain uninitialized (useful when you need to invoke the “receive” method, for instance).



161
162
163
 
# File 'lib/activesms/base.rb', line 161

def initialize(method_name = nil, *parameters) #:nodoc:
  create!(method_name, *parameters) if method_name
end

Instance Attribute Details

#sms ⇒ Object (readonly)

The Sms message object instance referenced by this model.



118
119
120
 
# File 'lib/activesms/base.rb', line 118

def sms
  @sms
end

Class Method Details

.bulk_sms_connection(config) ⇒ Object

:nodoc:



5
6
7
 
# File 'lib/activesms/connection_adapters/bulk_sms_adapter.rb', line 5

def self.bulk_sms_connection(config) #:nodoc:
  return ConnectionAdapters::BulkSmsAdapter.new(logger, config)
end

.clickatell_connection(config) ⇒ Object

:nodoc:



5
6
7
 
# File 'lib/activesms/connection_adapters/clickatell_adapter.rb', line 5

def self.clickatell_connection(config) #:nodoc:
  return ConnectionAdapters::ClickatellAdapter.new(logger, config)
end

.connected? ⇒ Boolean

Returns true if a connection that’s accessible to this class has already been opened.

Returns:

  • (Boolean) 


9
10
11
 
# File 'lib/activesms/connections.rb', line 9

def connected?
  return !@@connection.nil?
end

.connection ⇒ Object

Returns the connection currently associated with the class. This can also be used to “borrow” the connection to do work that is specific to a particular SMS gateway.

Raises:



16
17
18
19
 
# File 'lib/activesms/connections.rb', line 16

def connection
  raise ConnectionNotEstablished unless @@connection
  return @@connection
end

.connection=(spec) ⇒ Object

Set the gateway connection for the class.

Raises:



22
23
24
25
 
# File 'lib/activesms/connections.rb', line 22

def connection=(spec) #:nodoc:
  raise ConnectionNotEstablished unless spec
  @@connection = spec
end

.deliver(sms) ⇒ Object

Deliver the given Sms message object directly. This can be used to deliver a preconstructed message, like:

sms = Notifier.(parameters)
Notifier.deliver(sms)



151
152
153
 
# File 'lib/activesms/base.rb', line 151

def deliver(sms)
  new.deliver!(sms)
end

.establish_connection(config) ⇒ Object

Establishes the connection to the SMS gateway. Accepts a hash as input where the :adapter key must be specified with the name of a gateway adapter (in lower-case)

ActiveSms::Base.establish_connection(
  :adapter  => "clickatell",
  :username => "myusername",
  :password => "mypassword"
  :api_id   => "myapiid"
)

Also accepts keys as strings (for parsing from YAML, for example).

The exceptions AdapterNotSpecified, AdapterNotFound, and ArgumentError may be returned.



42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/activesms/connections.rb', line 42

def establish_connection(config)
  config = config.symbolize_keys
  unless config.key?(:adapter)
    raise AdapterNotSpecified, "#{config} adapter is not configured"
  end
  adapter_method = "#{config[:adapter]}_connection"
  unless respond_to?(adapter_method)
    raise AdapterNotFound,
          "configuration specifies nonexistent #{config[:adapter]} adapter"
  end
  self.connection = self.send(adapter_method, config)
end

.method_missing(method_symbol, *parameters) ⇒ Object

:nodoc:



121
122
123
124
125
126
127
128
 
# File 'lib/activesms/base.rb', line 121

def method_missing(method_symbol, *parameters) #:nodoc:
  case method_symbol.id2name
    when /^create_([_a-z]\w+)/ then new($1, *parameters).sms
    when /^deliver_([_a-z]\w+)/ then new($1, *parameters).deliver!
    when "new" then nil
    else super
  end
end

.receive(sms) ⇒ Object

Receives an SMS message, parses it into an SMS object, instantiates a new model, and passes the message object to the model object’s #receive method. If you want your model to be able to process incoming messages, you’ll need to implement a #receive method that accepts the SMS object as a parameter.

class Notifier < ActionSms::Base
  def receive(sms)
    ...
  end
end



141
142
143
144
 
# File 'lib/activesms/base.rb', line 141

def receive(sms)
  sms = connection.parse(sms)
  new.receive(sms)
end

.simplewire_connection(config) ⇒ Object

:nodoc:



13
14
15
 
# File 'lib/activesms/connection_adapters/simplewire_adapter.rb', line 13

def self.simplewire_connection(config) #:nodoc:
  return ConnectionAdapters::SimplewireAdapter.new(logger, config)
end

Instance Method Details

#connection ⇒ Object

Returns the connection currently associated with the class. This can also be used to “borrow” the connection to do work that is specific to a particular SMS gateway.



59
60
61
 
# File 'lib/activesms/connections.rb', line 59

def connection
  self.class.connection
end

#create!(method_name, *parameters) ⇒ Object

Initialize the model via the given method_name. The body will be rendered and a new Sms object created.



167
168
169
170
171
172
173
 
# File 'lib/activesms/base.rb', line 167

def create!(method_name, *parameters) #:nodoc:
  initialize_defaults(method_name)
  send(method_name, *parameters)
  
  # Build the SMS object itself.
  @sms = create_sms
end

#deliver!(sms = @sms) ⇒ Object

Delivers an Sms message object. By default, it deliver the cached object (from the #create! method). If no cached object exists, and no alternate has been give as the prameter, this will fail.



178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/activesms/base.rb', line 178

def deliver!(sms = @sms) #:nodoc:
  raise "no SMS object available for delivery!" unless sms
  logger.info "Sending SMS: #{sms}" unless logger.nil?
  
  begin
    send("perform_delivery_#{delivery_method}", sms) if perform_deliveries
  rescue Exception => e
    raise e if raise_delivery_errors
  end
  
  return sms
end