wiki:DiscussionPlugin

Version 76 (modified by Blackhex, 4 years ago) (diff)

--

Discussion Forum Plugin

Description

The DiscussionPlugin adds discussion forums to Trac. An arbitrary number of forums can be added, organized to forum groups. Users can create topics in forums and reply to them which together creates discussion threads. Threaded or flat view to topics and its replies is supported. Each forum has a list of moderators who can delete topics, replies, etc. Plugin is administrated directly or via Trac administration interface with appropriate rights. Appending new forums and topics either as new replies shows up in timeline. Searching capability in topics and replies is supported too.

Live Example

To get an idea how the forums look, see BlackTrac discussion.

Donations

If you want to support plugin's development, you can donate some small amount via PaySec or PayPal (PaySec prefered). If you specify particular feature, you want to support, in the note field, the donation will be used to develop that feature.

Any donation will be gratefully welcomed.

Bugs/Feature Requests

Existing bugs and feature requests for DiscussionPlugin are here.

If you have any issues, create a new ticket but read BugReporting page first, please.

Download and Source

You can download zipped sources, check out using Subversion, or browse the source with Trac.

Dependencies

If you need spam filtering feature working, the SpamFilterPlugin installation is required. In other cases, disable a DiscussionSpamFilter component. On older Trac versions, the DiscussionPlugin depends on a WebAdminPlugin since many configuration options are available only on appropriate WebAdminPlugin's pages. Since Trac 0.10, the WebAdminPlugin is internal part of the Trac.

Plugin Versions

As many other plugins in this site even this plugin names its branches according to Trac versions. Here is a simple table explaining this convention for DiscussionPlugin:

Plugin Branch Trac Branch Plugin Version
0.9 0.9-stable 0.5
0.10 0.10-stable 0.5
0.11 0.11-stable, 0.12-stable 0.6, 0.7

Main difference between 0.5 and 0.6 version is that 0.6 uses Genshi templates and 0.5 ClearSilver ones.

Installation

For general information about Trac plugins installation see TracPlugins. Plugin is configurable from trac.ini file, see TracIni for more on this topic. The following variables controls DiscussionPlugin's behavior:

[discussion]
title = Discussion
default_topic_display = classic
default_message_display = tree
forum_sort = lasttopic
forum_sort_direction = asc
topic_sort = lastreply
topic_sort_direction = asc
topics_per_page = 30
messages_per_page = 50
smtp_always_cc = 

Option title changes title of main navigation bar button, default_topic_display changes between two possible displays of topic list - the classic and the compact view. default_message_display defines default display mode for message list. Possible values are tree, flat, flat-asc and flat-desc. flat is synonym for flat-desc. forum_sort is column by which will be sorted forum lists. Possible values are: id, group, name, subject, time, moderators, description, topics, replies, lasttopic and lastreply. Topic lists may be sorted with topic_sort option. It has values id, forum, subject, time, author, body, replies and lastreply. Options forum_sort_direction and topic_sort_direction are directions of that sorting. They may be asc and desc. topics_per_page and messages_per_page options controlls number of items displayed in topic and message lists at each page of pagination. You can type list of e-mail addresses into smtp_always_cc option to send all discussion plugin e-mail notification to them. Previous example shows default values for these options.

If you run Trac in environment which needs to enable plugins explicitly put in trac.ini these lines:

[components]
tracdiscussion.admin.DiscussionWebAdmin = enabled
tracdiscussion.api.DiscussionApi = enabled
tracdiscussion.core.DiscussionCore = enabled
tracdiscussion.init.DiscussionInit = enabled
tracdiscussion.notification.DiscussionNotifyEmail = enabled
tracdiscussion.search.DiscussionSearch = enabled
tracdiscussion.spamfilter.DiscussionSpamFilter = enabled # Optional, disable if you don't have SpamFilterPlugin.
tracdiscussion.timeline.DiscussionTimeline = enabled
tracdiscussion.wiki.DiscussionWiki = enabled

The next step is to upgrade your environment:

# trac-admin <path_to_environment> upgrade

For now sqlite version 3 or PostgreSQL is required as SQL backend for running this plugin.

Permissions

Discussion plugin defines five permissions. With DISCUSSION_VIEW permission you can view all topics and you can post replies to them with DISCUSSION_APPEND permission. Attachments can be added to the topics with DISCUSSION_ATTACH permission. DISCUSSION_MODERATE permission gives you rights to delete replies or topics where are you defined as moderator. DISCUSSION_ADMIN permission gives you administrator rights to create, modify or delete forum groups, forums and topics. You can add these permissions by typing following commands from commandline or you can use web administration interface to do it for you.

# trac-admin <path_to_environment> permission add <user> DISCUSSION_VIEW
# trac-admin <path_to_environment> permission add <user> DISCUSSION_APPEND
# trac-admin <path_to_environment> permission add <user> DISCUSSION_ATTACH
# trac-admin <path_to_environment> permission add <user> DISCUSSION_MODERATE
# trac-admin <path_to_environment> permission add <user> DISCUSSION_ADMIN

Macros

There are few wiki macros available:

[forum:<forum_id> <text>]

Displays a link to forum with id <id> and text <text>. Second argument is optional.

[topic:<topic_id> <text>]

Displays a link to topic with id <id> and text <text>. Second argument is optional.

[message:<message_id> <text>]

