gudleik-acts_as_expired 0.0.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,76 @@
+= ActsAsExpired
+
+Acts as Expired allows you to set expiration information to any ActiveRecord based model.
+
+== Installation
+
+Install using gems:
+
+  # config/environment.rb
+  config.gem 'gudleik-acts_as_expired', :lib => 'acts_as_expired', :source => 'http://gems.github.com'
+
+  $ sudo rake gems:install
+  $ script/generate acts_as_expired_on_migration
+  $ rake db:migrate
+  
+== Usage
+
+Add acts_as_expired to your ActiveRecord model:
+
+  class Foobar < ActiveRecord::Base
+    acts_as_expired
+  end
+  
+Now you can set expiry date using +expires!+
+  # Set expiry using default settings
+  Foobar.first.expires! 
+  
+  # Set expiry date 1 year ahead, and notification time 2 days before expiry
+  Foobar.first.expires! :at => 1.year.from.now, :notify_at => 2.days
+  
+  # Set expiry date to 2010-01-01 and notification set to 12-01-2009
+  Foobar.first.expires! :at => Time.mktime(2010), :notify_at => Time.mktime(2009, 12)
+  
+  # Find out if object has expired
+  Foobar.first.expired? # => true / false
+  
+Expire has some named scopes you can use to find expired/expiring objects.
+
+  # Find objects that has expired
+  Expire.expired  # => array of expired objects
+  
+  # Loop thru objects that are about to expire
+  Expire.within(3.months.from_now).each { |expire| puts "#{expire.expirable.to_s} expires in #{time_ago_in_words(expire.at)}" }
+  
+== Notifications
+
+You can also set notification options to the Expire object, using +notify_at+ and +notify_email+.
++notify_at+ is when notification should be sent, and +notify_email+ is the email address the notification should be sent to.
+
+The gem does not provide any methods to automatically send notifications, this is up to you.
+But here is an example of how this can be done. First create an ExpiredMailer:
+
+  # app/models/expired_mailer.rb
+  class ExpiredMailer < ActionMailer::Base
+    def notification(object)
+      raise ArgumentError, "notify_email not set!" if object.notify_email.blank?
+    
+      recipients  object.notify_email
+      subject     "Notification about expiring object"
+      from        "dev-null@localhost"
+      body        :object => object
+    end
+  end
+
+Then setup a cronjob and run something like this using a rake task or script/runner:
+  
+  Expire.notifiable.each do |expired|
+    ExpiredMailer.deliver_notification(expired)
+    expired.update_attribute(:notified_at, Time.now)
+  end
+
+The gem ships with an ExpiredMailer, you can install it with 'script/generate acts_as_expired_mailer'.
+But it's not made to be portable, so it probably won't work out-of-the-box. 
+I recommend you create your own expired_mailer.
+
+Copyright (c) 2009 Gudleik Rasch <gudleik@rastamatra.org>, released under the MIT license

data/generators/acts_as_expired_mailer/acts_as_expired_mailer_generator.rb

@@ -0,0 +1,11 @@
+class ActsAsExpiredMailerGenerator < Rails::Generator::Base
+
+  def manifest
+    record do |m|
+      m.directory "app/views/expired_mailer"
+      m.file 'notification.text.html.erb', 'app/views/expired_mailer/notification.text.html.erb'
+      m.file 'notification.text.plain.erb', 'app/views/expired_mailer/notification.text.plain.erb'
+    end
+  end
+  
+end

data/generators/acts_as_expired_mailer/templates/notification.text.html.erb

@@ -0,0 +1,26 @@
+<p>
+  <%= t('.intro') %> 
+</p>
+
+<ul>
+  <li>
+    <a href="<%= Settings.mail.url_options.protocol %>://<%= Settings.mail.url_options.host %><%= url_for(@object.expirable) %>"><%= @object.expirable.to_s %></a>
+
+    <br/>
+    <b><%= Expire.human_attribute_name('at') %></b>: <%= @object.at.strftime("%Y-%m-%d") -%>
+  </li>
+</ul>
+
+<% if @object.note -%>
+<p>
+  <%= Expire.human_attribute_name("notes") -%>:
+  <div style="margin:1em">
+    <%= @object.note -%>
+  </div>
+</p>
+<% end -%>
+
+<p>
+--<br/>
+<%= t('.signature', :app_name => Settings.app.name) %> 
+</p>

