Extension:DiscussionThreading/doc

Title:  Modify Discussion Functionality to be more threadlike

Description:

See formal extension description

The thread-like nature of discussions is highly valuable. This extension is a quasi threading adaption for the discussion feature that does the following:


 * 1) Adds a [new] link onto the header that creates a new comment on the page when used.
 * 2) Adds a [reply] link onto the header that creates a reply to that section.
 * 3) Automatically adds a signature in at the top of the section - preferably in the header bar to show up in TOC
 * 4) Enters the discussion page in the add comment mode (and automatic signature) when new discussion page made

This requires adding 2 new hooks to Linker.php - which requires manual patching. The extension itself includes multiple hooks and the initial setup.

Installation Instructions
Will absolutely not work below 1.6.0, requires features added with that release.

The "reply" feature requires a new parameter passed to the EditPage. This parameter is "replyto=yes" when the user is replying to a previous post.

You can apply this extension either by downloading and copying the files into your wiki, or by manual processes below. The referenced packages have the files necessary to implement without editing patches, but only for the following versions. :


 * REL1_10_1 (untested)
 * REL1_10
 * REL1_9_3

If you do not have one of these versions, you must manually patch.

Download and Install Instructions
You can download the extension and already patched files from:


 * Windows Zip Package
 * TAR Package

require_once("$IP/extensions/DiscussionThreading/DiscussionThreading.php");
 * 1) Create a new directory extensions/DiscussionThreading
 * 2) Copy the files DiscussionThreading.php and DiscussionThreading.i18n.php into extensions/DiscussionThreading
 * 3) Select the appropriate Release Directory (NOTE: DO NOT USE THESE UNLESS YOU HAVE THE EXACT RELEASE) and perform ONLY ONE of the following two steps:
 * 4) Apply the patch file to your existing includes/linker.php file
 * 5) Copy the included linker.php file into your includes directory, overwriting the existing version (Note:  If you have applied other patches to this file they will be overwritten).
 * 6) Patch localsettings.php by adding the following near other require_once or at the end before the close statement:

If you have executed this properly, you will have the following:


 * DiscussionThreading.php and DiscussionThreading.i18n.php moved into $IP/extensions/DiscussionThreading/DiscussionThreading.php
 * Either patched Linker.php or the loaded Linker.php from the EXACT distribution downloaded release in $IP/includes/
 * extensions/DiscussionThreading/DiscussionThreading.php executed from localsettings.php

The next version (1_11_0) and trunk eliminate the need for patching. I had to slightly modify the DiscussionThreading.php file to accomodate. If you are upgrading from DiscussionThreading 0.*, you have to update all three files for DiscussionThreading version 1.1:
 * includes/Linker.php
 * extensions/DiscussionThreading/DiscussionThreading.php
 * extensions/DiscussionThreading/DiscussionThreading.i18n.php

Manual Patching and Installation
Details are below, but these are required steps:

require_once("$IP/extensions/DiscussionThreading/DiscussionThreading.php");
 * 1) Create a new directory extensions/DiscussionThreading
 * 2) Create a new file extensions/DiscussionThreading/DiscussionThreading.php and copy and paste the below code
 * 3) Create a new file extensions/DiscussionThreading/DiscussionThreading.i18n.php and copy and paste the below code
 * 4) Patch Linker.php according to below instructions
 * 5) Patch localsettings.php by adding the following near other require_once or at the end before the close statement:

There is something very funky about flushing the PHP compiled cache. I was only able to get the changes made in the Linker.php file to take effect by going to a discussion page while I was logged on as an administrator on the patched server and using a browser local to that machine (press the + tab). Somehow, this caused the .php files to recompile and activate for everyone.

Patches Required
To do this, have to patch the following (instructions are for 1.10.0, future or past releases will, of course vary with line numbers and locations):

Modified linker.php editSectionLinkForOther (line 985 in REL1_10)
public function editSectionLinkForOther( $title, $section ) { global $wgContLang;

$title = Title::newFromText( $title ); $editurl = '&section='.$section; $url = $this->makeKnownLinkObj( $title, wfMsg('editsection'), 'action=edit'.$editurl ); /** Added editSectionLinkForOther hook that allows section/header link to be modified */ $result = null; wfRunHooks( 'EditSectionLinkForOther', array( &$this, $title, $section, $url, &$result ) ); return is_null( $result ) ? "[{$url}] " : "[{$result}] "; /** End of hook */ }
 * 1) - 	return "[".$url."] ";

