apn_on_rails 0.1.0 → 0.1.1

data/README

@@ -1,16 +1,17 @@
-APN on Rails
-(Apple Push Notifications on Rails)
-=====================
+=APN on Rails (Apple Push Notifications on Rails)
+
+APN on Rails is a Ruby on Rails gem that allows you to easily add Apple Push Notification (iPhone)
+support to your Rails application.
+
+==Acknowledgements:
 
-Acknowledgements
-----------------
 This gem is a re-write of a plugin that was written by Fabien Penso and Sam Soffes.
 Their plugin was a great start, but it just didn't quite reach the level I hoped it would.
 I've re-written, as a gem, added a ton of tests, and I would like to think that I made it
 a little nicer and easier to use.
 
-Converting Your Certificate
----------------------------
+==Converting Your Certificate:
+
 Once you have the certificate from Apple for your application, export your key
 and the apple certificate as p12 files. Here is a quick walkthrough on how to do this:
 
@@ -26,28 +27,38 @@ Put 'apple_push_notification_production.pem' in config/
 
 If you are using a development certificate, then change the name to apple_push_notification_development.pem instead.
 
-Installing
-----------
+==Installing:
+
+===Stable (RubyForge):
 
-From RubyForge:
   $ sudo gem install apn_on_rails
 
-Or, if you like to live on the edge:
+===Edge (GitHub):
+
   $ sudo gem install markbates-apn_on_rails --source=http://gems.github.com
-  
-Then you just add the following require, wherever it makes sense to you:
-  require 'apn_on_rails'
+
+===Rails Gem Management:
 
 If you like to use the built in Rails gem management:
+
   config.gem 'apn_on_rails'
 
 Or, if you like to live on the edge:
+
   config.gem 'markbates-apn_on_rails', :lib => 'apn_on_rails', :source => 'http://gems.github.com'
-  
-Setup and Configuration
------------------------
-Once you have the gem installed you need to add the following to your Rakefile so you can use the
+
+==Setup and Configuration:
+
+Once you have the gem installed via your favorite gem installation, you need to require it so you can
+start to use it:
+
+Add the following require, wherever it makes sense to you:
+
+  require 'apn_on_rails'
+
+You also need to add the following to your Rakefile so you can use the
 Rake tasks that ship with APN on Rails:
+
   begin
     require 'apn_on_rails_tasks'
   rescue MissingSourceFile => e
@@ -55,6 +66,7 @@ Rake tasks that ship with APN on Rails:
   end
 
 Now, to create the tables you need for APN on Rails, run the following task:
+
   $ rake apn:db:migrate
 
 APN on Rails uses the Configatron gem, http://github.com/markbates/configatron/tree/master, 
@@ -72,17 +84,20 @@ see fit:
 
 That's it, now you're ready to start creating notifications.
 
-Example
--------
-
-    $ ./script/console
-    >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX")
-    >> notification = APN::Notification.new
-    >> notification.device = device
-    >> notification.badge = 5
-    >> notification.sound = true
-    >> notification.alert = "foobar"
-    >> notification.save
-    >> APN::Notification.send_notifications
+==Example:
+
+  $ ./script/console
+  >> device = APN::Device.create(:token => "XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX")
+  >> notification = APN::Notification.new
+  >> notification.device = device
+  >> notification.badge = 5
+  >> notification.sound = true
+  >> notification.alert = "foobar"
+  >> notification.save
+  >> APN::Notification.send_notifications
+
+You can also run the following Rake task to send your notifications:
+
+  $ rake apn:notifications:deliver
 
 Released under the MIT license.

data/lib/apn_on_rails/apn_on_rails.rb

@@ -22,13 +22,14 @@ if rails_env == 'production'
   configatron.apn.set_default(:cert, File.join(rails_root, 'config', 'apple_push_notification_production.pem'))
 end
 
-module APN
+module APN # :nodoc:
   
-  module Errors
+  module Errors # :nodoc:
     
