Editing DiscussionPlugin

[[PageOutline(2-5,Contents,pullout)]] = Add a discussion forum to Trac == Description This plugin adds discussion forum capabilities to Trac. Key features: * Any number of forums can be added and organized in forum groups. * Users can create topics in forums and reply to them, which together create 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. * Appending new forums and topics either as new replies shows up in timeline. * Searching capability in topics and replies is supported too. The plugin is administrated directly or via the Trac administration interface with appropriate permissions granted. '''Discussion list''': [[Image(discussion_list.png, 80%, border=2)]] '''Admin page''': [[Image(admin.png, 80%, border=2)]] '''Thread''': [[Image(thread.png, 80%, border=2)]] == Bugs/Feature Requests Existing bugs and feature requests for DiscussionPlugin are [report:9?COMPONENT=DiscussionPlugin here]. If you have any issues, create a [/newticket?component=DiscussionPlugin new ticket]. [[TicketQuery(component=DiscussionPlugin&group=type,format=progress)]] == Download Download the zipped source from [export:discussionplugin here]. The plugin is also available on [pypi:TracDiscussion PyPI]. == Source You can check out DiscussionPlugin from [/svn/discussionplugin here] using Subversion, or [source:discussionplugin browse the source] with Trac. == Installation === Dependencies If you need spam filtering features, then the SpamFilterPlugin is required. In other cases, disable the !DiscussionSpamFilter component. Sqlite version 3 or PostgreSQL is required as the database for running this plugin. === Plugin versions General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page. == Configuration The plugin is configurable from {{{trac.ini}}} file, see TracIni for more on this topic. The following variables controls DiscussionPlugin's behavior: {{{#!ini [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 = }}} Options: {{{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_sort}}} :: to sort Topic lists. It has values * {{{id}}}, * {{{forum}}}, * {{{subject}}}, * {{{time}}}, * {{{author}}}, * {{{body}}}, * {{{replies}}} and * {{{lastreply}}}. {{{forum_sort_direction}}} and {{{topic_sort_direction}}} :: are directions of that sorting: * {{{asc}}} and * {{{desc}}}. {{{topics_per_page}}} and {{{messages_per_page}}} :: options controls number of items displayed in topic and message lists at each page of pagination. You can type a list of email addresses into {{{smtp_always_cc}}} option to send all discussion plugin email notification to them. Previous example shows default values for these options. If you run Trac in an environment which needs to enable plugins explicitly, put in `trac.ini` these lines: {{{#!ini [components] tracdiscussion.admin.DiscussionWebAdmin = enabled tracdiscussion.api.DiscussionApi = enabled tracdiscussion.core.DiscussionCore = enabled tracdiscussion.init.DiscussionInit = enabled tracdiscussion.notification.DiscussionEmailNotification = 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 tracdiscussion.tags.DiscussionTagProvider = enabled tracdiscussion.tags.DiscussionTags = enabled tracdiscussion.ajax.DiscussionAjax = enabled }}} The next step is to upgrade your environment: {{{#!sh $ trac-admin <path_to_environment> upgrade }}} == Permissions This plugin defines the following 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. * The `DISCUSSION_MODERATE` permission gives you rights to delete replies or topics where you are defined as a moderator. * The `DISCUSSION_ADMIN` permission gives you administrator rights to create, modify or delete forum groups, forums and topics. You can add these permissions by typing the following commands from commandline or you can use web administration interface to do it for you: {{{#!sh $ 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 a 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 is given, then it displays the content of the topic with same subject as the name of the current wiki page. Currently there is a limitation of post length using this macro, because of using GET method of the 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 discussion 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 simplify the syntax a bit: {{{ [topic-attachment:<topic_id>:<filename>] [raw-topic-attachment:<topic_id>:<filename>] }}} == Change Log [[ChangeLog(/discussionplugin, 3)]] == Author/Contributors '''Author:''' [wiki:Blackhex Blackhex] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' [wiki:athomas], [wiki:hasienda], [wiki:lucid], [wiki:rjollos][[BR]]