thredded 0.7.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a4599cfd4cc1a0446216da0bb6c5bfcb19ad857d
-  data.tar.gz: 24286dd248ea8aa78737a5ee708ae3af0b2d0ad0
+  metadata.gz: 0b5134ae28a842aa241f4de392cd1679bb84d8d3
+  data.tar.gz: 8481a216ec08609350f19c86d9b88a2f1560d857
 SHA512:
-  metadata.gz: 0019fe0f00970082f29c57572ff07968de460d2a0cb9d8ab2590a668ef68a954078ac41f5d64a1e0125c4f6d0aabfd4a7465a96dae5685e0ce65f1b9cd0a8796
-  data.tar.gz: e4fb202dee30cad34b4cc8ced571cd0c6968c7ab5989b7e4d7722916fe4eb382e9e0abaa7ef237ebad6e32c546f6bf315fa6853daa6da8647101f4061f6a5e06
+  metadata.gz: 2c039dfafa5e1b3e890694fd77581e1eb4795f3c5503c3ac4f41120e9c8398e551c04a3bde6b2d007aa2f636ca0315debeb71c91cd9e5cba61c06743de4f2199
+  data.tar.gz: a8fac9025ad895c6003513807d4e4d246d50b4c5ae3f5f414823b69e9673ea1e4c578e362bbf2d67d6f69de9cbc76ade42d493ddae931cfc39df9cfeed518392

data/README.md

@@ -1,10 +1,10 @@
-# Thredded [![Code Climate](https://codeclimate.com/github/thredded/thredded/badges/gpa.svg)](https://codeclimate.com/github/thredded/thredded) [![Travis-CI](https://api.travis-ci.org/thredded/thredded.svg?branch=master)](https://travis-ci.org/thredded/thredded/) [![Test Coverage](https://codeclimate.com/github/thredded/thredded/badges/coverage.svg)](https://codeclimate.com/github/thredded/thredded/coverage) [![Gitter](https://badges.gitter.im/thredded/thredded.svg)](https://gitter.im/thredded/thredded?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Stories in Ready](https://badge.waffle.io/thredded/thredded.svg?label=ready&title=waffle.io)](http://waffle.io/thredded/thredded)
+# Thredded [![Code Climate](https://codeclimate.com/github/thredded/thredded/badges/gpa.svg)](https://codeclimate.com/github/thredded/thredded) [![Travis-CI](https://api.travis-ci.org/thredded/thredded.svg?branch=master)](https://travis-ci.org/thredded/thredded/) [![Test Coverage](https://codeclimate.com/github/thredded/thredded/badges/coverage.svg)](https://codeclimate.com/github/thredded/thredded/coverage) [![Inline docs](http://inch-ci.org/github/thredded/thredded.svg?branch=master)](http://inch-ci.org/github/thredded/thredded) [![Gitter](https://badges.gitter.im/thredded/thredded.svg)](https://gitter.im/thredded/thredded?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
 _Thredded_ is a Rails 4.2+ forum/messageboard engine. Its goal is to be as simple and feature rich as possible.
 
 Some of the features currently in Thredded:
 
-* Markdown post formatting with some BBCode support (by default).
+* Markdown (default) or BBCode post formatting.
 * (Un)read posts tracking.
 * Email notifications, topic subscriptions, @-mentions, per-messageboard notification settings.
 * Private group messaging.
@@ -41,10 +41,28 @@ application and not an engine like Thredded.
 
 ## 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.7.0'
+gem 'thredded', '~> 0.8.2'
 ```
 
 Add the Thredded [initializer] to your parent app by running the install generator.
@@ -114,14 +132,14 @@ to Thredded.
 
 ### Standalone layout
 
-By default, thredded renders in its own 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 the app:
+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" "$_"
@@ -129,7 +147,19 @@ mkdir -p app/views/thredded/shared/nav && cp "$(bundle show thredded)/$_/_standa
 
 ### Application layout
 
-You can also use Thredded with the application layout by by setting `Thredded.layout` in the initializer.
+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.
 
@@ -145,6 +175,14 @@ Include thredded JavaScripts in your `application.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.
 
@@ -180,17 +218,31 @@ mkdir -p app/views/thredded/posts && cp "$(bundle show thredded)/$_/_post.html.e
 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.
 
-#### Empty view partials included for customization
+#### View hooks
+
+Thredded provides view hooks to customize the UI before/after/replacing individual components.
 
-There are 2 empty view partials included in the gem that exist for the purpose of being overridden
-in the parent app *if desired*. They are:
+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:
 
