README.md in feeder-0.3.0 vs README.md in feeder-0.5.1
- old
+ new
@@ -1,7 +1,13 @@
-# Mingle
+# Feeder
+[](https://rubygems.org/gems/feeder)
+[](https://travis-ci.org/hyperoslo/feeder)
+[](https://gemnasium.com/hyperoslo/feeder)
+[](https://codeclimate.com/github/hyperoslo/feeder)
+[](https://coveralls.io/r/hyperoslo/feeder)
+
Feeder gives you a mountable engine that provides a route to a feed page in your
Ruby on Rails application.
## Installation
@@ -18,13 +24,124 @@
$ gem install feeder
Install the migrations:
rake feeder:install:migrations
-
+
Run the migrations:
rake db:migrate
+
+## Usage
+
+To make Feeder available, mount it to a route by adding the following somewhere
+in your _config/routes.rb_:
+
+```ruby
+mount Feeder::Engine => "/feed"
+```
+
+You will now be able to display a feed on _/feed_ in your application. In order
+for Feeder to display anything in your feed, however, you will need to make
+views per item type in the feed. Feeder looks up these views in
+_app/views/feeder/types_ by default, and then checks for a partial with the same
+name as your item type. As an example, if you have a `Message` model that you
+wish to list out on your feed, you would make a file called *_message.html.erb*
+in _app/views/feeder/types_.
+
+Feeder also comes with an observer for automatically generating wrapper items
+for your feedables (e.g. messages). In order to use it, you only need to register
+`Feeder::FeedableObserver` into your app, which can be done in
+_config/application.rb_ like this:
+
+```ruby
+config.active_record.observers = [ 'Feeder::FeedableObserver' ]
+```
+
+Then, all you need to do is tell Feeder what to
+observe, which is done through an initializer, like this:
+
+```ruby
+Feeder.configure do |config|
+ config.observe Message
+end
+```
+
+... and declare that your `Message` model is feedable:
+
+```ruby
+class Message < ActiveRecord::Base
+ feedable
+end
+```
+
+If you don't want to publish every message in the feed, you can supply a condition
+to `observe`:
+
+```ruby
+Feeder.configure do |config|
+ config.observe Message, if: -> message { message.show_in_feed? }
+end
+```
+
+Pretty neat.
+
+### Filtering
+
+Want to filter out what feedables to display in your feed? We've got you covered
+through the all-powerful `filter` scope! Give it a hash of feedables and the
+IDs that you want to fetch, and Feeder makes sure to only return feed items with
+the specified feedables. You may also pass in the symbol `:all` instead of a
+list of IDs, which would fetch each of them. For example: say you have the
+following feedables:
+
+- `ShortMessage`
+- `Tweet`
+- `NewsArticle`
+
+To get `Feeder::Item`s with news articles having IDs `[1, 2, 3, 4, 5]`, tweets
+`[2, 4, 6, 7]` and all short message, you could do like this:
+
+```ruby
+Feeder::Item.filter(
+ NewsArticle => [1, 2, 3, 4, 5],
+ Tweet => [2, 4, 6, 7],
+ ShortMessage => :all,
+)
+```
+
+**NOTE:** The `filter` scope is _exclusive_, meaning that anything you _do not_
+pass in to it will also not be brought back. With the above feedables, if you
+only want short messages `[1, 3, 4]`, but all of the tweets and news articles,
+you would have to specify them as well, like this:
+
+```ruby
+Feeder::Item.filter(
+ ShortMessage => [1, 3, 4],
+ Tweet => :all,
+ NewsArticle => :all
+)
+```
+
+The following would only return feed items with short messages:
+
+```ruby
+Feeder::Item.filter(ShortMessage => [1, 3, 4])
+```
+
+### Configuration
+
+```ruby
+Feeder.configure do |config|
+ # A list of scopes that will be applied to the feed items in the controller.
+ config.scopes << proc { limit 5 }
+end
+```
+
+### Stickies
+
+You can "sticky" messages in your feed so they're pinned at the top regardless of when
+they were created. Just set the `sticky` attribute and Feeder will take care of the rest.
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)