Event Based Modules

Telligent's platform raises a number of events that developers can plug into to extend behaviors or alter content. An example, would be connecting to the event raised when content is posted to validate that the content is not SPAM. These event based extensibility modules are also referenced as CS Modules.

CSModules allow you to plug into the Telligent Evolution Platform and run your own code when certain events happen. In fact, CSModules drive a lot of the Telligent Evolution platform functionality (77 are used out of the box). This means you can remove or replace the Telligent Evolution platform functionality without having to touch the source code. Examples of functionality implemented with CSModules include:

Activity Message Logging
Email Notification
Points
Spam Filtering

Events

There are three different types of events you can hook into.

Creating a CSModule

To create a CSModule you need to create a class that implements the CommunityServer.Components.ICSModule interface. This interface has one method, Init, with two parameters:

CSApplication –Contains CSApplication Events to hook into
XmlNode –Node that was used to register the CSModule for use with custom configuration options

All events must be wired up in the Init method. These may come from the CSApplication class passed into the method, or events in a separate class.

Once you’ve created your CSModule, you need to register it so that your Telligent Evolution platform application knows to use it. CSModules are registered in the <CSModules> section of the communityserver.config file. To add your custom module, just add a new node to this section, or preferably your override file, with the following markup:

<add name="Your_Module_Name" type="Namespace.ClassName, Assembly" />

General tips and tricks

Register / remove CSModules with Override Files

For a more detailed explanation of override files and why you should use them, read this article on How to: Use Override Files. Essentially by using a communityserver_override.config file to register CSModules you make upgrading to future versions of Community Server easier.

Below are two example overrides for adding and removing CSModules.

Add a CSModule

<Override xpath="/CommunityServer/CSModules" mode="add">
   <add name="Your_Module_Name" type = "Namespace.ClassName, Assembly" />
</Override>

Remove a CSModule

<Override xpath="/CommunityServer/CSModules/add[@name='ModuleName']"
          mode="remove" />

Configuration

You may have noticed that the CSModule Init event has two parameters: the CSApplication which provides the events to hook into and an XmlNode. This is the xml node which you used to register the module in the <CSModules>section of the communityserver.config file.

This means that you don’t have to hard code variables into your CSModule, but instead you can can specify them on the XMLNode you use to register your module. This means you can change the variables at a later date without having to recompile your module.

Troubleshooting CSModules

Make sure your Module class is marked as public.
Changes made to the communityserver.config file (or to the communityserver_override.config file) may not take effect until your web site is restarted. You can force a restart by touching the web.config file.
Check the Telligent Evolution event logs. Events are recorded there if CSModules can’t be loaded.

Mechanics of CSModules

CSModules are found in the communityserver.config file and are loaded into a Telligent Evolution platform instance when started. There are simple rules for how a CSModule is loaded into a site.

communityserver.config file

CSModules are listed in the communityserver.config file or optionally through a communityserver_override.config file, as shown in the following example:

<CSModules>
    ...
    <add
        name="CSExceptionModule"
        type="CommunityServer.Components.CSExceptionModule, CommunityServer.Components"
        />
    ...
</CSModules>

<clear /> - Clears the internal collection of all modules if any were previously added. There are no other options here. This is useful when an override file (such as communityserver_override.config) is used.
<remove name="ModuleName" /> Removes the particular module if it was previously added. The module removed is the one specified in the name attribute. If name is not specified or is empty, nothing is altered.
<add enabled="true" name="ModuleName" type="Type, Assembly" /> Adds a specific module to the list of modules.
- If enabled is omitted or the attribute value does not equal the literal string "false" the default value is true and the module will attempt to be added to the list of modules.
- If name is omitted or empty no module will attempt to be added. An exception will be logged in this case.
- If type is omitted or empty no module will attempt to be added. An exception will be logged in this case.

ICSModule interface

A CSModule must implement the ICSModule interface. It contains a single method for initialization:

public interface ICSModule
{
    voidInit(CSApplicationcsa, XmlNode node);
}

The add node is passed into this method so additional interrogation can be processed in the xml node.

Miscellaneous notes

An attempt to load a CSModule two or more times will result in an exception.
If the type cannot be found, an exception will be thrown.
If the type does not implement ICSModule, an exception will be thrown.
if an unhandled exception is thrown from the Init method, an exception will be thrown.

Developer Space