Premium Pack 1.51 > User Comments in WebHelp

The Premium Pack has integrated support for user comments in WebHelp using the IntenseDebate or Disqus blog commenting systems. You don't need to do any installation. You just sign up for the service and add your IntenseDebate or Disqus ID to the skin you are using. IntenseDebate is a free system from the makers of WordPress.

Disqus is an independent solution that is available in both free and paid versions, depending on the nature of your usage and your site. Both have extensive integration of social media and handle all the details of user databases and user login for you. Users can log in with their existing social media accounts, including Twitter, Facebook, OpenID and others, or by signing up for a free IntenseDebate or Disqus account.

How it works

When you sign up for an account with Disqus or IntenseDebate you give the service the URL of your WebHelp and they give you an ID for that address. Users can then sign in and add comments to any topic in your help.

The comments are hosted by the comment service provider and stored on their site. They are linked to your URL and the IDs of your topics. This means that the comments are "update-proof". You can modify and re-upload your help, this will not eliminate the comments as long as you do not change the IDs of your topics.

Limitations of the individual systems

There some key limitations of these commenting systems in Help & Manual WebHelp that you need to be aware of:

Both systems:
Since these are online systems the comments will only work on the Internet and only with WebHelp. You cannot use these comments on local WebHelp stored on users computers or on intranet systems within your own company or in HTML Help CHM files. The Premium Pack skins check the current URL and hide all comment components if the current URL does not match the URL registered with your comment provider.

IntenseDebate:
IntenseDebate's support for Facebook logins is not compatible with websites using frames. If you use IntenseDebate, you should not enable the Facebook login option.

Disqus:
Similarly, the Disqus commenting system is not compatible with Help & Manual WebHelp on iOS devices (iPhone and iPad). If you are targeting these devices you should not choose Disqus. Visitors on these devices will not see any comments. The Premium Pack scripts will identify them and hide the comments from view.

Visit the IntenseDebate or Disqus websites and sign up for an account. Both sites have plenty of information about the features and services provided. They are quite similar in many ways, but there are differences. Before signing up, you need to know the URL of the folder on your server where you plan to install your WebHelp, because you need to provide this to get your comments ID.

When you sign up you will be given an ID for your comments account. On IntenseDebate this is referred to as your account ID, Disqus calls it your "website short name". Make a note of this, you will need it for installation in your Premium Pack skin, along with the URL of your WebHelp site.

IMPORTANT:You don't need to follow the Disqus or IntenseDebate installation instructions!

The installation instructions on the IntenseDebate and Disqus sites are for manual installation on blogs and websites. You don't need to and shouldn't follow these instructions and you don't need to set any of the additional configuration variables. This is all handled automatically by the Premium Pack, where everything is already pre-installed and integrated in the skin. For example, the comment post IDs and topic URLs are all assigned for every topic you generate on the basis of your topic IDs and the address of your help.

You can configure your account on your Disqus or IntenseDebate dashboard after logging in with your comments provider.

Both systems allow you to choose what services you want to enable for users to log in to enter comments. If you are using IntenseDebate do not enable the Facebook login option as this is not compatible with frame-based sites. It will work, but it will generate a lot of script errors that will confuse your users and cause support requests.

General configuration options:

Both systems have a lot of useful options for things like moderation, and so on. You can leave these at the default settings for your first tests but you will probably want to go through all the available options carefully before you set your comments to go live.

Akismet anti-spam service:

Both Disqus and IntenseDebate support the excellent Akismet anti-spam plug-in. We strongly recommend that you sign up for this service and enable it as soon as possible. It works very well and will save you a lot of trouble by automatically identifying and blocking spam comments.

Next you need to enter three key pieces of information in your skin to activate your comments: the comments provider (Disqus or IntenseDebate), the comments ID from your provider and the URL of your WebHelp folder on your server. These are entered in the configuration variables of your skin.

1.Open the .hmskin skin file you are using for your WebHelp in Help & Manual.

2.Go to Project Explorer > Configuration > Common Properties > Text Variables and set the variables listed below.

Comments Provider:

Set the variable COMMENTS_TYPE to the name of your comments provider. Enter Disqus if you are using Disqus comments and IntenseDebate if you are using IntenseDebate comments.

Comments ID:

Set the variable COMMENTS_ID to the ID for your comments from your comments account. Disqus refers to this as your "website short name", IntenseDebate calls it your ID.

WebHelp URL:

Set the variable HELP_URL to the URL of your WebHelp. This must include the http:// prefix and the name of your main index file, which is normally index.html. If you leave out either of these components it will not work correctly.

Example:

http://help.ec-software.com/index.html

Now you just need to compile your WebHelp with the new version of the skin and upload it to the folder on your server. Note that since these are online systems the comments will only work on the Internet. You cannot use these comments on local WebHelp stored on users computers or on intranet systems within your own company. The Premium Pack skins check the current URL and hide all comment components if the current URL does not match the URL registered with your comment provider.

Activating comments in the Publish dialog:

To activate comments activate the PP User Comments checkbox in the Publish dialog when you compile your WebHelp output.

Interface texts:

See the variables reference for details on the variables for the interface texts used for accessing the comments. This includes the link texts for showing and hiding the comments and the text displayed instead of the comments if your comment provider's system is ever offline.

Disabling comments:

You can disable comments in your WebHelp quickly and easily if you ever need to. Just download the file comments.js from your website and change the var comments_off variable in the first line from "false" to "true" so that it looks like this:

var comments_off=true;

Then just upload the edited comments.js file back up to your website and comments will be hidden.

If you are using IntenseDebate there is a pop-up dialog that allows users to subscribe to comments with RSS. The standard text is for blogs and the English version says "Subscribe to this blog post's comments...", which is not really appropriate for WebHelp. To change this, you need to access the plugin editor in your IntenseDebate account and make a small change. This will replace the text "blog post" and "blog posts" in the dialog with "topic" and "topics".

WARNING:
Changing these settings in IntenseDebate needs to be done with care. Please don't add or change anything except what is shown here!

1: Get the Site ID for your account :

Log in to your IntenseDebate account and then access http://intensedebate.com/sitekey/ to get the site ID. The site ID for your account is the second of the three values shown for the site, it is the shorter numeric code.

2: Access the plugin editor

The plugin editor URL for your account is http://intensedebate.com/pluginEditor/#####, where ##### is the site id for the account you got in step 1.

3: Insert the following code

Paste the code listed below into the "Javascript to load:" editing box, without making any changes or additions:

function id_swap_words() {

document.getElementById('IDCommentsHeadFollowMenu').innerHTML =

document.getElementById('IDCommentsHeadFollowMenu').innerHTML.replace(/blog post/ig, 'topic').replace(/blog posts/ig, 'topics').replace(/this blog\'s/ig, 'all');

}

id_add_action('idcomments_func_load', id_swap_words);