# Acts As Featureable

[![Build Status](https://travis-ci.org/kainage/acts_as_featureable.png)](https://travis-ci.org/kainage/acts_as_featureable)

Requires ruby *1.9.3* or later

Add a polymorphic resource to your rails app for pulling content to a main/features page.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'acts_as_featureable'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install acts_as_featureable
    
Run the generator:

    $ rails g features

This will create the migration file and an initializer.

Migrate the database:

    $ rake db:migrate

## Configuration

Edit the initializer file to set default settings for feature size and auto title & summary assigning:

## Usage

### Featureable Model

Add the appropriate line to the class you want to feature:

```ruby
class Topic
	acts_as_featurable
end
```

Add the routes to your _routes_ config file for the resource(s) you wish to make featureable

```ruby
resources :topics do
	resources :features
end
```

### CanCan integration

If you are using CanCan for authorization, the _features controller_ will automatically add authorization
to each action.

### Creating Features

Add a feature to a model. The _title_ and _summary_ (or whichever methods you add in the initializer file) will be assigned:

```ruby
featureable = Topic.create(title: 'Title', summary: 'Summary')
featureable.features.create
# => <Feature title: "Title", summary: "Summary">
```

You can also override them directly:

```ruby
featureable = Topic.create(title: 'Title', summary: 'Summary')
featureable.features.create(title: 'My New Title', summary 'My New Summary')
# => <Feature title: "My New Title", summary: "My New Summary">
```

The _position_ of the features can be specified:

```ruby
featureable = Topic.create
featureable.features.create(position: 3)
# => <Feature position: 3>
```

If it is not specified, it will automatically be assigned the next, lowest _position_:

```ruby
featureable = Topic.create
featureable.features.create
# => <Feature position: 1>

featureable.features.create
# => <Feature position: 2>
```

If you try and assign a position which has already been taken, it will find the next, lowest available _position_:

```ruby
featureable = Topic.create
featureable.features.create
# => <Feature position: 1>

featureable.features.create(position: 1)
# => <Feature position: 2>

featureable.features.create(position: 1)
# => <Feature position: 3>
```

### Categories

You can specify categories when creating features:

```ruby
featureable = Topic.create
featureable.features.create(category: :mains)
# => <Feature category: "mains">
```

You can specify any category and as many as you like to pull to different parts of your site.

```ruby
featureable = Topic.create
featureable.features.create(category: :mains)
# => <Feature category: "mains">
featureable.features.create(category: :hot_topics)
# => <Feature category: "hot_topics">

featureable.features.count
# => 2

featureable.features.where(category: :hot_topics).count
# => 1
```

This is the default behaviour. If you specify categories in your ```acts_as_featureable.rb``` initilaizer file:

```ruby
config.categories = [:mains, :hot_topics]
```

then these are the only allowable categories for your application. You also get the side benefit of 
having a scope created for each of these categories on the Feature class. See the next section for more details.

### Feature scope

Get all features ordered by thier _position_ ascending:

```ruby
Feature.ordered
```

If you have specified strict categories in your initializer (see previous section) then you can use those as scopes
on the Feature class:

```ruby
Feature.hot_topics
# => <Feature category: "hot_topics" ... >
```

## View Helpers

Adds two helper methods to your views:

```ruby
<%= feature_form_for(featureable) %>
```

Which renders a basic form for creating features from a featureable object.

```ruby
<%= features_for(featureable) %>
```

Which simiply lists the features' position and category with a delete link

## Contributing

1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request