textris 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2fd3e9eb6888e74d470bde1afe44a785ecbec855
-  data.tar.gz: b32e98392db542754742c288849125af7f7b28fd
+  metadata.gz: dec9ef9f16f25185395f550204e2e5afbd067d8b
+  data.tar.gz: b5f8bf92434c2e95ff71a0bf6d9ee2a4692b0091
 SHA512:
-  metadata.gz: 352443cb1e2001e43ae58a11d863f80ec5b11b84956aae8f5cd654f75a0da56f313d79b683b27194a5768d8485733a5f11a016366cbf404450bb1ba6bf5b620b
-  data.tar.gz: 4b90542d764e5b78a0cd682065f5df71050cb05f0a971d21979a43627c2e631b8f55b7420efa97fe2ef07fe2416799e4112688a337755355bdfc0e7533322a4a
+  metadata.gz: 5c721b8a4f1e67a3e62ee457869f8afb0f83c39f92e979dc7c63fa1300a03538b9a5ac1b9917b7e39ea44ad9ff89fca1734cedd37d34185c99655d5e6420e2f9
+  data.tar.gz: 4e723b946fbd68b08ef751d2785171a24a0a4c66fec6a1fd6de67cc4992c44952ebdc152321dffb4f6fc9034961eaf510a9579dbdead94534b372ec6055672f1

data/README.md

@@ -4,17 +4,22 @@ Simple gem for implementing texter classes which allow sending SMS messages in s
 
 Unlike similar gems, **Textris** has some unique features:
 