data/generators/acts_as_expired_mailer/templates/notification.text.plain.erb

@@ -0,0 +1,12 @@
+<%= t('.intro') %> 
+
+  * <%= @object.expirable.to_s %> <<%= Settings.mail.url_options.protocol %>://<%= Settings.mail.url_options.host %><%= url_for(@object.expirable) %>>
+  <%= Expire.human_attribute_name('at') %>: <%= @object.at.strftime("%Y-%m-%d") -%>
+
+<% if @object.note -%>
+  <%= Expire.human_attribute_name("notes") -%>:
+  <%= @object.note -%>
+<% end -%>
+
+--
+<%= t('.signature', :app_name => Settings.app.name) %>

data/generators/acts_as_expired_on_migration/acts_as_expired_on_migration_generator.rb

@@ -0,0 +1,7 @@
+class ActsAsExpiredOnMigrationGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.migration_template 'migration.rb', 'db/migrate', :migration_file_name => "acts_as_expired_on_migration"
+    end
+  end
+end

data/generators/acts_as_expired_on_migration/templates/migration.rb

@@ -0,0 +1,26 @@
+class ActsAsExpiredOnMigration < ActiveRecord::Migration
+  
+  def self.up
+    create_table :expires do |t|
+      t.integer   :expirable_id
+      t.string    :expirable_type, :limit => 30
+      
+      t.text      :note
+      t.timestamp :at
+      t.string    :notify_email
+      t.timestamp :notify_at, :default => nil
+      t.timestamp :notified_at, :default => nil
+      
+      t.timestamps      
+    end
+    
+    add_index :expires, [ :expirable_id, :expirable_type ], :unique => true
+    add_index :expires, :notify_at
+    add_index :expires, :at
+  end
+  
+  def self.down
+    drop_table :expires
+  end
+  
+end

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/lib/acts_as_expired.rb

@@ -0,0 +1,71 @@
+# ActsAsExpired
+#
+# This module is included in ActiveRecord::Base, so you can add this feature
+# to your model using +acts_as_expirable+.
+#
+# Making an ActiveRecord class "acts as expired" means you can add expiry
+# information to it.
+
+module ActsAsExpired
+  
+  #
+  # Called when plugin is included
+  #
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+  
+  module ClassMethods
+    def acts_as_expired
+      include ActsAsExpired::InstanceMethods
+      has_one :expire, :as => :expirable
+    end
+  end
+  
+  module InstanceMethods
+    
+    # Returns true if the object has expired.
+    def expired?
+      return false if expire.nil?
+      expire.expired?
+    end
+    
+    #
+    # Creates or updates the Expire object for the class.
+    # 
+    # The options hash is passed directly to the Expire object, so you can pass 
+    # any valid attribute found in the Expire class.
+    #
+    # Some values have default settings:
+    # * :at             Time when object should expire. Default is 1.year.from_now
+    # * :notify_at      Time when notification should be sent. Default is 30.days before :at
+    #                   You can pass both a Time object or a Fixnum, like 30.days
+    # * :notify_email   Email address that should receive expiry email. Default is nil.
+    #
+    # Returns the expire object.
+    # An error is raised if the record is invalid.
+    #
+    def expires!(options = {})
+      options = {
+        :at           => 1.year.from_now,
+        :notify_at    => 30.days,
+        :notify_email => nil
+      }.update(options)
+      
+      # set notify_at 
+      if options[:notify_at].is_a?(Fixnum)
+        options[:notify_at] = options[:notify_at].until(options[:at])
+      end
+      
+      # Create or update existing object      
+      if self.expire.nil?
+        self.expire = Expire.create!(options)
+      else
+        self.expire.update_attributes!(options)
+      end
+      
+      self.expire
+    end
+  end
+  
+end

data/lib/expire.rb

