Skip to content
Browse files

Updated README and comments for inclusion in rdoc

  • Loading branch information...
1 parent c967e4c commit e88796b23ffadfe2295320f8bbdad8c03adea633 @whtt-eric committed May 18, 2011
View
1 Gemfile
@@ -14,4 +14,5 @@ group :development do
gem "bundler", "~> 1.0.0"
gem "jeweler", "~> 1.6.0"
gem "simplecov", ">=0.4.0"
+ gem "hanna"
end
View
7 Gemfile.lock
@@ -41,6 +41,11 @@ GEM
rails (~> 3.0)
rspec-rails
git (1.2.5)
+ haml (2.2.24)
+ hanna (0.1.12)
+ haml (~> 2.2.8)
+ rake (~> 0.8.2)
+ rdoc (~> 2.3.0)
hominid (3.0.2)
i18n (0.5.0)
jeweler (1.6.0)
@@ -74,6 +79,7 @@ GEM
rake (>= 0.8.7)
thor (~> 0.14.4)
rake (0.8.7)
+ rdoc (2.3.0)
rspec (2.5.0)
rspec-core (~> 2.5.0)
rspec-expectations (~> 2.5.0)
@@ -106,6 +112,7 @@ DEPENDENCIES
bundler (~> 1.0.0)
factory_girl_rails (= 1.0.1)
generator_spec
+ hanna
hominid (>= 3.0.2)
jeweler (~> 1.6.0)
mocha (= 0.9.12)
View
91 README.rdoc
@@ -1,6 +1,90 @@
-= subscribed_to
+= SubscribedTo
-Abstract layer for managing mailing list subscriptions
+Abstraction layer for managing mailing list subscription information for your user model.
+
+=== Requirements
+
+* Rails 3.x
+
+=== Supported Services
+
+<b>MailChimp</b>
+
+via the Homonid gem - http://github.com/terra-firma/hominid
+
+API v1.3 - http://apidocs.mailchimp.com/1.3
+
+* listSubscribe
+* listUnsubscribe
+* listUpdateMember
+
+
+<b>Constant Contact</b>
+
+Planned
+
+== Installation
+
+Add the gem to your Gemfile
+
+ gem "subscribed_to"
+
+Install the gem using bundler
+
+ bundle install
+
+Run the generator. You must specify the name of your user model.
+Other options:
+
+<tt>--skip-migration</tt>:: Do not generate the migration file to add the required column
+<tt>--service=SERVICE</tt>:: Specify which mailing list service you subscribe to (currently only supports "mail_chimp")
+
+ rails generate subscribed_to:install MODEL
+
+If you run the generator with <tt>--skip-migration</tt>, then you must be sure to to include the <tt>subscribed_to_list</tt> column in some other migration.
+
+ t.boolean :subscribed_to_list, :default => false
+
+Be sure to run the migration before you continue.
+
+=== Initializer Configuration
+
+After the initializer has been generated, you must set your mail service configuration options. The initializer is located at: <tt>config/initializers/subscribe_to.rb</tt>
+
+==== Mail Chimp
+
+Set your API key
+
+ mail_chimp_config.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-us1"
+
+Set up your mailing lists to subscribe users to. List names can be any valid symbol.
+
+<tt>:id</tt>:: id of list - get this from the "Settings" page of your list
+<tt>:merge_vars</tt>:: hash of merge vars on list, MUST at least include "EMAIL" (do not use "MERGE0")
+
+ mail_chimp_config.lists = {
+ :mailing_list => {
+ :id => "xxxxxxxx",
+ :merge_vars => {"FNAME" => :first_name, "LNAME" => :last_name, "EMAIL" => :email}}}
+
+=== User Model Configuration
+
+You must enable *SubscribedTo* in your user model with <tt>subscribed_to</tt>.
+
+The only paramter it takes is a symbol which corresponds to a list in the <tt>mail_chimp_config.lists</tt> hash.
+
+ subscribed_to :mailing_list
+
+You may also need to specify <tt>subscribed_to_list</tt> as an accessible attribute.
+
+ attr_accessible :subscribed_to_list
+
+=== View Configuration
+
+To get things working with the view, just include a checkbox input on your user registration/edit forms.
+
+ = f.check_box :subscribed_to_list
+ = f.label :subscribed_to_list, "Join the mailing list"
== Contributing to subscribed_to
@@ -14,6 +98,5 @@ Abstract layer for managing mailing list subscriptions
== Copyright
-Copyright (c) 2011 whtt-eric. See LICENSE.txt for
-further details.
+Copyright (c) 2011 Eric Salczynski. See LICENSE.txt for further details.
View
7 Rakefile
@@ -33,14 +33,9 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
spec.pattern = FileList['spec/**/*_spec.rb']
end
-RSpec::Core::RakeTask.new(:rcov) do |spec|
- spec.pattern = 'spec/**/*_spec.rb'
- spec.rcov = true
-end
-
task :default => :spec
-require 'rake/rdoctask'
+require 'hanna/rdoctask'
Rake::RDocTask.new do |rdoc|
version = File.exist?('VERSION') ? File.read('VERSION') : ""
View
4 lib/generators/subscribed_to/install_generator.rb
@@ -1,6 +1,6 @@
module SubscribedTo
- module Generators
- class InstallGenerator < Rails::Generators::NamedBase
+ module Generators #:nodoc:
+ class InstallGenerator < Rails::Generators::NamedBase #:nodoc:
include Rails::Generators::Migration
source_root File.expand_path('../templates', __FILE__)
View
23 lib/subscribed_to.rb
@@ -19,24 +19,28 @@ def self.setup
# Sets Mail Chimp configuration using a block
#
- # SubscribedTo.setup do |config|
- # config.service = :mail_chimp
+ # Example configuration:
+ # SubscribedTo.setup do |config|
+ # config.service = :mail_chimp
#
- # config.mail_chimp do |mail_chimp_config|
- # mail_chimp_config.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-us1"
- # mail_chimp_config.lists = {:mailing_list => {:id => "123456", :merge_vars => {"FNAME" => :first_name}
- # end
- # end
+ # config.mail_chimp do |mail_chimp_config|
+ # mail_chimp_config.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-us1"
+ # mail_chimp_config.lists = {:mailing_list => {:id => "123456", :merge_vars => {"FNAME" => :first_name}
+ # end
+ # end
def self.mail_chimp(&block)
@@mail_chimp_config = SubscribedTo::MailChimp::Config.new
block.call @@mail_chimp_config
end
- def self.included(base) #nodoc:
+ def self.included(base) #:nodoc:
base.send :extend, ClassMethods
end
module ClassMethods
+ # Enable *SubscribedTo* in your user model.
+ # The only paramter it takes is a symbol which corresponds to a list in the <tt>mail_chimp_config.lists</tt> hash.
+ # subscribed_to :mailing_list
def subscribed_to(id)
include InstanceMethods
include MailChimp::InstanceMethods if SubscribedTo.service == :mail_chimp
@@ -49,15 +53,18 @@ def subscribed_to(id)
end
end
+ # Returns the list id for the class as defined in mail_chimp
def list_id
SubscribedTo.mail_chimp_config.lists[@list_key][:id]
end
+ # Returns the hash of merge vars for the class as defined in mail_chimp
def merge_vars
SubscribedTo.mail_chimp_config.lists[@list_key][:merge_vars]
end
end
+ # Provides instance methods which should be overwritten in service modules
module InstanceMethods
private
View
5 lib/subscribed_to/mail_chimp.rb
@@ -2,12 +2,13 @@
require 'hominid'
module SubscribedTo
+ # Module for MailChimp subscription interaction
module MailChimp
module InstanceMethods
private
# Subscribe the user to the mailing list
- def subscribe_to_list
+ def subscribe_to_list #:doc:
if subscribed_to_list
h = Hominid::API.new(SubscribedTo.mail_chimp_config.api_key)
h.list_subscribe(self.class.list_id, self.email)
@@ -17,7 +18,7 @@ def subscribe_to_list
end
# Update attributes of existing member
- def update_list_member
+ def update_list_member #:doc:
config = SubscribedTo.mail_chimp_config
merge_vars = self.class.merge_vars
View
2 lib/subscribed_to/mail_chimp/config.rb
@@ -1,6 +1,6 @@
module SubscribedTo
module MailChimp
- class Config < Hash
+ class Config < Hash #:nodoc:
# Creates an accessor that simply sets and reads a key in the hash:
# Borrowed from Warden: https://github.com/hassox/warden/blob/master/lib/warden/config.rb
def self.hash_accessor(*names) #:nodoc:
View
2 lib/subscribed_to/version.rb
@@ -1,5 +1,5 @@
module SubscribedTo
- module Version
+ module Version #:nodoc:
MAJOR = 0
MINOR = 1
PATCH = 0

0 comments on commit e88796b

Please sign in to comment.
Something went wrong with that request. Please try again.