Formol

Formol is a Rails 3.1 forum engine until Rails 3.2 is out for good.

Why an engine?

Because I needed it. And because a forum is rarely a standalone app in a professional context.

In a near future, formol engine will be packaged in an independent and standalone application for those who need it.

Why writing a forum in rails?

Customers often ask for a forum inside their app. They think about phpBB or vBulletin like forum but it doesn't exist in rails. Developping one is really too expensive for a single project and:

  • bridge users between a phpBB and a rails app is very tricky (I just don't wanna try it).
  • phpBB / vBulletin is hard (or impossible) to embed into an application layout, especially a rails one.
  • Rails app and php forum won't share their sessions

Why don't use an existing solution?

Existing solutions are:

Beast has been inactive for 2 years. It's rails 2.2 and ruby 1.8. Don't need to say more.

Rails3-forums has been inactive for 8 months. It does less than formol after 1.5 weeks of development.

Forem is the most complete solution you can find in rails. Unfortunatly, it doesn't suit my needs.

In addition, I had to "come back" to ruby (was programming Java for 1.5 year) and I've never written an engine, never used rails 3.1 for a real project.

I decided then to write my own, with the best test coverage I can get (actually 99.3%).

Scaling

I do my best to think about everything that could make this engine scale for devils:

  • every non 'eager-loadable' association (like first and last on has_many) is heavily cached with belongs_to.
  • there's counters cache everywhere
  • I'll introduce caching (or try to in any case) for very high scaling when the app is stable.
  • I use a lot of indexes

Compatibility

Actually, formol is only tested with following parameters:

  • Ruby 1.9.2
  • Rails 3.1.3
  • Ubuntu
  • Mysql

When I would have read travis documentation, I'll test it on more platforms / db / rails versions (rails 3.2, ruby 1.9.3 & jruby, postgreSQL)

Installation

You can now install formol as a gem.

To install 0.0.4 (actual gem pushed)

#in your Gemfile

gem 'formol'

To install 0.0.5 (actual master revision)

#in your Gemfile

gem 'formol', :git => 'https://github.com/mulasse/formol'

then, execute rails g formol:install

You could have an issue saying that you're call method 'user class' on nil. That's because I load an observer in Formol::Engine. I have no solution against this at the moment. Every tip is welcome.

Once formol:install has run, you should do the following things:

  • run rake db:migrate
  • add <%= include_formol_javascripts %> and <%= include_formol_stylesheets %> in the head section of your application layout
  • add include Formol::Integration::User in your User model
  • add one or more text-formatter gems into your gemfile (actually, only 'formol-markdown')
  • edit initializer file and change config.text_formatter if you want something else than markdown

Formol expect your 'User' model to provide a method/property called display_name. If your model hasn't it already, create this method and return whatever you want (nickname, firstname + lastname ...)

If you want to use syntax-highlighting, add a stylesheet_link_tag with pygments/one_of_pyments_stylesheets as param in your application layout. You can find all pygments stylesheets in app/assets/pygments. This will be improved in the future.

Formol relies on jquery, jquery-ui and jquery_ujs. You should have them in your application.css or application layout.

Without jquery-ui, sort categories / forums and change forum's categories won't be available in admin.

NOTICE:

0.0.4 & 0.0.5 are unstable. Almost all functionalities are tested BUT application is not complete. You should not use Formol in production for now.

Features

  • Administration
    • categories
    • forums
  • Forums
    • mark all topics as read
  • Topics
    • locking topics
    • viewing all topics for a forum
    • creating new topics
    • pinning topics
    • tracking (read / unread by user)
    • subscriptions (with not scaling mailing)
    • polls & votes
  • Posts
    • replying to topics
    • deleting posts
    • editing posts
    • quoting
    • display user's signature
    • RTE
    • gravatars (based on User#email with default avatar)
    • avatars (bringed by your own)
  • Text formatting
    • markdown + syntax highlighting (gem 'formol-markdown')
  • User preferences
    • display signatures
    • display avatars
    • use signature by default
    • signature
  • User permissions
  • Misc
    • install generator
    • gemspec
    • basic style

Help on avatars

If you provide your own system of avatar storage, you'll need to provide avatar_url in your User model.

An example, with paperclip:

class User < ActiveRecord::Base
  has_attached_file :avatar, :styles => { :thumb => '100x100>' }

  def avatar_url
    avatar.url(:thumb)
  end
end

Formol works well with 100x100 avatars (according to basic style)

NOTICE: formol will look first for avatar_url, then for email and then fallback to default avatar

Preview

Find other screenshots in /previews

Topic content

Dependencies

At the moment, formol is independent from any auth system, but I still recommend Devise. Formol is highly coupled with will_paginate, you can't use it without will_paginate.

Maybe I'll change this with something more flexible in the future. It's not planned for the moment because I don't know other solutions than will_paginate.

Others:

Coming next

  • Soft delete topics (i'm not sure now since all tests failed because soft deletion doesn't trigger destroy callbacks)
  • Theme support
  • Generator (devise views)
  • Demo app
  • Selenium tests
  • More translations (french of course and more)
  • Permissions management (by admin)

Copyright 2011 Florian DUTEY

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.