Using spservices to create discussion and reply in a Discussion List

January 26, 2014 John Liu

This updated blog post describes how I go about building a threaded, inline comments system for any page, using a SharePoint Discussion List as the backend storage for threaded data.

I choose to use SPServices because originally, the webpart is built for a SharePoint 2007 environment.

I've rebuilt the webpart using the JavaScript code and confirm it runs happily in SharePoint 2013, and this time, with much better screenshots!
In SharePoint 2010 and 2013, you should be able to talk directly to the REST endpoint to perform read and updates.

Enter the Discussion List

Many users have a love-hate relationship with SharePoint's Discussion list. Perhaps more hate. The main culprit is the inflexible UI. Lack of many modern forum needs:

Can't show all discussions and show threaded replies together
Can't do inline new discussion
Can't do inline replies
Poor support cross browsers
Can't easily filter for a subset

But still, the list itself is very functional.

Does support threaded discussions
Calculates total replies and last discussion updated
Has email notification through SharePoint alerts
Has tweaked permission model where users can create but not modify their own posts, or can edit.

Figure: A basic SharePoint Discussion List

Let's ignore the problems with the native Discussion List UI, and build our own with JavaScript

Read from the Discussion List

/*
This code queries using SPServices' GetListItems on list and populates a UL.discussions dom element on the page
*/
var $ul = $("ul.discussions");
var list = "My Discussions";

function getDiscussionList(list, $ul) {
var promise = $().SPServices({
operation: "GetListItems",
listName: list,
CAMLViewFields: "<ViewFields><FieldRef Name='Title' /><FieldRef Name='Body' /><FieldRef Name='Author' /><FieldRef Name='Modified' /><FieldRef Name='DiscussionLastUpdated' /><FieldRef Name='ItemChildCount' /></ViewFields>",
CAMLQuery: "<Query><OrderBy><FieldRef Name='DiscussionLastUpdated' Ascending='FALSE' /></OrderBy></Query>"
});

promise.done(function(){
var items = $(promise.responseXML).SPFilterNode("z:row").SPXmlToJson({
    mapping: {},
    includeAllAttrs: true,
    removeOws: true
});
$ul.empty(); // clear old list

$.each(items, function(index, item) {
    // render each discussion
    var $li = $("<li class=discussion' />");
    $li.append(item.Title);
    $li.append(item.Body);
    $li.append(item.Author);
    $li.append(item.Modified);
    $li.append(item.DiscussionLastUpdated);
    $li.append(item.ItemChildCount);
    $li.append(item.FileRef);
    $li.append("<div class='replies'>replies</div>");
    $ul.append($li);

}); // end items.each
}); // end promise done
promise.fail(function(xhr, status, error) {
alert(xhr.responseText);
}); // end promise fail

} // end getDiscussionList

Key points:

List.asmx - GetListItems
This returns the top level items in the list, which are Discussions

Figure out the threaded discussions

In SharePoint discussion lists, the top level "Discussion" items are folders. The subsequent "Message" reply items are list items within that folder.
So to query for the replies to a discussion, we query the list with the filepath of the top level Discussion item as the query filter.

/*
This second function figure out the threaded replies when you expand one discussion
*/

Note: The FileRef usually has a value that looks like this:
// 15;#Company/Site1/Web1/Lists/My Discussions/15_.000
You need to clean the URL and use only the file path:

function getFilePath(fileRef) {
if (!fileRef) return;
var m = /;#(.*)$/.exec(fileRef);
if (m) {
return m[1];
}
}

This will give you:
Company/Site1/Web1/Lists/My Discussions/15_.000

function getDiscussionReplies(list, filepath) {
var options = {
operation: "GetListItems",
listName: list,
CAMLViewFields: "<ViewFields><FieldRef Name='Title' /><FieldRef Name='Body' /><FieldRef Name='Author' /><FieldRef Name='Modified' /><FieldRef Name='DiscussionLastUpdated' /><FieldRef Name='ItemChildCount' /></ViewFields>",
CAMLQueryOptions: "<QueryOptions><ViewAttributes Scope='RecursiveAll' IncludeRootFolder='True' /></QueryOptions>",
CAMLQuery: "<Query><Where><Contains><FieldRef Name='FileRef' /><Value Type='Text'>" + filepath + "</Value></Contains></Where><OrderBy><FieldRef Name='FileRef' Ascending='TRUE' /></OrderBy></Query>"
};
var promise = $().SPServices(options);

promise.done(function(){
var items = $(promise.responseXML).SPFilterNode("z:row").SPXmlToJson({
    mapping: {},
    includeAllAttrs: true,
    removeOws: true
});

$.each(items, function(index, item) {
// render each reply
// snipped

}); // end items.each
}); // end promise done

} // end getDiscussionReplies

