Discussions Overview

Last edited: 8/21/2008

Whether you call them message boards, forums, or in our case, Discussions, interaction between members of a site is one of the most important aspects of keeping your audience interested. And with our API, it has never been easier to get the conversation started.

The following getContents can simply be dropped into your site to provide a foundation to work from. Tweak the formatting, add or remove a tag using the Discussions API as a reference, style it, and you're done!

Textile support

To allow for formatting in comments, the Textile markup language has been integrated into the Discussions system. Raw HTML is not allowed -- so as not to allow members the ability to hijack the design or introduce security vulnerabilities -- and will be rendered as normal text within the comment. For a primer in the language of Textile, take a look at the quick reference or more thorough complete reference.

Display boards

The following getContent will display all of the discussion boards setup in the backend for a site:

getContent(
"discussions",
"display:boards",
"show:<h3><a href="__url__">__name__</a></h3>",
"show:<p>__description__</p>",
"nocache"
);

A complete listing of tags is available at the Display mode: boards Discussions API.

This getContent should be placed in a file named mcms_disc_boards.php, which is accessed through the URL http://www.mysite.com/discussions/. The .htaccess rule:

rewriteRule ^discussions/?$ /mcms_disc_boards.php [L,NC,QSA]

Display categories

The following getContent will display all of the categories setup in the backend for the specified board:

getContent(
"discussions",
"display:categories",
"boardname:" . $_GET['boardslug'],
"nav:<h3><a href="/discussions/">Boards</a> > __boardname__</h3>",
"show:<b><a href="__url__">__name__</a></b> [__count__]",
"show:<br />",
"show:__description__",
"show:<hr />",
"nocache"
);

A complete listing of tags is available at the Display mode: categories Discussions API.

This getContent should be placed in a file named mcms_disc_categories.php, which is accessed through the URL http://www.mysite.com/discussions/{board slug}/. The .htaccess rule:

rewriteRule ^discussions/([a-z0-9_-]+)/?$ /mcms_disc_categories.php?boardslug=$1 [L,NC,QSA]

Display discussions

The following getContent will display all of the discussions added by members to the specified category:

getContent(
"discussions",
"display:discussions",
"boardname:" . $_GET['boardslug'],
"categoryname:" . $_GET['catslug'],
"page:" . $_GET['page'],
"nav:<h3><a href="/discussions/">Boards</a> > <a href="__boardurl__">__boardname__</a> > __categoryname__</h3>",
"show:<b><a href="__url__">__name__</a></b>",
"show:<br />",
"show:[<b>Created on</b> __datecreated format='n/j/y'__] ",
"show:[<b>Started by</b> __username__] ",
"show:[<b>Last active</b> __datelastactive format='n/j/y'__] ",
"show:[<b>Comments</b> __count__] ",
"show:[<b>Last comment by</b> __lastusername__]",
"show:<hr />",
"pagination:<table width="100%" cellpadding="0" cellspacing="0">",
"pagination:<tr>",
"pagination:<td>",
"pagination:<a href="__firstpage__"><<</a> ",
"pagination:<a href="__previouspage__"><</a> ",
"pagination:page __currentpage__ of __totalpages__ ",
"pagination:<a href="__nextpage__">></a> ",
"pagination:<a href="__lastpage__">>></a>",
"pagination:</td>",
"pagination:<td align="right">",
"pagination:discussions __recordfrom__ to __recordto__ of __totalrecords__",
"pagination:</td>",
"pagination:</tr>",
"pagination:</table>",
"nocache"
);

A complete listing of tags is available at the Display mode: discussions Discussions API.

This getContent should be placed in a file named mcms_disc_discussions.php, which is accessed through the URL http://www.mysite.com/discussions/{board slug}/{category slug}/. The .htaccess rule:

rewriteRule ^discussions/([a-z0-9_-]+)/?([a-z0-9_-]+)?/?([0-9]+)?/?$ /mcms_disc_discussions.php?boardslug=$1&catslug=$2&page=$3 [L,NC,QSA]

Add a new discussion

The following getContent will display the form fields necessary to add a new discussion to the specified category:

getContent(
"discussions",
"display:newdiscussion",
"boardname:" . $_GET['boardslug'],
"categoryname:" . $_GET['catslug'],
"show:<h3>Add Discussion</h3>",
"show:__formopen__",
"show:Title:<br />",
"show:__namefield__",
"show:<br />Comment:<br />",
"show:__commentfield__",
"show:<br />",
"show:__submitbutton__",
"show:__formclose__",
"nocache"
);

A complete listing of tags is available at the Display mode: newdiscussion Discussions API.

This getContent can be placed in its own file, but normally appears after the getContent to display the discussions in mcms_disc_discussions.php, which is accessed through the URL http://www.mysite.com/discussions/{board slug}/{category slug}/.

Display comments

The following getContent will display all of the comments added by members to the specified discussion:

