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
- Spam Filtering
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" />
- Remove a CSModule
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.
- 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.
CSModules are listed in the communityserver.config file or optionally through a communityserver_override.config file, as shown in the following example:
- <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.
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.
- 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.