Kentico CMS 7.0 Developer's Guide



Previous topic Next topic Mail us feedback on this topic!  


Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

Subscriptions allow users to receive e-mail notifications when a new post is added to a selected forum or as a reply to a specific post. Users may subscribe directly while browsing through forums on the live site.


When viewing the thread list of a forum, the Subscribe to forum link displayed at the top provides a way to subscribe to the entire forum (all of its threads).


To subscribe to a specific post and the replies under it, users can click on the Subscribe to post button shown below any given post.



Both of these actions open a dialog where users can submit their e-mail address.





Please note


The subscription functionality may be disabled through the properties of the web part used to publish the forum or forum group.


Additionally, the Security settings of specific forums may be configured to only allow subscription for certain types of users or roles.



Enabling double opt-in


To make users confirm that the e-mail address they're subscribing with really exists and belongs to them, you can enable the double opt‑in functionality. With double opt‑in enabled, subscribers will be sent an e-mail with a confirmation link. They will have to click the link to create their subscription.


To enable double opt‑in globally for all forums:


1. Go to Site Manager -> Settings -> Community -> Forums.


2. Turn on the Enable double opt-in for forums setting.


3. Specify how long you want the confirmation links to be valid in the Double opt-in interval setting.


The following two steps are optional. If you omit them, the system will use the default approval page located in ~/CMSModules/Forums/CMSPages/SubscriptionApproval.aspx.


4. Place the Forum subscription confirmation web part on a new page. Adjust its properties according to your needs.


5. Enter the page's path into the Double opt-in approval page path setting.


Double opt-in should now be configured for all forums. You can override the settings for each forum group in its properties in CMS Desk -> Tools -> Forums. You can also define specific settings for particular forums.


The functionality uses the Forums - Subscription request e-mail template. You can insert the confirmation link into the template using the {%SubscriptionLink%} macro.




Users can cancel their forum subscriptions at any time by clicking on the unsubscription link included in every notification e-mail about a new post (when using the default e-mail template).




The link leads to a page that automatically processes the unsubscription request and deletes the appropriate subscription (it is identified using a parameter passed in the query string of the link's URL).


This is either handled by the ~/CMSPages/Unsubscribe.aspx system page, or by a custom unsubscription page created for the website. If you wish to use a custom page, it is necessary to place the Forum unsubscription web part onto it, which ensures all the required functionality. The URL of this page then needs to be entered into the Forum unsubscription URL field of the given forum or forum group (the value can also be inherited from the website's Forum unsubscription URL setting, which can be specified in Site Manager -> Settings -> Community-> Forums).





Subscription e-mails and the Forum base URL


It is important to set a correct Forum base URL value in the forum configuration so that the subscription notifications and other related e-mails contain valid links leading to the appropriate forum.


When entering the value, you can use the relative URL of the page where the forum is located, for example: ~/Community/Forums.aspx



Alternatively, users with access to CMS Desk can view all of their active forum subscriptions in My Desk -> My profile -> Subscriptions and manually Unsubscribe (Delete) as needed.




For live site users, the same options can be provided by the My account web part, as long as its Display my subscriptions and Display forum subscriptions properties are enabled.


Managing subscriptions


When editing a forum in CMS Desk -> Tools -> Forums, administrators can manage all of the given forum's subscriptions on the Subscriptions tab.



The Delete (Delete) action may be used to remove existing subscriptions. If this is done with the Send confirmation e-mail to subscriber checkbox enabled, a notification e-mail will be sent to the given address, informing about the unsubscription.


The NewSubscription New subscription button provides a way to subscribe a user to the whole forum. When clicked, the dialog depicted in the screenshot below is opened. All that needs to be done is enter the e‑mail address of the user that should be subscribed and then click OK.




Like when removing subscriptions, the checkbox at the bottom of the dialog indicates if a confirmation e-mail should be sent to the address of the new subscriber. These confirmation e-mails are sent automatically to users who subscribe on-site.


E-mail templates


The post notification e-mails are sent to the subscribed users based on the Forums - New post e-mail template, which can be edited in Site Manager -> Administration -> E‑mail templates. The notifications informing users about their forum subscriptions or unsubscriptions are based on the Forums - Subscription confirmation and Forums - Unsubscription confirmation templates respectively. If you have double opt-in enabled for forums, the e-mail that is sent upon requesting subscription is based on the Forums - Subscription request template.


You can use the following specific context macros in forum subscription e‑mail templates:


{% ForumDisplayName %} - display name of the related forum.

{% ForumName %} - code name of the related forum.

{% ForumDescription %} - resolves into the description text of the forum.

{% GroupDisplayName %} - display name of the related forum group.

{% GroupName %} - code name of the related forum group.

{% GroupDescription %} - description text of the forum group.

{% PostSubject %} - the subject of the new forum post that caused the notification to be sent.

{% PostText %} - resolves into the HTML content of the new post.

{% PostTextPlain %} - resolves into the plain text version of the new post's content.

{% PostUsername %} - name of the user who created the post.

{% PostTime %} - the date and time when the new post was added.

{% Link %} - resolves into a link to the new post.

{% UnsubscribeLink %} - generates a link that can be used to unsubscribe from the given forum.


The two macros below are available for (un)subscription notifications:


{% Subject %} - if the user is subscribed to a specific post, this resolves into the subject of the given post. Otherwise it returns an empty string.

{% Separator %} - if the user is subscribed to a specific post, this returns the value of the forums.confirmationtemplateseparator resource string (" - " by default). This can be placed between the name of the forum and the subject of the post to cover both possible subscription scenarios.


You can use the following macro when double opt-in is enabled:


{% SubscribeLink %} - contains the URL of the page used to confirm subscriptions.


You can also access the following related objects and their properties (e.g. {% ForumPost.PostViews %}:


{% ForumPost %} - ForumPostInfo object of the post to which the user is subscribed (if applicable).

{% Forum %} - ForumInfo object representing the forum to which the user is subscribed.

{% ForumGroup %} - ForumGroupInfo object of the forum group containing the given forum.

{% Subscriber %} - ForumSubscriptionInfo object representing subscription of the recipient to the given forum. Only available for the New post template.