getContent(
"discussions",
"display:comments",
"boardname:" . $_GET['boardslug'],
"categoryname:" . $_GET['catslug'],
"discussionid:" . $_GET['discid'],
"page:" . $_GET['page'],
"nav:<h3><a href="/discussions/">Boards</a> > <a href="__boardurl__">__boardname__</a> > <a href="__categoryurl__">__categoryname__</a> > __discussionname__</h3>",
"show:<a name="__anchor__"></a>",
"show:<b>on __datecreated format='n/j/y'__ ",
"show:__username__ wrote:</b>",
"show: <a href="__editurl__">edit</a>",
"show:<br />",
"show:__comment__",
"show:<br /><br /><i>Edited by __editusername__ on __editdate format='n/j/y'__</i>",
"show:<hr />",
"pagination:<table width="100%" cellpadding="0" cellspacing="0">",
"pagination:<tr>",
"pagination:<td>",
"pagination:<a href="__firstpage__"><<</a> ",
"pagination:<a href="__previouspage__"><</a> ",
"pagination:page __currentpage__ of __totalpages__ ",
"pagination:<a href="__nextpage__">></a> ",
"pagination:<a href="__lastpage__">>></a>",
"pagination:</td>",
"pagination:<td align="right">",
"pagination:comments __recordfrom__ to __recordto__ of __totalrecords__",
"pagination:</td>",
"pagination:</tr>",
"pagination:</table>",
"nocache"
);

A complete listing of tags is available at the Display mode: comments Discussions API.

This getContent should be placed in a file named mcms_disc_comments.php, which is accessed through the URL http://www.mysite.com/discussions/{board slug}/{category slug}/{discussion slug}/{discussion ID}/. The .htaccess rule:

rewriteRule ^discussions/([a-z0-9_-]+)/?([a-z0-9_-]+)?/?([a-z0-9_-]+)?/?([0-9]+)?/?([0-9]+)?/?$ /mcms_disc_comments.php?boardslug=$1&catslug=$2&discid=$4&page=$5 [L,NC,QSA]

Add a new comment

The following getContent will display the form fields necessary to add a new comment to the specified discussion:

getContent(
"discussions",
"display:newcomment",
"discussionid:" . $_GET['discid'],
"show:<h3>Add Comment</h3>",
"show:__formopen__",
"show:__commentfield__",
"show:<br />",
"show:__submitbutton__",
"show:__formclose__",
"nocache"
);

A complete listing of tags is available at the Display mode: newcomment Discussions API.

This getContent can be placed in its own file, but normally appears after the getContent to display the comments in mcms_disc_comments.php, which is accessed through the URL http://www.mysite.com/discussions/{board slug}/{category slug}/{discussion slug}/{discussion ID}/.

Edit a comment

The following getContent will display the form fields necessary to edit the specified comment:

getContent(
"discussions",
"display:editcomment",
"commentid:" . $_GET['commentid'],
"show:__formopen__",
"show:Comment:<br />",
"show:__namefield__<br />",
"show:__commentfield__",
"show:<br />",
"show:__submitbutton__",
"show:__formclose__",
"nocache"
);

A complete listing of tags is available at the Display mode: editcomment Discussions API.

This getContent should be placed in a file named mcms_disc_edit_comment.php, which is accessed through the URL http://www.mysite.com/discussions/{board slug}/{category slug}/{discussion slug}/{discussion ID}/edit/{comment ID}/. The .htaccess rule:

rewriteRule ^discussions/([a-z0-9_-]+)/?([a-z0-9_-]+)?/?([a-z0-9_-]+)?/?([0-9]+)?/edit/?([0-9]+)?/?$ /mcms_disc_edit_comment.php?commentid=$5 [L,NC,QSA]

Delete a comment

The following getContent will display the form fields necessary to delete the specified comment:

getContent(
"discussions",
"display:deletecomment",
"commentid:" . $_GET['commentid'],
"show:__formopen__",
"show:__submitbutton__",
"show:__formclose__",
"nocache"
);

A complete listing of tags is available at the Display mode: deletecomment Discussions API.

This getContent can be placed in its own file, but normally appears after the getContent to edit the specified comment in mcms_disc_edit_comment.php, which is accessed through the URL http://www.mysite.com/discussions/{board slug}/{category slug}/{discussion slug}/{discussion ID}/edit/{comment ID}/.

System messages and how they work

When a request is made to post a new discussion or edit a comment, for example, the system 1) attempts to complete the action and 2) redirects the member to an appropriate URL. Attached to the query string of this URL is a sysmsgid parameter with an integer value corresponding to the result (whether success or failure) of the request. They are:

$systemMessages = array(
1  => 'The discussion could not be added at this time.',
2  => 'The comment could not be added at this time.',
3  => 'Please enter a discussion title to submit.',
4  => 'Please enter a comment to submit.',
5  => 'The integrity of your action could not be verified.',
6  => 'The discussion was successfully added.',
7  => 'The comment was successfully added.',
8  => 'The comment could not be edited at this time.',
9  => 'The comment was successfully edited.',
10 => 'The comment could not be deleted at this time.',
11 => 'The comment was successfully deleted.',
12 => 'The discussion could not be deleted at this time.',
13 => 'The discussion was successfully deleted.',
14 => 'The discussion could not be edited at this time.',
15 => 'The discussion was successfully edited.'
);

To display the system messages as helpful feedback, include the above array along with the following PHP code in each mcms_disc_*.php file:

if (array_key_exists($_GET['sysmsgid'], $systemMessages)) {
  print "<p><strong>" . $systemMessages[$_GET['sysmsgid']] . "</strong></p>";
}

 

Examples

Here are two examples that show discussion boards in action.

http://developers.monkcms.com/discussions/

http://demo.ekklesia360.com/discussions/