Skip to content

Latest commit

 

History

History
229 lines (163 loc) · 6.79 KB

README.md

File metadata and controls

229 lines (163 loc) · 6.79 KB
Raw

Forem - using Bootstrap

Forem, using the forem-bootstrap theme

Forem Build status

"NO U!"

Forem is an engine for Rails that aims to be the best little forum system ever. The end goal is to have an engine that can be dropped into an application that provides the basic functionality of forums, topics and posts.

We are currently undergoing large changes. If you want to use this project, please keep this in mind. You can view a list of the intended changes on our Version 1.0 Roadmap

Demo

A demo application can be found at http://forem.heroku.com, and the source for this application can be found on the forem.heroku.com repository

Installation

Installing Forem is easy.

Specify Gem dependencies

If you're using Rails 3:

gem 'forem', :github => "radar/forem"

For Rails 4, use the rails4 branch:

gem 'forem', :github => "radar/forem", :branch => "rails4"

For Rails 4, you will also need to manually specify these dependencies:

gem 'friendly_id', github: "FriendlyId/friendly_id"
gem 'cancan', git: "https://github.com/nukturnal/cancan.git"

For all Rails versions, one of kaminari or will_paginate

gem 'kaminari', '0.14.1'
# OR
gem 'will_paginate', '3.0.4'

Run the installer

Ensure that you first of all have a User model and some sort of authentication system set up. We would recommend going with Devise, but it's up to you. All Forem needs is a model to link topics and posts to.

Run the installer and answer any questions that pop up. There's sensible defaults there if you don't want to answer them.

rails g forem:install

Set up helper methods in your user model

Forem depends on a to_s method being available on your User model so that it can display the user's name in posts. Define this in your model like this:

def to_s
  name
end

It also depends on an email method for displaying avatars using Gravatar. If you don't have an email attribute on the model, define a new method:

def email
  email_address
end

And you're done! Yaaay!

For more information on installing, please see the "Installation" wiki page

Features

Here's a comprehensive list of the features currently in Forem:

If there's a feature you think would be great to add to Forem, let us know on the Issues page

Auto Discovery Links

If you would like to add auto discovery links for the built in forum Atom feeds, then add the following method inside your <head> tag:

<%= forem_atom_auto_discovery_link_tag %>

View Customisation

If you want to customise Forem, you can copy over the views using the (Devise-inspired) forem:views generator:

rails g forem:views

You will then be able to edit the forem views inside the app/views/forem of your application. These views will take precedence over those in the engine.

Extending Classes

All of Forem’s business logic (models, controllers, helpers, etc) can easily be extended / overridden to meet your exact requirements using standard Ruby idioms.

Standard practice for including such changes in your application or extension is to create a directory app/decorators. place file within the relevant app/decorators/models or app/decorators/controllers directory with the original class name with _decorator appended.

Adding a custom method to the Post model:

# app/decorators/models/forem/post_decorator.rb

Forem::Post.class_eval do
  def some_method
    ...
  end
end

Adding a custom method to the PostsController:

# app/decorators/controllers/forem/posts_controller_decorator.rb

Forem::PostsController.class_eval do
  def some_action
    ...
  end
end

The exact same format can be used to redefine an existing method.

Translations

We currently have support for the following languages:

  • Brazillian (pt-BR)
  • Bulgarian
  • Chinese (Simplified, zh-CN)
  • Chinese (Traditional, zh-TW)
  • Dutch
  • English
  • Farsi (Persian)
  • German
  • Italian
  • Polish
  • Portuguese (pt-PT)
  • Russian
  • Spanish
  • Lithuanian
  • Japanese

Patches for new translations are very much welcome!

OMG BUG! / OMG FEATURE REQUEST!

File an issue and we'll get around to it when we can.

Developing on forem

Forem is implemented as a Rails engine and its specs are run in the context of a dummy Rails app. The process for getting the specs to run is similar to setting up a regular rails app:

bundle exec rake forem:dummy_app

Once this setup has been done, Forem's specs can be run by executing this command:

bundle exec rspec spec

More information can be found in this issue in the bugtracker.

If all the tests are passing (they usually are), then you're good to go! Develop a new feature for Forem and be lavished with praise!

Contributors

  • Ryan Bigg
  • Philip Arndt
  • Josh Adams
  • Adam McDonald
  • Zak Strassburg
  • And more

Places using Forem

If you want yours added here, just ask!