+    # Raised when a notification message to Apple is longer than 256 bytes.
     class ExceededMessageSizeError < StandardError
       
-      def initialize(message)
+      def initialize(message) # :nodoc:
         super("The maximum size allowed for a notification payload is 256 bytes: '#{message}'")
       end
       

data/lib/apn_on_rails/app/models/apn/device.rb

@@ -1,3 +1,8 @@
+# Represents an iPhone (or other APN enabled device).
+# An APN::Device can have many APN::Notification.
+# 
+# Example:
+#   Device.create(:token => '5gxadhy6 6zmtxfl6 5zpbcxmw ez3w7ksf qscpr55t trknkzap 7yyt45sc g6jrw7qz')
 class APN::Device < ActiveRecord::Base
   set_table_name 'apn_devices'
   
@@ -6,6 +11,8 @@ class APN::Device < ActiveRecord::Base
   validates_uniqueness_of :token
   validates_format_of :token, :with => /^[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}\s[a-z0-9]{8}$/
   
+  # Stores the token (Apple's device ID) of the iPhone (device).
+  # 
   # If the token comes in like this:
   #  '<5gxadhy6 6zmtxfl6 5zpbcxmw ez3w7ksf qscpr55t trknkzap 7yyt45sc g6jrw7qz>'
   # Then the '<' and '>' will be stripped off.

data/lib/apn_on_rails/app/models/apn/notification.rb

@@ -1,3 +1,19 @@
+# Represents the message you wish to send. 
+# An APN::Notification belongs to an APN::Device.
+# 
+# Example:
+#   apn = APN::Notification.new
+#   apn.badge = 5
+#   apn.sound = 'my_sound.aiff'
+#   apn.alert = 'Hello!'
+#   apn.device = APN::Device.find(1)
+#   apn.save
+# 
+# To deliver call the following method:
+#   APN::Notification.send_notifications
+# 
+# As each APN::Notification is sent the <tt>sent_at</tt> column will be timestamped,
+# so as to not be sent again.
 class APN::Notification < ActiveRecord::Base
   include ::ActionView::Helpers::TextHelper
   extend ::ActionView::Helpers::TextHelper
@@ -6,6 +22,10 @@ class APN::Notification < ActiveRecord::Base
   
   belongs_to :device, :class_name => 'APN::Device'
   
+  # Stores the text alert message you want to send to the device.
+  # 
+  # If the message is over 150 characters long it will get truncated
+  # to 150 characters with a <tt>...</tt>
   def alert=(message)
     if !message.blank? && message.size > 150
       message = truncate(message, :length => 150)
@@ -55,6 +75,15 @@ class APN::Notification < ActiveRecord::Base
   
   class << self
     
+    # Opens a connection to the Apple APN server and attempts to batch deliver
+    # an Array of notifications.
+    # 
+    # This method expects an Array of APN::Notifications. If no parameter is passed
+    # in then it will use the following:
+    #   APN::Notification.all(:conditions => {:sent_at => nil})
+    # 
+    # As each APN::Notification is sent the <tt>sent_at</tt> column will be timestamped,
+    # so as to not be sent again.
     def send_notifications(notifications = APN::Notification.all(:conditions => {:sent_at => nil}))
       unless notifications.nil? || notifications.empty?
         logger.info "APN: Attempting to deliver #{pluralize(notifications.size, 'notification')}."

data/lib/apn_on_rails/db/migrate/20090723132058_create_apn_devices.rb

@@ -1,4 +1,4 @@
-class CreateApnDevices < ActiveRecord::Migration
+class CreateApnDevices < ActiveRecord::Migratio # :nodoc:
   def self.up
     create_table :apn_devices do |t|
       t.text :token, :size => 71, :null => false

data/lib/apn_on_rails/db/migrate/20090723132059_create_apn_notifications.rb

@@ -1,4 +1,4 @@
-class CreateApnNotifications < ActiveRecord::Migration
+class CreateApnNotifications < ActiveRecord::Migration # :nodoc:
   
   def self.up
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: apn_on_rails
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - markbates