Key points:

Use CAMLQueryOptions for RecursiveAll
Use FileRef contains FilePath to find all threaded (Message) replies

Create a Discussion in the Discussion List

To create a new discussion, you just need to create a new item in the Discussion List

var list = "My Discussions";
var title = $("input.title").text();
var body = $("textarea.body").text();

function newDiscussion(list, title, body) {

var promise = $().SPServices({
operation: "UpdateListItems",
batchCmd: "New",
listName: "Team Discussion",
updates: "<Batch OnError='Continue' >" +
       "<Method ID='1' Cmd='New'>" +
        "<Field Name='ContentType'>Discussion</Field>" +
       "<Field Name='FSObjType'>1</Field>" +   // Important: FSObjType = 1 means that this is a folder. If this isn't specified SharePoint sometimes create the wrong root level item.
        "<Field Name='Title'>" + escapeColumnValue(title) + "</Field>" +
        "<Field Name='Body'>" + escapeColumnValue(body) + "</Field>" +
       "</Method>" +
      "</Batch>"
});

promise.done(function(){
var $ul = $("ul.discussions");
getDiscussionList(list, $ul);

}); // end promise done

}

Figure: Start a new discussion inline

Key points:

List.asmx - UpdateListItems
Set FSObjType = 1, this is necessary or there were head-scratching bugs

(Optional) Filter a Discussion List to only related item

In the Discussion List settings, you can add a lookup column RelatedItem to an external List (or Document Library).
Then when you use the JavaScript above, you can filter your CAML Queries so that they only return elements that are related to the current page.

For getDiscussionList:

CAMLQuery: "<Query><Where><Eq><FieldRef Name='RelatedItem' /><Value Type='Number'>" + related + "</Value></Eq></Where><OrderBy><FieldRef Name='DiscussionLastUpdated' Ascending='FALSE' /></OrderBy></Query>"

And for creating discussion threads:

updates: "<Batch OnError='Continue' >" +
     "<Method ID='1' Cmd='New'>" +
      "<Field Name='ContentType'>Discussion</Field>" +
      "<Field Name='FSObjType'>1</Field>" +
      "<Field Name='Title'>" + escapeColumnValue(title) + "</Field>" +
      "<Field Name='Body'>" + escapeColumnValue(body) + "</Field>" +
      "<Field Name='RelatedItem'>" + related + "</Field>" +
     "</Method>" +
    "</Batch>"

In my project, I linked my discussion list to a Video Library, and each Video has an area for creating comments and reply to threaded discussions. All the conversation are saved in one single Discussions List, but filtered on each page as required.

Understand the nested format for Discussion List items

In a SharePoint Discussion List:

Discussion (content type) is a Folder. FSObjType = 1
Message (content type) is a List Item. FSObjType = 0

Reply in a Discussion List.

var list = "My Discussions";
var filepath = "Company/Site1/Web1/Lists/My Discussions/15_.000";
var body = $("textarea.body").text();

function replyDiscussion(list, filepath, body) {

// RootFolder needs to start with /

} // end replyDiscussion

Figure: Threaded Discussions, with inline reply.

Key points:

List.asmx - UpdateListItems
Set FSObjType = 0 (for List Item), this is necessary or there were head-scratching bugs
Set RootFolder to the Filepath of the parent Discussion (folder) item. This way, UpdateListItems creates a new list item within that folder.

Conclusion: here we are. Threaded, inline, replies.

Combine everything together, the javascript lets me now do:

Tie a Discussion List to a Picture Library
Start one or more discussion threads on any Picture
See replies inline in one single UI.
Inline comment-creation
Inline comment-reply

Inline Edit and Inline Delete is possible, but the end-user will need to follow SharePoint permission settings on the Discussion List. I have not written code to do those operations.