README in has_emails-0.0.1 vs README in has_emails-0.1.0

- old
+ new

@@ -1,77 +1,60 @@ = has_emails -+has_emails+ adds support for emailing capabilities between ActiveRecord models. ++has_emails+ demonstrates a reference implementation for sending emails with +logging and asynchronous support. == Resources -API - -* http://api.pluginaweek.org/has_emails - Wiki * http://wiki.pluginaweek.org/Has_emails -Announcement +API -* http://www.pluginaweek.org +* http://api.pluginaweek.org/has_emails -Source +Development -* http://svn.pluginaweek.org/trunk/plugins/active_record/has/has_emails +* http://dev.pluginaweek.org/browser/trunk/has_emails -Development +Source -* http://dev.pluginaweek.org/browser/trunk/plugins/active_record/has/has_emails +* http://svn.pluginaweek.org/trunk/has_emails == Description Emailing between users and other parts of a system is a fairly common feature in web applications, especially for those that support social networking. Emailing doesn't necessarily need to be between users, but can also act as a way for the web application to send notices and other notifications to users. Rails already provides ActionMailer as a way of sending emails. However, the framework does not provide an easy way to persist emails, track their status, and -process them asynchronously. Designing and building this type of framework can -become complex and cumbersome and takes away from the focus of the web application. -This plugin helps ease that process by providing a complete implementation for -sending and receiving emails to and between models in your application. +process them asynchronously. Designing and building a framework that supports this +can be complex and takes away from the business focus. This plugin can help ease +that process by demonstrating a complete implementation of these features. == Usage -=== Adding emailing support +=== Creating new emails -If you want to use the built-in support for email addresses (using the EmailAddress -model), you can add emailing support for users like so: +Emails should usually still be created using ActionMailer. However, instead of +delivering the emails, you can queue the emails like so: - class User < ActiveRecord::Base - has_email_address - # has_email_addresses if you want to support multiple addresses - end + Notifier.deliver_signup_notification(david) # sends the email now + Notifier.queue_signup_notification(david) # sends the email later (has_emails kicks in) -On the other hand, if you already have the email address for users stored as a -column in your users table, you can add emailing support like so: +In addition to queueing emails, you can build them directly like so: - class User < ActiveRecord::Base - has_messages :emails, - :message_class => 'Email' - end - -=== Creating new emails - - email = user.emails.build - email.to << [user1, email_address1, 'someone@somewhere.com'] + email_address = EmailAddress.find(123) + email = email_address.emails.build + email.to EmailAddress.find(456) email.subject = 'Hey!' email.body = 'Does anyone want to go out tonight?' email.deliver! -As can be seen in the above example, you can use Users, EmailAddresses, or even -Strings as recipients in emails. Each will be automatically converted to the -EmailRecipient class so that it can be stored in the database. - === Replying to emails reply = email.reply_to_all reply.body = "I'd love to go out!" reply.deliver! @@ -80,51 +63,29 @@ forward = email.forward forward.body = 'Interested?' forward.deliver! -=== External process messaging +=== Processing email asynchronously In addition to delivering emails immediately, you can also *queue* emails so -that an external application processes and delivers them. This is especially -useful when you want to asynchronously send e-mails so that it doesn't block the -user interface on your web application. +that an external application processes and delivers them (as mentioned above). +This is especially useful when you want to asynchronously send e-mails so that +it doesn't block the user interface on your web application. -To queue emails for external processing, you can simply use the <tt>queue!</tt> -event, rather than <tt>deliver!</tt>. This will indicate to any external processes -that the email is ready to be sent. The external process can then invoke <tt>deliver!</tt> -whenever it is ready to send the queued email. +To process queued emails, you need an external cron job that checks and sends +them like so: -=== Running migrations + Email.with_state('queued').each do |email| + email.deliver! + end -To migrate the tables required for this plugin, you can either run the -migration from the command line like so: - - rake db:migrate:plugins PLUGIN=has_emails - -or (more ideally) generate a migration file that will integrate into your main -application's migration path: - - ruby script/generate plugin_migration has_emails - == Testing -Before you can run any tests, the following gems must be installed: +Before you can run any tests, the following gem must be installed: * plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper] -* dry_validity_assertions[http://wiki.pluginaweek.org/Dry_validity_assertions] == Dependencies -This plugin depends on the presence of the following plugins: +* plugins_plus[http://wiki.pluginaweek.org/Plugins_plus] * has_messages[http://wiki.pluginaweek.org/Has_messages] - -This plugin is also a plugin+. That means that it contains a slice of an -application, such as models and migrations. To test or use a plugin+, you -must have the following plugins/gems installed: -* plugin_dependencies[http://wiki.pluginaweek.org/Plugin_dependencies] -* loaded_plugins[http://wiki.pluginaweek.org/Loaded_plugins] -* appable_plugins[http://wiki.pluginaweek.org/Appable_plugins] -* plugin_migrations[http://wiki.pluginaweek.org/Plugin_migrations] - -Instead of installing each individual plugin+ feature, you can install them all -at once using the plugins+[http://wiki.pluginaweek.org/Plugins_plus] meta package, -which contains all additional features. +* state_machine[http://wiki.pluginaweek.org/State_machine]