If you are so inclined, donating to the project will help aid in its development
|  |  |
|:---:|:---:|
|  |  |
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 2.2+ 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.
[Discourse]: http://www.discourse.org/
## Installation
### Creating a new Rails app with Thredded
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.
```sh
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.
[thredded_create_app repo]: https://github.com/thredded/thredded_create_app
### Adding Thredded to an existing Rails app
Add the gem to your Gemfile:
```ruby
gem 'thredded', '~> 0.8.4'
```
Add the Thredded [initializer] to your parent app by running the install generator.
```console
rails generate thredded:install
```
Copy emoji images to your `public/emoji` directory.
```console
rake thredded:install:emoji
```
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:
```console
rake thredded:install:migrations db:migrate db:test:prepare
```
Mount the thredded engine in your routes file:
```ruby
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:
```ruby
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:
```console
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.4 to the v0.5):
```console
cp `bundle show thredded`/db/upgrade_migrations/20160501151908_upgrade_v0_4_to_v0_5.rb db/migrate
rake db:migrate
```
Note that for guaranteed best results you will want to run this with the gem checked out with v0.5.0.
### Migrating from Forem
Are you currently using [Forem]? Thredded provides [a migration][forem-to-thredded] to copy all of your existing data from Forem over
to Thredded.
[forem-to-thredded]: https://github.com/thredded/thredded/wiki/Migrate-from-Forem
[Forem]: https://github.com/rubysherpas/forem
## 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:
```bash
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 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):
#### Referencing your paths so that thredded views 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 either thredded or your app).
However if you don't want to update your layouts and partials, you can define methods automatically to delegate to the main_app's routes:
See https://gist.github.com/timdiggins/bf6d09b28828a392198562c93554ad07.
#### Pulling in thredded assets (styles and javascript)
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` (see below for customizing the styles):
```scss
@import "thredded";
```
Include thredded JavaScripts in your `application.js`:
```js
//= require thredded
```
To use thredded with your application layout, you also need to ensure that your layout and thredded don't load different
versions of jQuery. By default, Thredded loads jQuery v3 (via `//= require jquery3` from [jquery-rails]),
but if you want to use jQuery v1 or v2, then you need to create a file at
`app/assets/javascripts/thredded/dependencies/jquery.js` which contains just `//= require jquery`
or `// require jquery2`. If you are not loading jQuery in your app, or if you are already using jQuery v3, then you don't need to do do this (You also don't need to worry about this if you are using the default ["Standalone" layout](#standalone-layout))
[jquery-rails]: https://github.com/rails/jquery-rails
Thredded views also provide two `content_tag`s available to yield - `:thredded_page_title` and `:thredded_page_id`.
The views within Thredded pass those up through to your layout if you would like to use them.
### User profile page
Thredded does not provide a user's profile page, but it provides a partial for rendering the user's recent posts
in your app's user profile page. Here is how you can render it in your app:
```erb
<%= Thredded::ApplicationController.render partial: 'thredded/users/posts', locals: {
posts: Thredded.posts_page_view(scope: user.thredded_posts.order_newest_first.limit(5),
current_user: current_user) } %>
```
The `user` above is the user whose posts are rendered, and `current_user` is the user viewing the posts or `nil`.
The policy scopes that limit the posts to the ones `current_user` can see are applied automatically.
The code above uses the `ApplicationController.render` method introduced in Rails 5. If you're using Rails 4,
you will need to add the [`backport_new_renderer`](https://github.com/brainopia/backport_new_renderer) gem to use it.
### Customizing views
You can also override any views and assets by placing them in the same path in your application as they are in the gem.
This uses the [standard Rails mechanism](http://guides.rubyonrails.org/engines.html#overriding-views) for overriding
engine views. For example, to copy the post view for customization:
```bash
# Copy the post view into the application to customize it:
mkdir -p app/views/thredded/posts && cp "$(bundle show thredded)/$_/_post.html.erb" "$_"
```
**NB:** Overriding the views like this means that on every update of the thredded gem you have to check that your
customizations are still compatible with the new version of thredded. This is difficult and error-prone.
Whenever possible, use the styles and i18n to customize Thredded to your needs.
#### View hooks
Thredded provides view hooks to customize the UI before/after/replacing individual components.
View hooks allow you to render anything in the thredded view context.
For example, to render a partial after the post content textarea, add the snippet below to
the `config/initializers/thredded.rb` initializer:
```ruby
Rails.application.config.to_prepare do
Thredded.view_hooks.post_form.content_text_area.config.before do |form:, **args|
# This is render in the Thredded view context, so all Thredded helpers and URLs are accessible here directly.
render 'my/partial', form: form
end
end
```
You can use the post content textarea hook to add things like wysiwyg/wymean editors, buttons, help links, help copy,
further customization for the textarea, etc.
To see the complete list of view hooks and their arguments, run:
```bash
grep view_hooks -R --include '*.html.erb' "$(bundle show thredded)"
```
## Theming
The engine comes by default with a light and effective implementation of the
views, styles, and javascript. Once you mount the engine you will be presented
with a "themed" version of thredded.
### Styles
Thredded comes with a light Sass theme controlled by a handful of variables that can be found here:
https://github.com/thredded/thredded/blob/master/app/assets/stylesheets/thredded/base/_variables.scss.
To override the styles, override the variables *before* importing Thredded styles, e.g.:
```scss
// application.scss
$thredded-brand: #9c27b0;
@import "thredded";
```
The `@import "thredded"` directive above will import thredded styles and the [dependencies][thredded-scss-dependencies]
(currently just "select2" from [select2-rails]). If you already include your own styles for any of thredded
dependencies, you can import just the thredded styles alone like this:
```scss
// application.scss
@import "thredded/thredded";
```
If you are writing a Thredded plugin, import the [`thredded/base`][thredded-scss-base] Sass package instead.
The `base` package only defines variables, mixins, and %-placeholders, so it can be imported safely without producing
any duplicate CSS.
[thredded-scss-dependencies]: https://github.com/thredded/thredded/blob/master/app/assets/stylesheets/thredded/_dependencies.scss
[select2-rails]: https://github.com/argerim/select2-rails
[thredded-scss-base]: https://github.com/thredded/thredded/blob/master/app/assets/stylesheets/thredded/_base.scss
### Emails
Thredded sends several notification emails to the users. You can override in the same way as the views.
If you use [Rails Email Preview], you can include Thredded emails into the list of previews by adding
`Thredded::BaseMailerPreview.preview_classes` to the [Rails Email Preview] `preview_classes` config option.
[Rails Email Preview]: https://github.com/glebm/rails_email_preview
## I18n
Thredded is mostly internationalized. It is currently available in English and Brazilian Portuguese. We welcome PRs
adding support for new languages.
If you use thredded in languages other than English, you probably want to add `rails-i18n` to your Gemfile.
Additionally, you will need to require the translations for rails-timeago in you JavaScript,
e.g. for Brazilian Portuguese:
```js
//= require locales/jquery.timeago.pt-br
```
## Permissions
Thredded comes with a flexible permissions system that can be configured per messageboard/user.
It calls a handful of methods on the application `User` model to determine permissions for logged in users, and calls
the same methods on `Thredded:NullUser` to determine permissions for non-logged in users.
### Permission methods
The methods used by Thredded for determining the permissions are described below.
* To customize permissions for logged in users, override any of the methods below on your `User` model.
* To customize permissions for non-logged in users, override these methods on `Thredded::NullUser`.
#### Reading messageboards
1. A list of messageboards that a given user can read:
```ruby
# @return [ActiveRecord::Relation] messageboards that the user can read
thredded_can_read_messageboards
```
2. A list of users that can read a given list of messageboards:
```ruby
# @param messageboards [Array| Read | Post | Message | Moderate | Administrate | |
|---|---|---|---|---|---|
| Logged in | ✅ All | ✅ All |
Readers of the messageboards the user can post in |
moderator_column
|
admin_column
|
| Not logged in | ❌ No | ❌ No | ❌ No | ❌ No |