= Adhocracy {<img src="https://badge.fury.io/rb/adhocracy.png" alt="Gem Version" />}[http://badge.fury.io/rb/adhocracy] {<img src="https://travis-ci.org/timothycommoner/adhocracy.png?branch=master" alt="Build Status" />}[https://travis-ci.org/timothycommoner/adhocracy] {<img src="https://coveralls.io/repos/timothycommoner/adhocracy/badge.png" alt="Coverage Status" />}[https://coveralls.io/r/timothycommoner/adhocracy] {<img src="https://codeclimate.com/github/timothycommoner/adhocracy.png" />}[https://codeclimate.com/github/timothycommoner/adhocracy]

A group management engine for Rails.

== Compatibility

Adhocracy is a Rails Engine, which means it plays best with Rails applications. So far, it's only been tested with Rails 4.

== Usage

=== Installation

1. Add Adhocracy to your gemfile: `gem 'adhocracy'`
2. Run bundler: `bundle install`
3. Run this in your app folder: `rake adhocracy:install:migrations`
4. Run your migrations: `rake db:migrate`
5. Add `acts_as_group` to the models you want to have group functionality
6. Add `acts_as_member` to the models you want to have member functionality

=== Creating Groups and Members

Scenario: You want your Club model to have group functionality. Ideally, it'll accept members from both the Student and Teacher model.

First, add `acts_as_group` to your Club model:

    class Club < ActiveRecord::Base
      acts_as_group
    end

Then, add 'acts_as_member' to your Student and Teacher models:

    class Student < ActiveRecord::Base
      acts_as_member
    end

    class Teacher < ActiveRecord::Base
      acts_as_member
    end

After that, you can add members to your Club by:

    @club.add_member(@student)
    @student.join_group(@club)
    @teacher.join_group(@club)

List the current members:

    @club.members # => returns an array with @student and @teacher in it

Or list the groups a member is a part of:

    @student.groups # => returns an array with only @club

Check for membership:

    @student.member_of?(@club) # => true
    @club.has_member?(@teacher) # => true

And destroy memberships

    @student.leave_group(@club)
    @group.remove_member(@teacher)

=== Officers

Scenario: You want a special class of membership that has the privilege to edit the group and accept/invite new members.

Adhocracy allows for administrative members called officers. You can create a new officer with:

    @club.add_officer(@student)
    # or
    @student.promote(@club)

Later, you can strip an officer of her title with:

    @club.demote_officer(@student)
    # or
    @student.demote(@club)

You can check if a member is an officer with:

    @club.has_officer?(@member)
    # or
    @member.officer_of?(@club)

Or get a full list of officers:

    @club.officers
    # or of administered groups
    @member.administrations

=== Inviting Members

Scenario: You want your users to have control over which groups they join.

Groups can send invitations to users:

    @club.invite_member(@student)
    @student.groups # => does not yet include @club
    @student.group_invitations # => array including @club

The user can either accept or decline:

    @invitation = @student.membership_invitations.first
    @invitation.accept
    - or -
    @invitation.decline

If they accept, then they become a member of the group.

Invitations can be queried for their state of acceptance:

    @invitation.pending?
    @invitation.accepted?
    @invitation.declined?

You can also check to see if an invitation is already sent:

    @student.invited_to?(@club)
    @club.invited?(@student)

These checks can include the state of the invitation:

    @student.invited_to?(@club, { pending: true })
    @student.invited_to?(@club, { accepted: false })
    @student.invited_to?(@club, { declined: false })

=== Requesting Membership

Scenario: You want your groups to have control over which users join them.

Interested users can send membership requests to groups:

    @student.request_membership_in(@club)
    @club.members # => does not yet include @student
    @club.membership_requests # => array including @student

The group can either accept or decline:

    @request = @club.membership_requests.first
    @request.accept
    - or -
    @request.decline

Requests can be queried for their state of acceptance:

    @request.pending?
    @request.accepted?
    @request.declined?

You can also check to see if a request is already sent:

    @student.requested_membership_in?(@club)
    @club.recieved_request_from?(@student)

These checks can include the state of the request:

    @student.requested_membership_in?(@club, { pending: true })
    @student.requested_membership_in?(@club, { accepted: false })
    @student.requested_membership_in?(@club, { declined: false })

=== Nesting Groups

Scenario: You want your Company model to have many subsidiary companies.

Create a model that both `acts_as_group` and `acts_as_member`:

    class Company < ActiveRecord::Base
      acts_as_group
      acts_as_member
    end

You can then nest companies like you would any other member:

    @company.add_member(@child_company)
    @child_company.add_member(@grand_child_company)

== Limitations

Unfortunately, Rails does not support `has_many through` relationships that pass through a polymorphic join table, which we do in Adhocracy. In order to work around this limitation, we've created pseudo-associations, such as `@club.members` and `@user.groups`. These pseudo-associations return a simple array, rather than the feature-packed associations Rails typically uses. This means you can't chain in scopes or use commands like `@user.groups.create`. If you know of a way we can reincorporate Rails associations without losing our ability to join groups and members polymorphically, please share your thoughts!

== Issues

Adhocracy is still very young, and both its functionality and its documentation are bound to be lacking. If you're having trouble with something, feel free to open an issue.

== Contributing

Feel free to send us a pull request. Public methods, callbacks, and validations should have Rspec tests to back them up.

=== Contributors

Timothy Baron

== License

Released under the MIT license.