Thredded

Thredded is a Rails forum/messageboard engine. Its goal is to be as simple and feature rich as possible.

Some of the features currently in Thredded:

• Markdown (default) and / or BBCode post formatting, with onebox and <spoiler> / [spoiler] tag support.
• (Un)read posts tracking.
• Email notifications, topic subscriptions, @-mentions, per-messageboard notification settings.
• Private group messaging.
• Full-text search using the database.
• Pinned and locked topics.
• List of currently online users, for all forums and per-messageboard.
• Flexible permissions system.
• Basic moderation.
• Lightweight default theme configurable via Sass.

| | | |:---:|:---:| | | |

Thredded works with SQLite, MySQL (v5.6.4+), and PostgreSQL. Thredded has no infrastructure dependencies other than the database and, if configured in the parent application, the ActiveJob backend dependency such as Redis. Currently only MRI Ruby 3.1+ is supported. We would love to support JRuby and Rubinius as well.

If you're looking for variations on a theme - see Discourse. However, it is a full rails application and not an engine like Thredded.

Table of Contents

• Installation
  • Creating a new Rails app with Thredded
  • Adding Thredded to an existing Rails app
  • Upgrading an existing install
  • Migrating from Forem
• Rails compatibility
• Views and other assets
  • Standalone layout
  • Application layout
    • Reference your paths so that Thredded can find them
    • Add Thredded styles
    • Add Thredded JavaScripts (Sprockets)
    • Add Thredded JavaScripts (Webpack)
  • User profile page
  • Customizing views
    • View hooks
  • Theming
    • Styles
• Email and other notifications
  • Enabling auto-follow
• I18n
• Permissions
  • Permission methods
    • Reading messageboards
    • Posting to messageboards
    • Messaging other users (posting to private topics)
    • Moderating messageboards
    • Admin permissions
  • Default permissions
  • Handling "Permission denied" and "Not found" errors
• Moderation
  • Disabling moderation
• Plugins
• Development
  • Testing
  • Ruby
  • JavaScript
  • Testing with all the databases and Rails versions locally.
  • Developing and Testing with Docker Compose

Installation

Creating a new Rails app with Thredded

[!CAUTION] Please add thredded_create_app is currently out of date and needs contributors to fix it - it won't work with the latest thredded. See https://github.com/thredded/thredded_create_app if you can contribute.

<details> <summary> View the outdated instructions </summary>

Thredded provides an app generator that will generate a Rails app with Thredded, Devise, SimpleForm, RSpec, PostgreSQL, and a basic theme and navigation that is configured to work out of the box.

gem install thredded_create_app
thredded_create_app path/to/myapp

See thredded_create_app --help and the thredded_create_app repo to learn about the various options.

Then, see the rest of this Readme for more information about using and customizing Thredded.

</details>

Adding Thredded to an existing Rails app

Add the gem to your Gemfile:

gem 'thredded', '~> 1.2'

Add the Thredded [initializer] to your parent app by running the install generator.

rails generate thredded:install

Thredded needs to know the base application User model name and certain columns on it. Configure these in the initializer installed with the command above.

Then, copy the migrations over to your parent application and migrate:

rake thredded:install:migrations db:migrate db:test:prepare

Mount the thredded engine in your routes file:

mount Thredded::Engine => '/forum'

You also may want to add an index to the user name column in your users table. Thredded uses it to find @-mentions and perform name prefix autocompletion on the private topic form. Add the index in a migration like so:

DbTextSearch::CaseInsensitive.add_index(
    connection, Thredded.user_class.table_name, Thredded.user_name_column, unique: true)

Upgrading an existing install

1. To upgrade the initializer:

rails g thredded:install

But then compare this with the previous version to decide what to keep.

2. To upgrade the database (in this example from v0.11 to v0.12):

# Note that for guaranteed best results you will want to run this with the thredded gem at v0.12
cp "$(bundle show thredded)"/db/upgrade_migrations/20170420163138_upgrade_thredded_v0_11_to_v0_12.rb db/migrate
rake db:migrate

Migrating from Forem

Are you currently using Forem? Thredded provides a migration to copy all of your existing data from Forem over to Thredded.

Rails compatibility

| Rails | JS frameworks | Latest Thredded | |-----------------------|-------------------------------------------|------------------| | Rails 7.2 - Rails 8.1 | Turbo | Thredded 2.0 | | Rails 7.0 - Rails 8.0 | rails-ujs , jquery-ujs, and/or Turbolinks | Thredded 1.2 | | Rails 6.0 - rails 6.1 | rails-ujs , jquery-ujs, and/or Turbolinks | Thredded 1.1 | | Rails 5.2 | rails-ujs , jquery-ujs, and/or Turbolinks | Thredded 1.0.1 | | Rails 4.2 | rails-ujs , jquery-ujs, and/or Turbolinks | Thredded 0.16.16 |

Views and other assets

Standalone layout

By default, thredded renders in its own (standalone) layout.

When using the standalone thredded layout, the log in / sign out links will be rendered in the navigation. For these links (and only for these links), Thredded makes the assumption that you are using devise as your auth library. If you are using something different you need to override the partial at app/views/thredded/shared/nav/_standalone.html.erb and use the appropriate log in / sign out path URL helpers.

You can override the partial by copying it into your app:

mkdir -p app/views/thredded/shared/nav && cp "$(bundle show thredded)/$_/_standalone.html.erb" "$_"

Application layout

You can also use Thredded with your application (or other) layout by setting Thredded.layout in the initializer.

In this case, you will need to reference your paths/routes carefully and pull in thredded assets (styles and javascript):

Reference your paths so that Thredded can find them

In your layout you will probably have links to other paths in your app (e.g. navigation links). For any url helpers (like users_path or projects_path or whatever) will need to have main_app. prefixed to them so that they can be found from thredded (main_app.users_path will work from both thredded and your app).

Add Thredded styles

In this case, you will also need to include Thredded styles and JavaScript into the application styles and JavaScript.

Add thredded styles to your application.scss:

@import "thredded";

Thredded wraps the views in a container element that has a max-width and paddings by default. If your app layout already has a container element that handles these, you can remove the max-width and paddings from the Thredded one by adding this Sass snippet after @import "thredded";:

.thredded--main-container {
  // The padding and max-width are handled by the app's container.
  max-w