Modified linker.php editSectionLink (line 1004 in REL1_10)
public function editSectionLink( $nt, $section, $hint='' ) { global $wgContLang;

$editurl = '&section='.$section; $hint = ( $hint=='' ) ? '' : ' title="' . wfMsgHtml( 'editsectionhint', htmlspecialchars( $hint ) ) . '"'; $url = $this->makeKnownLinkObj( $nt, wfMsg('editsection'), 'action=edit'.$editurl, , , '', $hint ); /** Added editSectionLink hook that allows section/header link to be modified */ $result = null; wfRunHooks( 'EditSectionLink', array( &$this, $nt, $section, $hint, $url, &$result ) ); return is_null( $result ) ? "[{$url}] " : "[{$result}] "; /** End of hook */ }
 * 1) - 	return "[".$url."] ";

DiscussionThreading Extension
extensions/DiscussionThreading.php

This extension implements a discussion threading process. This threading will only be seen on the talk pages, unless explicity invoked in the command line.

It adds a [reply] link on the header line. Each time a new posting is entered or a posting is replied to, the comment will automatically be tagged (and appear in the TOC too). Of course direct editing can occur, but this really makes it a lot easier to organize discussions in a threading view that most are familiar with.

To do:
 * 1) get someone who knows regex to clean up the parsing of the subject line
 * 2) Assess to see if there's an easier way to do this

 * @addtogroup Extensions * @copyright © 2007 Jack D. pond * @licence GNU General Public Licence 2.0 or later */

if( defined( 'MEDIAWIKI' ) ) {

require_once( "$IP/extensions/DiscussionThreading/DiscussionThreading.i18n.php" );
 * 1) Internationalisation file

$wgExtensionFunctions[] = 'efDiscussionThreadSetup'; $wgExtensionCredits['other'][] = array( 						'name' => 'DiscussionThreading', 						'author' => 'Jack D. Pond',						'url' => 'http://www.mediawiki.org/wiki/Extension:DiscussionThreading',						'description' => 'Add Threading to discussion (talk) pages' );

/**	 * Set up hooks for discussion threading *	 * @param $wgSectionThreadingOn global logical variable to activate threading */

global $wgSectionThreadingOn; $wgSectionThreadingOn = True;

$wgHooks['EditPage::showEditForm:initial'][] = 'efDiscussionThread'; $wgHooks['EditPage::attemptSave'][] = 'efStampReply'; $wgHooks['EditPage::showEditForm:initial'][] = 'efDiscussionThreadEdit'; $wgHooks['EditSectionLinkForOther'][] = 'efDiscussionLink4other'; $wgHooks['EditSectionLink'][] = 'efDiscussionLink'; $wgHooks['AlternateEdit'][] = 'efDiscussionThreadEdit';

/**	 * Initial setup, add .i18n. messages from $IP/extensions/DiscussionThreading.i18n.php */			function efDiscussionThreadSetup { global $wgMessageCache, $wgDiscussionThreadMessages;

foreach( $wgDiscussionThreadMessages as $lang => $messages ) $wgMessageCache->addMessages( $messages, $lang ); }	/**	 * This function creates a linkobject for the editSectionLinkForOther function in linker *	 * @param $callobj Article object. * @param $title Title object. * @param $section Integer: section number. * @param $hint Link String: title, or default if omitted or empty * @param $url Link String: for edit url * @param $result String: Returns the section [new][edit][reply] html if in a talk page - otherwise whatever came in with * @return true */

function efDiscussionLink4other ($callobj, $title, $section, $url , &$result) {		global $wgSectionThreadingOn; if($wgSectionThreadingOn && $title->isTalkPage ) { $commenturl = '&section='.$section.'&replyto=yes'; $curl = $callobj->makeKnownLinkObj( $title, wfMsg('replysection'), 'action=edit'.$commenturl ); $newthreadurl = '&section=new'; $nurl = $callobj->makeKnownLinkObj( $nt, wfMsg('threadnewsection'), 'action=edit'.$newthreadurl ); $result = $nurl."][".$url."][".$curl; }		return (true); }

/**	 * This function creates a linkobject for the editSectionLink function in linker *	 * @param $callobj Article object. * @param $nt Title object. * @param $section Integer: section number. * @param $hint Link String: title, or default if omitted or empty * @param $url Link String: for edit url * @param $result String: Returns the section [new][edit][reply] html if in a talk page - otherwise whatever came in with * @return true */

function efDiscussionLink ($callobj, $nt, $section, $hint='', $url, &$result) {		global $wgSectionThreadingOn; if($wgSectionThreadingOn && $nt->isTalkPage ) { $commenturl = '&section='.$section.'&replyto=yes'; $hint = ( $hint=='' ) ? '' : ' title="' . wfMsgHtml( 'replysectionhint', htmlspecialchars( $hint ) ) . '"'; $curl = $callobj->makeKnownLinkObj( $nt, wfMsg('replysection'), 'action=edit'.$commenturl, , , '', $hint ); $newthreadurl = '&section=new'; $hint = ( $hint=='' ) ? '' : ' title="' . wfMsgHtml( 'threadnewsectionhint', htmlspecialchars( $hint ) ) . '"'; $nurl = $callobj->makeKnownLinkObj( $nt, wfMsg('threadnewsection'), 'action=edit'.$newthreadurl, , , '', $hint ); $result = $nurl."][".$url."][".$curl; }		return (true); }