-* `app/views/thredded/posts_common/form/_before_content.html.erb`
-* `app/views/thredded/posts_common/form/_after_content.html.erb`
+```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.
 
-And are rendered directly before, and directly after the textarea where users type their post
-contents. These exist in the case where a messageboard would like 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
 
@@ -442,11 +494,61 @@ rake dev:server
 To run the tests, just run `rspec`. The test suite will re-create the test database on every run, so there is no need to
 run tasks that maintain the test database.
 
-Run `rubocop` to ensure a consistent code style across the codebase.
-
-By default, SQLite is used in development and test. On Travis, the tests will run using SQLite, PostgreSQL, SQLite,
+By default, SQLite is used in development and test. On Travis, the tests will run using SQLite, PostgreSQL, MySQL,
 and all the supported Rails versions.
 
+### Ruby
+
+Thredded Ruby code formatting is ensured by [Rubocop](https://github.com/bbatsov/rubocop). Run `rubocop -a` to ensure a
+consistent code style across the codebase.
+
+Thredded is documented with [YARD](http://yardoc.org/) and you can use the
+[inch gem](https://github.com/rrrene/inch) or the [Inch CI](http://inch-ci.org/github/thredded/thredded) to find code
+that lacks documentation.
+
+### JavaScript
+
+Currently, Thredded JavaScript is written in the subset of ES6 that does not
+require Babel polyfills. We're waiting for the ES6/7 support on Rails to improve
+before updating this to full Babel.
+
+All Thredded JavaScript is compatible with the following Turbolinks options:
+
+* No Turbolinks.
+* Tubrolinks 5.
+* Turbolinks Classic.
+* Turbolinks Classic + jquery-turbolinks.
+
+Thredded JavaScript is also compatible with being loaded from script elements with
+`[async]` and/or `[defer]` attributes.
+
+To achieve the above, all the Thredded code must register onload via
+`Thredded.onPageLoad`, e.g.:
+
+```js
+window.Thredded.onPageLoad(() => {
+  // Initialize widgets:
+  $('[data-thredded-select2]').select2();
+});
+```
+
+Additionally, all the thredded views must be wrapped in a `<%= thredded_page do %>` block.
+
+On Turbolinks 5 onPageLoad will run on the same DOM when the page is restored
+from history (because Turbolinks 5 caches a *clone* of the body node, so
+the events are lost).
+
+This means that all DOM modifications on `window.Thredded.onPageLoad` must be
+idempotent, or they must be reverted on the `turbolinks:before-cache` event,
+e.g.:
+
+```js
+document.addEventListener('turbolinks:before-cache', () => {
+  // Destroy widgets:
+  $('[data-thredded-select2]').select2('destroy');
+});
+```
+
 ### Testing with all the databases and Rails versions locally.
 
 You can also test the gem with all the supported databases and Rails versions locally.

data/app/assets/javascripts/thredded/components/currently_online.es6

@@ -1,4 +1,4 @@
-(function($) {
+(($) => {
   const COMPONENT_SELECTOR = '[data-thredded-currently-online]';
 
   class ThreddedCurrentlyOnline {
@@ -16,8 +16,8 @@
     }
   }
 
-  $(function() {
-    var $nodes = $(COMPONENT_SELECTOR);
+  window.Thredded.onPageLoad(() => {
+    const $nodes = $(COMPONENT_SELECTOR);
     if ($nodes.length) {
       new ThreddedCurrentlyOnline().init($nodes);
     }

data/app/assets/javascripts/thredded/components/flash_messages.es6

@@ -0,0 +1,11 @@
+(($) => {
+  const COMPONENT_SELECTOR = '[data-thredded-flash-message]';
+
+  const destroy = () => {
+    $(COMPONENT_SELECTOR).remove();
+  };
+
+  document.addEventListener('turbolinks:before-cache', () => {
+    destroy()
+  });
+})(jQuery);

data/app/assets/javascripts/thredded/components/post_form.es6

@@ -1,4 +1,4 @@
-(function($) {
+(($) => {
   const COMPONENT_SELECTOR = '[data-thredded-post-form]';
 
   class ThreddedPostForm {
@@ -7,14 +7,31 @@
     }
 
     init($nodes) {
-      $nodes.find(this.textareaSelector).autosize();
+      let $textarea = $nodes.find(this.textareaSelector);
+      this.autosize($textarea);
+      new ThreddedMentionAutocompletion($).init($nodes);
+    }
+
+    autosize($textarea) {
+      $textarea.autosize()
+    }
+
+    destroy($nodes) {
+      $nodes.find(this.textareaSelector).trigger('autosize.destroy');
     }
   }
 
-  $(function() {
-    var $nodes = $(COMPONENT_SELECTOR);
+  window.Thredded.onPageLoad(() => {
+    const $nodes = $(COMPONENT_SELECTOR);
     if ($nodes.length) {
       new ThreddedPostForm().init($nodes);
     }
   });
+
+  document.addEventListener('turbolinks:before-cache', () => {
+    const $nodes = $(COMPONENT_SELECTOR);
+    if ($nodes.length) {
+      new ThreddedPostForm().destroy($nodes);
+    }
+  });
 })(jQuery);

data/app/assets/javascripts/thredded/components/time_stamps.es6

@@ -1,8 +1,10 @@
-jQuery(function($) {
+(($) => {
   const COMPONENT_SELECTOR = '#thredded--container abbr.timeago';
 
-  var allowFutureWas = jQuery.timeago.settings.allowFuture;
-  $.timeago.settings.allowFuture = true;
-  $(COMPONENT_SELECTOR).timeago();
-  $.timeago.settings.allowFuture = allowFutureWas;
-});
+  window.Thredded.onPageLoad(() => {
+    const allowFutureWas = jQuery.timeago.settings.allowFuture;
+    $.timeago.settings.allowFuture = true;
+    $(COMPONENT_SELECTOR).timeago();
+    $.timeago.settings.allowFuture = allowFutureWas;
+  });
+})(jQuery);

data/app/assets/javascripts/thredded/components/topic_form.es6

@@ -1,4 +1,4 @@
-(function($) {
+(($) => {
   const COMPONENT_SELECTOR = '[data-thredded-topic-form]';
   class ThreddedTopicForm {
     constructor() {
@@ -16,6 +16,7 @@
 
     init($nodes) {
       $nodes.find(this.textareaSelector).autosize();
+      new ThreddedMentionAutocompletion($).init($nodes);
       $nodes.filter(this.compactSelector).
         on('focus', this.titleSelector, e => {
           this.toggleExpanded(e.target, true);
@@ -42,14 +43,24 @@
         });
     }
 
+    destroy($nodes) {
+      $nodes.find(this.textareaSelector).trigger('autosize.destroy');
+    }
   }
 
-  $(function() {
-    var $nodes = $(COMPONENT_SELECTOR);
+  window.Thredded.onPageLoad(() => {
+    const $nodes = $(COMPONENT_SELECTOR);
     if ($nodes.length) {
       new ThreddedTopicForm().init($nodes);
     }
   });
+
+  document.addEventListener('turbolinks:before-cache', () => {
+    const $nodes = $(COMPONENT_SELECTOR);
+    if ($nodes.length) {
+      new ThreddedTopicForm().destroy($nodes);
+    }
+  });
 })(jQuery);
 
 

data/app/assets/javascripts/thredded/components/topics.es6

@@ -1,4 +1,4 @@
-(function($) {
+(($) => {
   const COMPONENT_SELECTOR = '[data-thredded-topics]';
 
   const TOPIC_SELECTOR = 'article';
@@ -28,8 +28,8 @@
     }
   }
 
-  $(function() {
-    var $nodes = $(COMPONENT_SELECTOR);
+  window.Thredded.onPageLoad(() => {
+    const $nodes = $(COMPONENT_SELECTOR);
     if ($nodes.length) {
       new ThreddedTopics().init($nodes);
     }

data/app/assets/javascripts/thredded/components/turboforms.es6

@@ -0,0 +1,15 @@
+// Submit GET forms with turbolinks
+(function($) {
+  if (window.Turbolinks && window.Turbolinks.supported) {
+    window.Thredded.onPageLoad(() => {
+      $('[data-thredded-turboform]').on('submit', function(evt) {
+        evt.preventDefault();
+        Turbolinks.visit(this.action + (this.action.indexOf('?') === -1 ? '?' : '&') + $(this).serialize());
+
+        // On mobile the soft keyboard doesn't won't go away after the submit since we're submitting with
+        // Turbolinks. Hide it:
+        window.Thredded.hideSoftKeyboard();
+      });
+    });
+  }
+})(jQuery);

data/app/assets/javascripts/thredded/components/user_preferences_form.es6

@@ -1,40 +1,67 @@
-(function($) {
+(($) => {
   const COMPONENT_SELECTOR = '[data-thredded-user-preferences-form]';
-  const NOTIFY_ON_MENTION_SELECTOR = ':checkbox[name="user_preferences_form[notify_on_mention]"]';
-  const MESSAGEBOARD_NOTIFY_ON_MENTION_SELECTOR = '[name="user_preferences_form[messageboard_notify_on_mention]"]';
+  const FOLLOW_TOPICS_ON_MENTION_SELECTOR = ':checkbox[name="user_preferences_form[follow_topics_on_mention]"]';
+  const MESSAGEBOARD_FOLLOW_TOPICS_ON_MENTION_SELECTOR = '[name="user_preferences_form[messageboard_follow_topics_on_mention]"]';
+  const FOLLOWED_TOPIC_EMAILS_SELECTOR = ':checkbox[name="user_preferences_form[followed_topic_emails]"]';
+  const MESSAGEBOARD_FOLLOWED_TOPIC_EMAILS_SELECTOR = ':checkbox[name="user_preferences_form[messageboard_followed_topic_emails]"]';
 
   class UserPreferencesForm {
     constructor(form) {
       this.$form = $(form);
-      this.$notifyOnMention = this.$form.find(NOTIFY_ON_MENTION_SELECTOR);
-      this.$messageboardNotifyOnMention = this.$form.find(MESSAGEBOARD_NOTIFY_ON_MENTION_SELECTOR);
+      this.$followTopicsOnMention = this.$form.find(FOLLOW_TOPICS_ON_MENTION_SELECTOR);
+      this.$messageboardFollowTopicsOnMention = this.$form.find(MESSAGEBOARD_FOLLOW_TOPICS_ON_MENTION_SELECTOR);
+      this.$followedTopicEmails = this.$form.find(FOLLOWED_TOPIC_EMAILS_SELECTOR);
+      this.$messageboardFollowedTopicEmails = this.$form.find(MESSAGEBOARD_FOLLOWED_TOPIC_EMAILS_SELECTOR);
 
-      this.messageboardNotifyOnMentionCheckedWas = this.$messageboardNotifyOnMention.prop('checked');
-      this.$messageboardNotifyOnMention.on('change', () => {
-        this.rememberMessageboardNotifyOnMentionChecked();
+      this.messageboardFollowTopicsOnMentionCheckedWas = this.$messageboardFollowTopicsOnMention.prop('checked');
+      this.$messageboardFollowTopicsOnMention.on('change', () => {
+        this.rememberMessageboardAutofollowTopicsChecked();
       });
-      this.rememberMessageboardNotifyOnMentionChecked();
+      this.rememberMessageboardAutofollowTopicsChecked();
 
-      this.$notifyOnMention.on('change', () => {
-        this.updateMessageboardNotifyOnMention();
+      this.$followTopicsOnMention.on('change', () => {
+        this.updateMessageboardAutofollowTopics();
       });
-      this.updateMessageboardNotifyOnMention();
+      this.updateMessageboardAutofollowTopics();
+
+      this.messageboardFollowedTopicEmailsCheckedWas = this.$messageboardFollowedTopicEmails.prop('checked');
+      this.$messageboardFollowedTopicEmails.on('change', () => {
+        this.rememberMessageboardFollowedTopicEmailsChecked();
+      });
+      this.rememberMessageboardFollowedTopicEmailsChecked();
+
+      this.$followedTopicEmails.on('change', () => {
+        this.updateMessageboardFollowedTopicEmails();
+      });
+      this.updateMessageboardFollowedTopicEmails();
+    }
+
+    rememberMessageboardAutofollowTopicsChecked() {
+      this.messageboardFollowTopicsOnMentionCheckedWas =
+        this.$messageboardFollowTopicsOnMention.filter(':checkbox').prop('checked');
+    }
+
+    updateMessageboardAutofollowTopics() {
+      const enabled = this.$followTopicsOnMention.prop('checked');
+      this.$messageboardFollowTopicsOnMention
+        .prop('disabled', !enabled)
+        .filter(':checkbox').prop('checked', enabled ? this.messageboardFollowTopicsOnMentionCheckedWas : false);
     }
 
-    rememberMessageboardNotifyOnMentionChecked() {
-      this.messageboardNotifyOnMentionCheckedWas =
-        this.$messageboardNotifyOnMention.filter(':checkbox').prop('checked');
+    rememberMessageboardFollowedTopicEmailsChecked() {
+      this.messageboardFollowedTopicEmailsCheckedWas =
+        this.$messageboardFollowedTopicEmails.filter(':checkbox').prop('checked');
     }
 
-    updateMessageboardNotifyOnMention() {
-      const enabled = this.$notifyOnMention.prop('checked');
-      this.$messageboardNotifyOnMention
+    updateMessageboardFollowedTopicEmails() {
+      const enabled = this.$followedTopicEmails.prop('checked');
+      this.$messageboardFollowedTopicEmails
         .prop('disabled', !enabled)
-        .filter(':checkbox').prop('checked', enabled ? this.messageboardNotifyOnMentionCheckedWas : false);
+        .filter(':checkbox').prop('checked', enabled ? this.messageboardFollowedTopicEmailsCheckedWas : false);
     }
   }
 
-  $(function() {
+  window.Thredded.onPageLoad(() => {
     const $forms = $(COMPONENT_SELECTOR);
     if ($forms.length) {
       $forms.each(function() {