Homec4science
Diffusion invenio-infoscience (maint-2.0) Browse

R3600/invenio/legacy/webcomment/doc/admin/webcomment-admin-guide.webdoc
b473f46447f4maint-2.0

Last Change
Raw File

webcomment-admin-guide.webdoc
View Options

# -*- mode: html; coding: utf-8; -*-
# This file is part of Invenio.
# Copyright (C) 2007, 2008, 2010, 2011 CERN.
#
# Invenio is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation; either version 2 of the
# License, or (at your option) any later version.
#
# Invenio is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Invenio; if not, write to the Free Software Foundation, Inc.,
# 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: WebComment Admin Guide -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/admin<lang:link/>">_(Admin Area)_</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->
<style type="text/css">
<!--
.guidecommentbox {
float:left;
clear:both;
font-size:small;
margin-bottom:12px
}
.guidecommentboxcontent {
border:1px solid #000;
padding:1px;
}
.guidecommentboxaction {
text-decoration:underline;
text-align:right;
}
-->
</style>
<h2>Contents</h2>
<strong>1. <a href="#1">Overview</a></strong><br />
<strong>2. <a href="#2">Managing WebComment</a></strong><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.1<a href="#2.1"> Viewing comments/review information</a><br />
<strong>3. <a href="#3">Configuring WebComment</a></strong><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.1<a href="#3.1"> Configuring moderator per collection</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.2<a href="#3.2"> Enabling LaTeX/MathJax in comments</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.3<a href="#3.3"> Configuring threading</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.4<a href="#3.4"> Configuring commenting rounds</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.5<a href="#3.5"> Configuring restrictions</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.5.1<a href="#3.5.1"> Record-level restrictions</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.5.2<a href="#3.5.2"> Discussion-level restrictions</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.5.3<a href="#3.5.3"> Comment-level restrictions</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.6<a href="#3.6"> Configuring file attachments</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;3.7<a href="#3.7"> Configuring email notifications</a><br />
<a name="1"></a><h2>1. Overview</h2>
<p>
WebComment manages all aspects related to comments. From the admin interface it is
possible to check comment statistics as well as manage comments reported.
If the user is authorized for moderation, when viewing a record special links are
displayed to execute actions such as delete/undelete or unreport comments.
</p>
<a name="2"></a><h2>2. Managing WebComment</h2>
<a name="2.1"></a><h3>2.1 Viewing comments/review information</h3>
<p> From the admin interface it is possible to view statistics related
to the most commented/reviewed records and latest comments/reviews posted.
</p>
<p> Depending on the role the user has, it will be possible to view information
related to the collections the user is authorized to.
</p>
<a name="3"></a><h2>3. Configuring WebComment</h2>
<a name="3.1"></a><h3>3.1 Configuring moderator per collection</h3>
<p>Configuration to specify which user is moderator of a given collection
is done through WebAccess administration interface.</p>
<p>In order to permit a given user to be a comment moderator, the following steps have to be followed:
</p>
<ul>
<li> Create a role for the user who is going to moderate (one for each moderator)</li>
<li> Go to the Action Administration Menu inside of WebAccess admin interface <br />
and assign this role to the action 'moderatecomments'. Specify as argument <br />
the collections allowed for the user.</li>
<li> In case you want to give the superadmin user access to all collections, follow <br />
the steps above and write * as the collection argument. </li>
</ul>
<a name="3.2"></a><h3>3.2 Enabling LaTeX/MathJax in comments</h3>
<p>
It is possible to enable LaTeX rendering in comments with the MathJax module. In order to do that,
it is necessary to set the following directive in the invenio configuration file:
<pre>CFG_WEBCOMMENT_USE_MATHJAX_IN_COMMENTS = 1</pre>
</p>
<a name="3.3"></a><h3>3.3 Configuring threading</h3>
<p>
Replies to comments can be organized in threads. It is possible to
configure the maximum depth of the threads with
the <code>CFG_WEBCOMMENT_MAX_COMMENT_THREAD_DEPTH</code> variable in
the <code>invenio-local.conf</code> file. <br/>
Set <code>CFG_WEBCOMMENT_MAX_COMMENT_THREAD_DEPTH = -1</code> to not limit the depth.<br/>
Set <code>CFG_WEBCOMMENT_MAX_COMMENT_THREAD_DEPTH = 0</code> for a "flat" discussion.<br/>
Set <code>CFG_WEBCOMMENT_MAX_COMMENT_THREAD_DEPTH = 1</code> for one-level deep threads (<b>default</b>)<br/>
etc..
</p>
<p>
The main advantage of setting a maximum depth is to not enter into
deep, meaningless indentations when users might not understand the
concept of threads, and mix the "reply to" and "add comment"
actions. When <code>CFG_WEBCOMMENT_MAX_COMMENT_THREAD_DEPTH</code> is reached,
the level of discussion becomes a "flat" discussion.
</p>
<p>
For example, with <code>CFG_WEBCOMMENT_MAX_COMMENT_THREAD_DEPTH = 1</code>, replies
to comments would go through to the following states:
<table style="text-align:center">
<tr><td>State 1</td><td></td><td>State 2</td><td></td><td>State 3</td><td></td><td>State 4</td></tr>
<tr><td valign="top">
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 1
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 2
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
</td>
<td style="padding:40px" valign="top">
<pre>
Reply to
Comment 1
-------->
</pre>
</td>
<td valign="top">
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 1
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox" style="margin-left:20px">
<div class="guidecommentboxcontent">
<b>Comment 3</b>
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 2
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
</td>
<td style="padding:40px" valign="top">
<pre style="margin-top:30px">
Reply to
Comment 3
-------->
</pre>
</td>
<td valign="top">
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 1
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox" style="margin-left:20px">
<div class="guidecommentboxcontent">
Comment 3
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox" style="margin-left:20px">
<div class="guidecommentboxcontent">
<b>Comment 4</b>
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 2
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
</td>
<td style="padding:40px" valign="top">
<pre style="margin-top:60px">
Reply to
Comment 3
-------->
</pre>
</td>
<td valign="top">
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 1
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox" style="margin-left:20px">
<div class="guidecommentboxcontent">
Comment 3
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox" style="margin-left:20px">
<div class="guidecommentboxcontent">
Comment 4
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox" style="margin-left:20px">
<div class="guidecommentboxcontent">
<b>Comment 5</b>
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Comment 2
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
</td></tr>
</table>
</p>
<a name="3.4"></a><h3>3.4 Configuring commenting rounds</h3>
<p>You can configure WebComment to group comments according to
the status of the commented record. This enables the creation of
commenting <em>rounds</em>, so that comments belonging
to the same round are grouped together, and comments belonging
to past rounds are less prominently displayed.
</p>
<p>
For example, let's say that a collaboration is commenting a draft
document: once a new revision of the document is uploaded by the
author, the already existing comments are grouped together and moved
to archive. The discussion page will then appear empty, and a new
commenting round can start.<br/>
The past commenting rounds are still visible as small individual
links at the top of the discussion. A click on one of these links
reveals the comments belonging to this group/round. It is then also possible
to continue replying to comments submitted during this past round,
though it is not possible to add a new comment (not a reply).
</p>
<table>
<tr>
<td valign="top">
<span style="text-decoration:underline;font-size:small"> &gt;Comments for revision 1</span><br/>
<span style="text-decoration:underline;font-size:small"> &gt;Comments for revision 2</span><br/>
<span style="text-decoration:underline;font-size:small"> v Comments for revision 3</span><br/><br/>
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Great paper. Check typo line 12.
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Are you sure that figure 5 is ok?
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
<div class="guidecommentbox">
<div class="guidecommentboxcontent">
Please include the standard logo.
</div>
<div class="guidecommentboxaction">Reply to</div>
</div>
</td>
<td valign="top" style="padding:40px" >
<pre style="margin-top:10px">
New revision
of file
------------>
</pre>
</td>
<td valign="top">
<span style="text-decoration:underline;font-size:small"> &gt;Comments for revision 1</span><br/>
<span style="text-decoration:underline;font-size:small"> &gt;Comments for revision 2</span><br/>
<span style="text-decoration:underline;font-size:small"> &gt; Comments for revision 3</span><br/>
<span style="text-decoration:underline;font-size:small"> v Comments for revision 4</span><br/><br/>
<p style="text-align:center"><em>(blank)</em></p
</td>
</tr>
</table>
<p>
In order to know what is the current round, the MARC metadata of the
commented record must specify the name of the current group to which new
comments have to be attached. The MARC field specifying the round "name"
can be configured with
the <code>CFG_WEBCOMMENT_ROUND_DATAFIELD</code> of
the <code>invenio-local.conf</code> file. There you can set the MARC code
that contains the round name, for each collection you want to enable rounds.
</p>
<p>Note that whatever the current round is, a reply to a
comment will always belong to the round of the parent.</p>
<p>
<em>How to modify the MARC field with the round name?</em>:
this is up to the admin of the system, but it would typically be done
by a WebSubmit submission. This field might already exists if you
store a revision number in your metadata, or date, etc.
</p>
<p>
<em>How to restrict commenting rounds?</em>: you can combine rounds
with the comment-level restrictions documented in
section <a href="#3.5.3">Comment-level restrictions</a>, which uses a
similar mechanism to protect comments.
</p>
<a name="3.5"></a><h3>3.5 Configuring restrictions</h3>
Comments restrictions can be configured at several levels, detailed in
the next sections. Note that restrictions applied to comments also
apply to the files attached to comments.
<a name="3.5.1"></a><h4>3.5.1 Record-level restrictions</h4>
<p>
When a record is restricted via its collection
(<code>viewrestrcoll</code> WebAccess action), the comments submitted
for this record are restricted to users who can view the record.
</p>
<a name="3.5.2"></a><h4>3.5.2 Discussion-level restrictions</h4>
<p>
Discussion pages can be restricted with the WebAccess <code>viewcomment</code>
and <code>sendcomment</code> actions. This let you define who can read or send
comments in particular collections.
</p>
<a name="3.5.3"></a><h4>3.5.3 Comment-level restrictions</h4>
<p>
Restrictions can be applied at the level of individual records. When
submitting a comment, WebComment checks in the record metadata if some
restriction should be applied. The field where WebComment is looking
for restrictions can be configured in the
the <code>CFG_WEBCOMMENT_RESTRICTION_DATAFIELD</code> of
the <code>invenio-local.conf</code> file. There you can define for each
collection the MARC code containing the restriction information.
</p>
<p>
For the restriction to be applied, an authorisation for
the <code>viewrestrcomment</code> WebAccess action must be set up.
The "status" parameter of the <code>viewrestrcomment</code> must match
the value in the MARC metadata. This lets you define different
restrictions based on the value in the metadata.
<br/>Unless the status is empty, the comment will be restricted, even if
no role is specifically linked to the <code>viewrestrcomment</code>
action for this status.</p>
<p>Note that whatever the status of the record is, a reply to a
comment always inherits the restriction of the parent.</p>
<em>How to modify the MARC field with the restriction?</em>:
this is up to the admin of the system, but it would typically be done by
a WebSubmit submission.
</p>
<a name="3.6"></a><h3>3.6 Configuring file attachments</h3>
<p>
WebComment allows authorized users to attach files to submitted
comments. This is only available to logged in users, who have been
authorized via the <code>attachcommentfile</code> WebAccess action. By
default no user (except admin) can attach files.</p>
<p>
In addition, you can configure the maximum number of allowed attachments with the
<code>CFG_WEBCOMMENT_MAX_ATTACHED_FILES</code> (default 5) variable of
the the <code>invenio-local.conf</code>
file. Set <code>CFG_WEBCOMMENT_MAX_ATTACHED_FILES = 0</code> for
unlimited number of files.<br/>
Note that this is only applicable only if you installed the jQuery plugins
with <code>make install-jquery-plugins</code>.
</p>
<p>
You can set up the maximum size (in bytes) of attachments with
the <code>CFG_WEBCOMMENT_MAX_ATTACHMENT_SIZE</code> variable of the
the <code>invenio-local.conf</code> file.
</p>
<a name="3.7"></a><h3>3.7 Configuring email notifications</h3>
<p>
WebComment allows users to subscribe to discussions directly from the
web interface. In addition you can set up automatic notifications that
don't require the users to subscribe. The main use case for this is to
notify the author that a new comment has been submitted on her
document.
</p>
<p>
WebComment checks for automatic notifications of comments in the MARC
record. It specifically looks for emails in fields defined by
the <code>CFG_WEBCOMMENT_EMAIL_REPLIES_TO</code> variable of the
the <code>invenio-local.conf</code> file. There you can define
the fields to look for for specific collections.
</p>
c4science · Help