-- phone number E164 validation and normalization with the [Phony](https://github.com/floere/phony) gem
-- multiple, per-environment configurable delivery methods
 - e-mail proxy allowing to inspect messages using [Mailinator](https://mailinator.com/) or similar service
+- phone number E164 validation and normalization with the [Phony](https://github.com/floere/phony) gem
+- multiple, per-environment configurable and chainable delivery methods
+- extensible with any number of custom delivery methods (also chainable)
 - support for testing using self-explanatory `Textris::Base.deliveries`
 - simple, extensible code written from the ground up instead of copying *ActionMailer*
 
+Currently, this gem comes with `test` and `mail` delivery methods, so there's no method for any real SMS gateway yet. Still, you can easily implement your own - see the [Custom delivery methods](#custom-delivery-methods) chapter below.
+
 ## Installation
 
 Add to `Gemfile`:
 
-    gem 'textris'
+```ruby
+gem 'textris'
+```
 
 And run:
 
@@ -24,43 +29,87 @@ And run:
 
 Place texter classes in `app/texters` (e.g. `app/texters/user_texter.rb`):
 
-    class UserTexter < Textris::Base
-      default :from => "Our Team <+48 666-777-888>"
+```ruby
+class UserTexter < Textris::Base
+  default :from => "Our Team <+48 666-777-888>"
 
-      def welcome(user)
-        @user = user
+  def welcome(user)
+    @user = user
 
-        text :to => @user.phone
-      end
-    end
+    text :to => @user.phone
+  end
+end
+```
 
-Place relevant view templates in `app/views/<texter_name>/<action_name>.text.*`, (e.g. `app/views/user_texter/welcome.text.erb`):
+Place relevant view templates in `app/views/<texter_name>/<action_name>.text.*` (e.g. `app/views/user_texter/welcome.text.erb`):
 
-    Welcome to our system, <%= @user.name %>!
+```erb
+Welcome to our system, <%= @user.name %>!
+```
 
 Invoke them from application logic:
 
-    class User < ActiveRecord::Base
-      after_create do
-        UserTexter.welcome(self).deliver
-      end
-    end
+```ruby
+class User < ActiveRecord::Base
+  after_create do
+    UserTexter.welcome(self).deliver
+  end
+end
+```
+
+### Custom delivery methods
+
+Place desired delivery method in `app/deliveries/<name>_delivery.rb` (e.g. `app/deliveries/my_provider_delivery.rb`):
+
+```ruby
+class MyProviderDelivery < Textris::Delivery::Base
+  # Implement sending message to single phone number
+  self.send_message(phone, message)
+    some_send_method(:phone => phone, :text => message.content)
+  end
+
+  # ...or implement sending message to multiple phone numbers at once
+  self.send_message_to_all(message)
+    other_send_method(:phone_array => message.to, :text => message.content)
+  end
+end
+```
+
+> **NOTE**: You can also place your custom deliveries in `app/texters` if you don't want to clutter the *app* directory too much.
+
+Only one of methods above must be implemented for the delivery class to work. In case of multiple phone numbers and no implementation of *send_message_to_all*, the *send_message* method will be invoked multiple times.
+
+After implementing your own deliveries, you can activate them by setting app configuration:
+
+```ruby
+# Use your new delivery
+config.textris_delivery_method = :my_provider
+
+# Chain your new delivery with others, including stock ones
+config.textris_delivery_method = [:my_provider, :mail]
+```
 
 ## Testing
 
 Access all messages that were sent with the `:test` delivery:
 
-    Textris::Base.deliveries
+```ruby
+Textris::Base.deliveries
+```
 
 You may want to clear the delivery queue before each test:
 
-    before(:each) do
-      Textris::Base.deliveries.clear
-    end
+```ruby
+before(:each) do
+  Textris::Base.deliveries.clear
+end
+```
 
 Keep in mind that messages targeting multiple phone numbers, like:
 
-    text :to => ['48111222333', '48222333444']
+```ruby
+text :to => ['48111222333', '48222333444']
+```
 
 will yield multiple message deliveries, each for specific phone number.
 
@@ -70,25 +119,32 @@ You can change default settings by placing them in any of environment files, lik
 
 Choose the delivery method:
 
-    # Don't send anything, access your messages via Textris::Base.deliveries
-    config.textris_delivery_method = :test
+```ruby
+# Don't send anything, access your messages via Textris::Base.deliveries
+config.textris_delivery_method = :test
+
+# Send e-mails instead of SMSes in order to inspect their content
+config.textris_delivery_method = :mail
 
-    # Send e-mails instead of SMSes in order to inspect their content
-    config.textris_delivery_method = :mail
+# Chain multiple delivery methods (e.g. to have e-mail backups of your messages)
+config.textris_delivery_method = [:mail, :test]
+```
 
-Configure the mail delivery:
+Configure the mail delivery with custom templates:
 
-    # E-mail sender, here: "our-team-48666777888@test.app-name.com"
-    config.textris_mail_from_template = '%{from_name:d}-%{from_phone}@%{env:d}.%{app:d}.com'
+```ruby
+# E-mail sender, here: "our-team-48666777888@test.app-name.com"
+config.textris_mail_from_template = '%{from_name:d}-%{from_phone}@%{env:d}.%{app:d}.com'
 
-    # E-mail target, here: "app-name-test-48111222333-texts@mailinator.com"
-    config.textris_mail_to_template = '%{app:d}-%{env:d}-%{to_phone}-texts@mailinator.com'
+# E-mail target, here: "app-name-test-48111222333-texts@mailinator.com"
+config.textris_mail_to_template = '%{app:d}-%{env:d}-%{to_phone}-texts@mailinator.com'
 
-    # E-mail subject, here: "User texter: Welcome"
-    config.textris_mail_subject_template = '%{texter:dh} texter: %{action:h}'
+# E-mail subject, here: "User texter: Welcome"
+config.textris_mail_subject_template = '%{texter:dh} texter: %{action:h}'
 
-    # E-mail body, here: "Welcome to our system, Mr Jones!"
-    config.textris_mail_body_template = '%{content}'
+# E-mail body, here: "Welcome to our system, Mr Jones!"
+config.textris_mail_body_template = '%{content}'
+```
 
 ### Template interpolation
 

data/lib/textris.rb

@@ -4,5 +4,6 @@ require 'action_mailer'
 require 'textris/base'
 require 'textris/message'
 require 'textris/delivery'
+require 'textris/delivery/base'
 require 'textris/delivery/test'
 require 'textris/delivery/mail'

data/lib/textris/delivery.rb

@@ -3,14 +3,16 @@ module Textris
     module_function
 
     def get
-      case Rails.application.config.try(:textris_delivery_method).to_s
-      when 'mail'
-        ::Textris::Delivery::Mail
-      when 'test'
-        ::Textris::Delivery::Test
-      else
-        ::Textris::Delivery::Test
+      methods = Rails.application.config.try(:textris_delivery_method)
+      methods = [*methods].compact
+      if methods.blank?
+        methods = [:test]
       end
+
+      methods.map do |method|
+        "Textris::Delivery::#{method.to_s.camelize}".safe_constantize ||
+          "#{method.to_s.camelize}Delivery".safe_constantize
+      end.compact
     end
   end
 end

data/lib/textris/delivery/base.rb

@@ -0,0 +1,13 @@
+module Textris
+  module Delivery
+    class Base
+      class << self
+        def send_message_to_all(message)
+          message.to.each do |to|
+            send_message(to, message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textris/delivery/mail.rb

@@ -1,6 +1,6 @@
 module Textris
   module Delivery
-    class Mail
+    class Mail < Textris::Delivery::Base
       class Mailer < ActionMailer::Base
         def notify(from, to, subject, body)
           mail :from => from, :to => to, :subject => subject, :body => body
@@ -8,12 +8,6 @@ module Textris
       end
 
       class << self
-        def send_message_to_all(message)
-          message.to.each do |to|
-            send_message(to, message)
-          end
-        end
-
         private
 
         def send_message(to, message)

data/lib/textris/delivery/test.rb

@@ -1,13 +1,7 @@
 module Textris
   module Delivery
-    class Test
+    class Test < Textris::Delivery::Base
       class << self
-        def send_message_to_all(message)
-          message.to.each do |to|
-            send_message(to, message)
-          end
-        end
-
         def messages
           @messages ||= []
         end

data/lib/textris/message.rb

@@ -26,8 +26,10 @@ module Textris
     end
 
     def deliver
-      delivery = ::Textris::Delivery.get
-      delivery.send_message_to_all(self)
+      deliveries = ::Textris::Delivery.get
+      deliveries.each do |delivery|
+        delivery.send_message_to_all(self)
+      end
 
       self
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textris
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Karol Słuszniak
@@ -51,6 +51,7 @@ files:
 - lib/textris.rb
 - lib/textris/base.rb
 - lib/textris/delivery.rb
+- lib/textris/delivery/base.rb
 - lib/textris/delivery/mail.rb
 - lib/textris/delivery/test.rb
 - lib/textris/message.rb