/**	 * This function is a hook used to test to see if empty, if so, start a comment *	 * @param $efform form object. * @return true */

function efDiscussionThreadEdit ($efform) { global $wgRequest,$wgSectionThreadingOn; $efform->replytosection = ''; $efform->replyadded = false; $efform->replytosection = $wgRequest->getVal( 'replyto' ); if( !$efform->mTitle->exists ) { if($wgSectionThreadingOn && $efform->mTitle->isTalkPage ) { $efform->section = 'new'; }		}		return (true); }

/**	 * Create a new header, one level below the 'replyto' header, add re: to front and tag it with user information *	 * @param $efform Form Object before display * @return true */

function efDiscussionThread($efform){ global $wgSectionThreadingOn; $wgSectionThreadingOn = isset($wgSectionThreadingOn) ? $wgSectionThreadingOn : false; if ( $efform->replytosection != '' && $wgSectionThreadingOn && !$efform->replyadded) { if ($efform->replytosection != '') { $text = $efform->textbox1; $matches = array; preg_match( "/^(=+)(.+)\\1/mi",					$efform->textbox1,					$matches ); if( !empty( $matches[2] ) ) { preg_match( "/.*(-+)\\1/mi",$matches[2],$matchsign); if (!empty($matchsign[0]) ){ $text = $text."\n\n".$matches[1]."=Re: ".trim($matchsign[0])." ~".$matches[1]."="; } else { $text = $text."\n\n".$matches[1]."=Re: ".trim($matches[2])." -- ~".$matches[1]."="; }				} else { $text = $text." -- ~ \n\n"; }				$efform->replyadded = true; $efform->textbox1 = $text; }			return (true); }		return (true); }	/**	 * When the new header is created from summary in new (+) add comment, just stamp the header as created *	 * @param $efform Form Object before display * @return true */

function efStampReply($efform){ global $wgSectionThreadingOn; $wgSectionThreadingOn = isset($wgSectionThreadingOn) ? $wgSectionThreadingOn : false; if ( $efform->section == "new" && $wgSectionThreadingOn && !$efform->replyadded) { $efform->summary = $efform->summary." -- ~"; }		return(true); } } ?>

Internationalisation file DiscussionThreading.i18n.php
I was only completely comfortable with the english translations - looking to others to help me put the correct language translations in.

I would deeply appreciate your help here.

Load into file (in extension DiscussionThreading.i18n.php)

 'reply',	'replysectionhint' => "Reply to this Posting",	'threadnewsection' => 'new',	'threadnewsectionhint' => "Start a new thread" );

/* Need to add af,br,bs,ca,cs,cy,de,et,eu,fi,fr,ga,gl,he,hr,hsb,id,is,it,ja,kk-kz,kk-tr,kk-cn,kk,lv,nl, no,nn,oc,pt,pt-br,ro,ru,sk,sl,sq,uk,wa,zh-cn,zh-tw,zh-yue,zh-hk,zh-sg

Would do this by adding a new $wgDiscussionThreadMessages array example: $wgDiscussionThreadMessages['lang1'] = array(	'replysection' => 'lang1 - tag',	'replysectionhint' => "lang1 - hint",	'threadnewsection' => 'lang1 - new',	'threadnewsectionhint' => "'lang1 - Start a new thread" ); ?>

Would add new languages with a new array per, using this array schema for each language:

$wgDiscussionThreadMessages['lang1'] = array(	'replysection' => 'lang1 - tag',	'replysectionhint' => "lang1 - hint",	'threadnewsection' => 'lang1 - new',	'threadnewsectionhint' => "'lang1 - Start a new thread" );

Indenting Headers
If you are really serious about threading, you can indent headers by modifying the corresponding CSS file (eg. skins/monobook/main.css). To modify all headers (talk or regular article), you can add a 'padding-left: x em;' into each of the headers 3-6. Eg.:

h3 { font-size: 132%; padding-left: 1em ;} h3 .editsection { font-size: 76%; font-weight: normal; } h4 { font-size: 116%; padding-left: 2em ;} h4 .editsection { font-size: 86%; font-weight: normal; } h5 { font-size: 100%; padding-left: 3em ;} h5 .editsection { font-weight: normal; } h6 { font-size: 80%; padding-left: 4em ; } h6 .editsection { font-size: 125%; font-weight: normal; }