Rakismet
========

**Akismet** (<http://akismet.com/>) is a collaborative spam filtering service.
**Rakismet** is easy Akismet integration with your Rails app, including support
for TypePad's AntiSpam service.


Setup
=====

As a plugin
-----------

Install with `script/plugin install git://github.com/jfrench/rakismet`

Rakismet installation should have created a file called rakismet.rb in
config/initializers. If not, you can copy the template from:
vendor/plugins/rakismet/generators/rakismet/templates/config/initializers/rakismet.rb.

As a gem
--------

`gem install rakismet` if you're using gemcutter or 
`gem install jfrench-rakismet` if you're using GitHub.

From your app root, run `./script/generate rakismet` to create the Rakismet
initializer.

Getting Started
---------------

Once you've installed Rakismet via your method of choice, you'll need an API 
key from the folks at WordPress. Head on over to http://wordpress.com/api-keys/ 
and sign up for a new username.

Edit config/initializers/rakismet.rb and fill in `Rakismet::URL` and
`Rakismet::KEY` with the URL of your application and the key you received
from WordPress.

If you wish to use another Akismet-compatible API provider such as TypePad's
antispam service, you'll also need to change the `Rakismet::HOST`.

Finally, introduce Rakismet to your application. Let's assume you have a Comment
model and a CommentsController:

    class Comment < ActiveRecord::Base
      has_rakismet
    end

    class CommentsController < ActionController::Base
      has_rakismet
    end


Basic Usage
===========

Rakismet provides three methods for interacting with Akismet:

  `spam?`

From within a CommentsController action, simply call `@comment.spam?` to get a
true/false response. True means it's spam, false means it's not. Well,
usually; it's possible something went wrong and Akismet returned an error
message. `@comment.spam?` will return false if this happens. You can check
`@comment.akismet_response` to be certain; anything other than 'true' or
'false' means you got an error. That said, as long as you're collecting the
data listed above it's probably sufficient to check `spam?` alone.

  `ham!` and `spam!`

Akismet works best with your feedback. If you spot a comment that was
erroneously marked as spam, `@comment.ham!` will resubmit to Akismet, marked
as a false positive. Likewise if they missed a spammy comment,
`@comment.spam!` will resubmit marked as spam.


What's Required in the Comment Model?
=====================================

Rakismet sends the following information to the spam-hungry robots at Akismet.
This means these attributes should be stored in your Comment model or
accessible through that class's associations.

    author        : name submitted with the comment
    author_url    : URL submitted with the comment
    author_email  : email submitted with the comment
    comment_type  : 'comment', 'trackback', 'pingback', or whatever you fancy
    content       : the content submitted
    permalink     : the permanent URL for the entry the comment belongs to
    user_ip       : IP address used to submit this comment
    user_agent    : user agent string
    referrer      : http referer

`user_ip`, `user_agent`, and `referrer` are optional; you don't have to store
them, but it's a good idea. If you omit them from your model (see "Customizing
Attributes"), the `spam?` method will attempt to extract these values from the
current request object, if there is one. This means Rakismet can operate
asynchronously by storing the request attributes and validating the comment at
a later time. Or it can operate synchronously by plucking the request
attributes from the environment at the time the comment is initially submitted
and validating on the spot. The latter could work well with a before_create
callback.


Customizing the Comment Model
=============================

If your attribute names don't match those listed above, or if some of them
live on other objects, you can pass `has_rakismet` a hash mapping the default 
attributes to your own. You can change the names, if your comment attributes
don't match the defaults:

    class Comment < ActiveRecord::Base
      has_rakismet :author => :commenter_name,
                   :author_email => :commenter_email
    end

Or you can pass in a proc, to access associations:

    class Comment < ActiveRecord::Base
      belongs_to :author
      has_rakismet :author => proc { author.name },
                   :author_email => proc { author.email }
    end

For any attribute you don't specify, Rakismet will try to find an attribute or 
method matching the default name. As mentioned above, if `user_ip`,
`user_agent`, and `referrer` are not present on your model, Rakismet will
attempt to find them in the request environment when `spam?` is called from
within a Rakismet-aware controller action.

Customizing the Comments Controller
===================================

Most of the time you won't be checking for spam on every action defined in
your controller. If you only call `spam?` within `CommentsController#create` 
and you'd like to reduce filter overhead, `has_rakismet` takes `:only` and
`:except` parameters that work like the standard before/around/after filter
options.

    class CommentsController < ActionController::Base
      has_rakismet :only => :create
    end

Forked
=============================

At the time of forking, the only addition to this project has been to add gemspec 
and generator templates so rakismet can be used as a gem. This is a better solution
when working with reloadable plugins as rakismet is not compatible when plugins are
reloadable.
    
--------------------------------------------------------------
Copyright (c) 2008 Josh French, released under the MIT license