@@ -0,0 +1,64 @@
+# This class holds information about the expiration, 
+# such as time when object expires and notification options.
+#
+#   create_table :expires do |t|
+#     t.integer   :expirable_id
+#     t.string    :expirable_type, :limit => 30
+#     
+#     t.text      :note
+#     t.timestamp :at
+#     t.string    :notify_email
+#     t.timestamp :notify_at, :default => nil
+#     t.timestamp :notified_at, :default => nil
+#     
+#     t.timestamps      
+#   end
+#
+# There are also some named scopes you can use to fetch all expired/expiring objects:
+# Some examples:
+#   Expire.expired                  # => all expired objects
+#   Expire.notifiable               # => all objects that are about to expire with notification options set.
+#   Expire.within                   # => all objects that expires within 2 weeks from now
+#   Expire.within 3.months.from_now # => returns all objects that expires within 3 months from now
+#
+class Expire < ActiveRecord::Base
+
+  belongs_to :expirable, :polymorphic => true
+  
+  validate :validate_dates
+  
+  # All expired objects
+  named_scope :expired, :conditions => [ 'NOW() >= at' ], :order => 'expires.at'
+  
+  # All notifiable objects that are about to expire
+  named_scope :notifiable, :conditions => [ "NOW() >= notify_at AND (NOW() <= notified_at OR notified_at IS NULL) AND notify_email != ''"], :order => 'expires.at'
+  
+  # All objects that are about to expire
+  named_scope :within, lambda { |*args| { :conditions => [ "at <= ?", (args.first || 2.weeks.from_now )]} }
+
+  #
+  # Returns true if object has expired
+  #
+  def expired?
+    return false if at.nil?
+    return at.past?
+  end
+  
+  #
+  # Notification is only enabled if notify_email and notify_at is set
+  #
+  def notification_enabled?
+    not notify_email.blank? and not notify_at.nil?
+  end
+  
+  private
+  
+  # 
+  # Make sure expiry date is in future and notification date is before expiry date
+  #
+  def validate_dates
+    errors.add(:at, :expire_date_is_in_past) if self.at < Time.now
+    errors.add(:notify_at, :notify_date_is_before_expiry_date) if self.notify_at > self.at
+  end
+  
+end

data/lib/expired_mailer.rb

@@ -0,0 +1,18 @@
+# Class for sending alerts when objects are about to expire.
+
+class ExpiredMailer < ActionMailer::Base
+  
+  #
+  # Send notification about an expiring object
+  #
+  def notification(object)
+    raise ArgumentError, "notify_email not set!" if object.notify_email.blank?
+    
+    recipients  object.notify_email
+    subject     I18n.t('expired_mailer.notification.subject', :expirable => object.expirable)
+    from        Settings.mail.headers.from
+    headers     'reply-to' => Settings.mail.headers.devnull
+    body        :object => object
+  end
+
+end

data/rails/init.rb

@@ -0,0 +1,5 @@
+require 'acts_as_expired'
+
+ActiveRecord::Base.send(:include, ActsAsExpired)
+
+RAILS_DEFAULT_LOGGER.info "** acts_as_expired: initialized properly."

data/tasks/acts_as_expired_tasks.rake

@@ -0,0 +1,25 @@
+# Rake file for acts_as_expired
+# 
+# To send email alerts to expiring objects, run:
+#   rake expires:notify
+#
+
+namespace :expires do
+
+  desc 'Notify about objects that are about to expire (by email)'
+  task 'notify' => :environment do
+    Expire.notifiable.each do |object|
+      
+      puts %{Sending notification to #{object.notify_email} for object "#{object.expirable}"}
+
+      begin
+        mail = ExpiredMailer.deliver_notification(object)
+        object.notified_at = Time.now
+        object.save
+      rescue => error
+        puts error
+      end
+    end    
+  end
+
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: gudleik-acts_as_expired
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Gudleik Rasch
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-07 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Rails plugin that allows expiring of ActiveRecord models
+email: gudleik@rastamatra.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- MIT-LICENSE
+- init.rb
+- rails/init.rb
+- tasks/acts_as_expired_tasks.rake
+- lib/acts_as_expired.rb
+- lib/expire.rb
+- lib/expired_mailer.rb
+- generators/acts_as_expired_mailer/acts_as_expired_mailer_generator.rb
+- generators/acts_as_expired_mailer/templates/notification.text.html.erb
+- generators/acts_as_expired_mailer/templates/notification.text.plain.erb
+- generators/acts_as_expired_on_migration/acts_as_expired_on_migration_generator.rb
+- generators/acts_as_expired_on_migration/templates/migration.rb
+has_rdoc: false
+homepage: http://github.com/gudleik/acts_as_expired/tree
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Rails plugin that allows expiring of ActiveRecord models
+test_files: []
+