Displays a link to reply with id <id> and text <text>. Second argument is optional.

[last-forum:<forum_group_id> <text>]

Displays a link to the last forum created in forum group with id <id> and text <text>. Second argument is optional.

[last-topic:<forum_id> <text>]

Displays a link to the last topic created in forum with id <id> and text <text>. Second argument is optional.

[[ViewTopic(<topic_subject>)]]

Displays content of topic with subject <topic_subject>. If no subject given displays content of topic with same subject as name of current wiki page. Currently there is a limitation of post length using this macro because of using GET method of HTML form.

[[RecentTopics(<forum_id>,<number_of_topics>)]] or [[RecentTopics(<number_of_topics>)]]

Displays list of recently changed topics in a forum <forum_id> or in all forums, if <forum_id> is not specified, grouped by the day of their last change. Second argument <number_of_topics> limits the number of recently changed topics displayed.

Example

Discuss this on the [forum:5 Trac Development forum]. 
Useful threads are [topic:23 this one] and [topic:96 this one].

Attachments

Foreign files can also be attached to topics and then linked in replies. For this purpose you can use general Trac attachment link syntax with disscussion domain and topic resource:

[attachment:discussion:topic/<topic_id>:<filename>]
[raw-attachment:discussion:topic/<topic_id>:<filename>]
[[Image(discussion:topic/<topic_id>:<filename>)]] 

There are also two custom macros doing the same and they simplifies the syntax a bit:

[topic-attachment:<topic_id>:<filename>]
[raw-topic-attachment:<topic_id>:<filename>]

Planned Features

  • Better permission system (maybe using 0.11 permissions policies).
  • email2trac support.

Notes

  • Branches 0.9 and 0.10 of the plugin are considered as deprecated and not developed anymore. User-contributed backporting patches are welcomed though.
  • Branch 0.11 of the plugin is tested mainly with Trac 0.12 now. If you encounter some problem on Trac 0.11, just create a ticket about it. Separate branch 0.12 will be created only in case of significant differences between Trac 0.11 and 0.12 relevant to the plugin.

Support

If you have any troubles with plugin's installation or configuration and your problem is generally Trac related, you can ask on #trac channel at Freenode IRC network to get the quickiest answer. If the problem is purely DiscussionPlugin related, you can create a topic at BlackTrac discussion - DiscussionPlugin forum

Feedback

Are you using this plugin?
  • Yes, it's usefull. (sgrayban, cboos, okaori, wadeb, s0undt3ch, ttressieres, imme, dh1jc, talameelombu, Tharban, athomas, jtuchscherer, xvirus, osimons, Sincklation, manni, izzy, ericalens, KevinGabbert, mwehr, renzo, marcvs, eskil, rjollos, koolhand, edo, colski, dfleming, lucasrangit, miezuit, lhr870630, hasienda, arnisandy, lucid, AdrianFritz, akliewer99)
  • No, it's useless.
  • No, I don't need it. (dfaerch, harmy, prz)
  • I think it will help

  • You don't have permission to vote. You may need to login.

Change Log

[14140] by hasienda on 2014-08-30 23:24:03
DiscussionPlugin: Provide permalink to most recently founded topic, refs #8232.

The link can be copied from the bottom of any (non-empty) forum topic listing.

[14139] by hasienda on 2014-08-30 17:20:13
DiscussionPlugin: Prevent TypeError: tuple indices must be integers, not str, refs #11902.

Thanks to Samuel Degrande for the original report and to Jun Omae for
explaining the issue and providing both, an elegant fix and improved unit tests.

[13945] by hasienda on 2014-05-31 23:44:08
DiscussionPlugin: Extend use of new attribute getter api method, refs #11706.

Preventing TypeError in case of invalid ID argument is required for this
use, and doesn't hurt for others anyway.

[13944] by hasienda on 2014-05-31 23:14:21
DiscussionPlugin: Review wiki macros and syntax provider code, refs #756 and #11706.

This includes a wide range of changes from adding another db access method to
api over moving SQL into model module to correcting resource ID as
required for fine-grained permission support.

Adding the missing import from trac.resource as follow-up to [9640] suggests
rare use of discussion WikiMacros so far.

[13942] by hasienda on 2014-05-30 22:32:02
DiscussionPlugin: Hotfix for topic (attachment parent) Trac resource, refs #756 and #11800.

I've been expecting issues when moving on towards unified resources and
resource permissions. This is another hack before being able to associate
attachments with full resource path, not just topic, the current shortcut.

[13939] by hasienda on 2014-05-24 00:44:45
DiscussionPlugin: Change listeners got incomplete objects, refs #6783 and #8981.

Fixed tag-related change listeners to get discussion item IDs, what caused
KeyErrors before, just raised a couple of other issues. Not all of these
issues are resolved yet. I decided to initially catch listener errors with
logged warnings for improved API method robustness.

Moved time stamp generation nearer to db action and letting _add_item()
return the added item ID obsoleted four api methods at once.

[13938] by hasienda on 2014-05-23 21:43:39
DiscussionPlugin: Narrow user selection according to granted permissions, refs #756.

You should be able to choose only users with appropriate permissions as
moderators, and the same applies to subscriptions. This is still not 100%
correct, because ultately fine-grained permisions could affect this too.

Author/Contributors

Author: Blackhex
Contributors: athomas lucid

Attachments (3)

Download all attachments as: .zip